You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
A containment environment for AI agents that can write and execute code. Built for researchers, alignment engineers, and teams building autonomous systems who need **observability, rollback, and human oversight** — not black-box execution.
8
6
9
7
---
10
8
11
-
See [AGENTS.md](AGENTS.md) for the active code-writing agent profile.
9
+
See [TODO.md](TODO.md) for roadmap | [AGENTS.md](AGENTS.md) for agent profile
12
10
13
-
## About
11
+
## Why REPLOID?
14
12
15
-
Reploid is a **self-modifying AI substrate** that demonstrates recursive self-improvement ([RSI](https://en.wikipedia.org/wiki/Recursive_self-improvement)) in a browser environment.
13
+
AI agents that write code are powerful but dangerous. Most frameworks give agents unrestricted filesystem access, shell execution, or Docker root — then hope nothing goes wrong.
16
14
17
-
**How:**The agent reads code from its VFS → analyzes & improves it → writes back to VFS → hot-reloads → evolves.
15
+
REPLOID takes a different approach: **everything runs in a browser sandbox**with transactional rollback, pre-flight verification, and human approval gates. The agent can modify its own tools, but every mutation is auditable and reversible.
18
16
19
-
The agent's "brain" is data in [IndexedDB](https://developer.mozilla.org/en-US/docs/Web/API/IndexedDB_API). It can modify this data (its own code) while running.
17
+
**Use cases:**
18
+
-**AI safety research** — Study agent behavior in a contained environment
19
+
-**Model comparison** — Arena mode runs multiple LLMs against the same task, picks the best verified solution
20
+
-**Self-modification gating** — Test proposed code changes before committing them
21
+
-**Alignment prototyping** — Experiment with oversight patterns before deploying to production
20
22
21
-
---
23
+
## How It Works
24
+
25
+
The agent operates on a Virtual File System (VFS) backed by IndexedDB. It can read, write, and execute code — but only within the sandbox. All mutations pass through a verification layer that checks for syntax errors, dangerous patterns, and policy violations.
22
26
23
27
## Architecture
24
28
@@ -29,45 +33,55 @@ graph TD
29
33
Tools --> VFS[(Virtual File System)]
30
34
31
35
subgraph Safety Layer
32
-
Tools --> Worker(Verification Worker)
33
-
Worker -.->|Verify| VFS
36
+
Tools --> Verify[Verification Manager]
37
+
Verify --> Worker(Web Worker Sandbox)
38
+
Worker -.->|Check| VFS
39
+
Arena[Arena Harness] --> Verify
34
40
end
35
41
36
-
subgraph Capability
37
-
Agent --> Reflection[Reflection Store]
38
-
Agent --> Persona[Persona Manager]
42
+
subgraph Observability
43
+
Agent --> Audit[Audit Logger]
44
+
Agent --> Events[Event Bus]
39
45
end
40
46
```
41
47
42
-
### Key Components
48
+
### Safety First
43
49
44
-
1.**Core Substrate**:
45
-
*`agent-loop.js`: The main cognitive cycle (Think -> Act -> Observe).
46
-
*`vfs.js`: Browser-native file system using IndexedDB.
47
-
*`llm-client.js`: Unified interface for Cloud (Proxy) and Local (WebLLM) models.
50
+
1.**Verification Manager**: All code changes pass through pre-flight checks in an isolated Web Worker. Catches syntax errors, infinite loops, `eval()`, and other dangerous patterns before they reach the VFS.
48
51
49
-
2.**Safety Mechanisms**:
50
-
***Verification Worker**: Runs proposed code changes in a sandboxed Web Worker to check for syntax errors and malicious patterns (infinite loops, `eval`) before writing to VFS.
51
-
***Genesis Factory**: Creates immutable snapshots ("Lifeboats") of the kernel for recovery.
52
+
2.**VFS Snapshots**: Transactional rollback. Capture state before mutations, restore if verification fails. No permanent damage from bad agent decisions.
52
53
53
-
3.**Tools**:
54
-
*`code_intel`: Lightweight structural analysis (imports/exports) to save context tokens.
55
-
*`read/write_file`: VFS manipulation.
56
-
*`python_tool`: Execute Python via Pyodide (WASM).
54
+
3.**Arena Mode**: Test-driven selection for self-modifications. Multiple candidates compete, only verified solutions win. Located in `/testing/arena/`.
57
55
58
-
---
56
+
4.**Circuit Breakers**: Rate limiting and iteration caps (default: 50 cycles) prevent runaway agents. Automatic recovery on failure.
59
57
60
-
## RSI Levels
58
+
5.**Audit Logging**: Every tool call, VFS mutation, and agent decision is logged. Full replay capability for debugging and analysis.
61
59
62
-
1.**Level 1 (Tools):** Agent creates new tools at runtime using `create_tool`.
63
-
2.**Level 2 (Meta):** Agent improves its own tool creation mechanism.
64
-
3.**Level 3 (Substrate):** Agent re-architects its entire loop or memory system.
|`verification-manager.js`| Pre-flight safety checks in sandboxed worker |
68
+
|`arena-harness.js`| Competitive selection for code changes |
65
69
66
70
---
67
71
68
-
## RSI Examples
72
+
## Self-Modification Research
73
+
74
+
REPLOID is designed to study [recursive self-improvement](https://en.wikipedia.org/wiki/Recursive_self-improvement) (RSI) safely. The agent can modify its own code, but every change is verified, logged, and reversible.
75
+
76
+
### Modification Levels
69
77
70
-
### Example 1: Tool Creation (Level 1)
78
+
| Level | Description | Safety Gate |
79
+
|-------|-------------|-------------|
80
+
|**L1: Tools**| Agent creates new tools at runtime | Verification Worker |
|**L3: Substrate**| Agent modifies core loop or memory | Human Approval (planned) |
83
+
84
+
### Example: Tool Creation (L1)
71
85
**Goal:** "Create a tool that adds two numbers"
72
86
73
87
```
@@ -86,7 +100,7 @@ graph TD
86
100
[Agent] ✓ Goal complete
87
101
```
88
102
89
-
### Example 2: Meta-Tool Creation (Level 2)
103
+
### Example: Meta-Tool Creation (L2)
90
104
**Goal:** "Build a system that creates tools from descriptions"
91
105
92
106
```
@@ -114,7 +128,7 @@ graph TD
114
128
[Agent] I just created a tool-creating tool! (Level 2 RSI)
115
129
```
116
130
117
-
### Example 3: Substrate Modification (Level 3)
131
+
### Example: Substrate Modification (L3)
118
132
**Goal:** "Analyze your tool creation process and optimize it"
119
133
120
134
```
@@ -140,52 +154,48 @@ graph TD
140
154
141
155
---
142
156
143
-
## Landscape
157
+
## Comparison
144
158
145
-
Reploid lives in a small but rapidly evolving ecosystem of self-improving agents. We intentionally share compute constraints (browser, IndexedDB) while diverging on safety architecture and ownership.
|**Inspectable**| Full source | Full source | Partial | Closed |
146
167
147
-
### WebLLM (MLC AI)
148
-
WebLLM is the inference engine reploid can stand on: deterministic WebGPU execution. It excels at raw token throughput and versioned stability but offers no tools, memory, or self-modification. REPLOID layers VFS, a tool runner, PAWS governance, and substrate/capability boundaries above WebLLM so passive inference becomes an auditable agent capable of planning, testing, and rewriting itself safely.
168
+
**REPLOID's niche:** Safe experimentation with self-modifying agents. Not the most powerful agent framework — the most observable and recoverable one.
149
169
150
-
### OpenHands (formerly OpenDevin)
151
-
OpenHands embraces Docker power (shell, compilers, sudo) to tackle arbitrary repos, yet that freedom kills safety—the agent can brick its container with a single bad edit. REPLOID trades GCC for transactional rollback: everything lives inside a browser tab, checkpoints live in IndexedDB, and humans approve cats/dogs diffs before mutations land. We prioritize experimentation accessibility and undo guarantees over unrestricted OS access.
170
+
---
152
171
153
-
### Gödel Agent
154
-
Gödel Agent explores theoretical RSI by letting reward functions and logic rewrite themselves. It is fascinating math, but it lacks persistent state management, tooling, or human guardrails, so "reward hacking" is inevitable. REPLOID focuses on engineering: reproducible bundles, hot-reloadable modules, and EventBus-driven UI so observers can inspect every mutation. We sacrifice unconstrained search space for transparency and hands-on controllability.
172
+
## Research Questions
155
173
156
-
### Devin (Cognition)
157
-
Devin shows what proprietary, cloud-scale orchestration can deliver: GPT-4-class reasoning, hosted shells, and long-running plans. But it is a black box—you cannot audit, fork, or run Devin offline. REPLOID is the opposite: a glass-box brain stored locally, fully inspectable and modifiable by its owner. We bet that sovereign, user-controlled RSI will outpace closed SaaS once users can watch and influence every self-improvement step.
1.**Containment** — Can browser sandboxing provide meaningful safety guarantees for code-writing agents?
177
+
2.**Verification** — What static/dynamic checks catch dangerous mutations before execution?
178
+
3.**Selection** — Does arena-style competition improve agent outputs vs. single-model generation?
179
+
4.**Oversight** — What human-in-the-loop patterns balance safety with agent autonomy?
165
180
166
-
**Why REPLOID is different:** Explores the "Ship of Theseus" problem in a tab. Capabilities can mutate aggressively, but the substrate remains recoverable thanks to immutable genesis modules, and IndexedDB checkpoints.
181
+
These are open questions. REPLOID is infrastructure for exploring them, not answers.
167
182
168
183
---
169
184
170
-
## Philosophy
171
-
172
-
Reploid is an experiment in [**substrate-independent RSI**](https://www.edge.org/response-detail/27126):
185
+
## Quick Start
173
186
174
-
- The agent's "brain" is just data in IndexedDB
175
-
- The agent can modify this data (its own code)
176
-
- The original source code (genesis) is the evolutionary starting point
177
-
- Every agent instance can evolve differently
178
-
179
-
**Analogy:**
180
-
-**DNA** = source code on disk (genesis)
181
-
-**Organism** = runtime state in IndexedDB (evolved)
0 commit comments