https://github.com/dotbrains/eden
Python orchestrator for AI coding agents in sandboxed worktrees.
https://github.com/dotbrains/eden
agents claude-code codex docker podman python sandbox worktree
Last synced: 15 days ago
JSON representation
Python orchestrator for AI coding agents in sandboxed worktrees.
- Host: GitHub
- URL: https://github.com/dotbrains/eden
- Owner: dotbrains
- License: other
- Created: 2026-05-01T02:54:52.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-06-10T08:01:29.000Z (15 days ago)
- Last Synced: 2026-06-10T09:23:49.507Z (15 days ago)
- Topics: agents, claude-code, codex, docker, podman, python, sandbox, worktree
- Language: Python
- Homepage:
- Size: 928 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
- Agents: AGENTS.md
Awesome Lists containing this project
README
# Eden
[](https://github.com/dotbrains/eden/actions/workflows/ci.yml)
[](https://pypi.org/project/eden-agent/)
[](https://pypi.org/project/eden-agent/)
[](LICENSE)
Python orchestrator for AI coding agents in sandboxed git worktrees.
Eden creates a fresh git worktree on a new branch, runs a coding agent (Claude Code, Codex, opencode, pi, or any line-streaming CLI) inside a sandbox (Docker, Podman, isolated, Daytona, Vercel, or forkd microVMs), captures its output, and commits the changes back. You get a branch with one clean commit per iteration, ready to review or merge.
```mermaid
flowchart LR
Repo[(Host repo)] --> WT[Fresh worktree
on new branch]
WT --> SB[Sandbox
docker • podman • isolated
daytona • vercel • forkd • no_sandbox]
SB --> Agent[Coding agent
claude_code • codex
opencode • pi • cli_agent]
Agent -->|stdout stream| Loop{iteration loop}
Loop -->|commit per iteration| Branch[Eden branch]
Loop -->|next iteration| Agent
Branch --> Repo
```
## Install
```bash
pip install eden-agent
```
Requires Python 3.11+.
## Quick example
The `simulated_agent` runs without any external CLI installed. Run this from inside a git repository:
```python
from pathlib import Path
from eden import run, simulated_agent
from eden.sandboxes.no_sandbox import provider as no_sandbox
result = run(
cwd=Path.cwd(),
sandbox=no_sandbox(),
agent=simulated_agent(
output="hello from the simulated agent\nCOMPLETE\n",
),
prompt="ignored by the simulated agent",
max_iterations=1,
)
print(f"branch: {result.branch}")
print(f"iterations: {len(result.iterations)}")
```
For a real agent, scaffold a project:
```bash
eden init --sandbox docker --agent claude-code --yes
cp .eden/.env.example .env # then fill in API keys
docker build -t eden:$(basename $(pwd)) -f .eden/Dockerfile .
python .eden/main.py
```
## Development with Flox
Eden uses [Flox](https://flox.dev) in two distinct ways — don't conflate them:
1. **The repo dev toolchain** — the [`.flox/`](.flox/) environment that sets up *your* machine to work on Eden.
2. **Per-agent runtimes** — an optional, separate environment each agent declares for *its own* CLI.
### Repo dev toolchain
On Linux/macOS the repo ships a declarative, lockfile-pinned dev environment under [`.flox/`](.flox/). With Flox installed:
```bash
flox activate # provisions toolchain + builds .venv on first run
pytest -m "unit or e2e"
pre-commit run --all-files
```
`flox activate` provides Python 3.11/3.12/3.13, git, gh, the docker/podman clients, pre-commit, and make, then builds `.venv` via `pip install -e ".[dev]"`. Pick the interpreter with `EDEN_PYTHON` (e.g. `EDEN_PYTHON=python3.12 flox activate`; defaults to `python3.11`).
Flox is Linux/macOS only — on Windows, install directly with `python -m pip install -e ".[dev]"`. See [`AGENTS.md`](AGENTS.md#setup-and-development-commands) for the full command list.
### Per-agent runtimes
Separately, each **agent** can declare its own Flox runtime via `flox_env=` on its factory. Eden then runs that agent's CLI inside `flox activate -d -- `, so the agent gets a declared, lockfile-pinned toolchain instead of inheriting the host's. See [Agents — Per-agent Flox runtime](docs/agents.md#per-agent-flox-runtime).
## Documentation
Full documentation lives in [`docs/`](docs/README.md):
- [What is Eden?](docs/what-is-eden.md) — positioning and feature matrix
- [Quick start](docs/quick-start.md) — five-minute tour
- [Tutorial: build your first agent loop](docs/tutorial-first-loop.md) — 10-minute walkthrough that ends with a real agent fixing a real bug
- [Python API reference](docs/python-api.md) — every name importable from `eden`
- [How it works](docs/how-it-works.md) — branch strategies, sandbox lifecycle, iteration loop
- [Sandbox providers](docs/sandbox-providers.md) — seven provider catalog
- [Agents](docs/agents.md) — six agent factories
## License
[PolyForm Shield 1.0.0](LICENSE).