Self-hosted sandboxes for AI coding agents — MIT, E2B-style Python API, Docker or Firecracker isolation.
Formerly sketched as “Spark”; renamed to Cell to avoid collision with Apache Spark.
A Cell is a disposable execution workspace: checkout code, install deps, build/test, snapshot, destroy — while reusable caches survive. You run the control plane; data stays on your hosts.
Start here: docs/quickstart.md · Support: docs/ops/SUPPORT.md
| Path | Command |
|---|---|
| Docker (default) | go build -o bin/celld ./cmd/celld && ./bin/celld serve --mode=all --environments ./environments |
| MicroVM | ./scripts/setup-microvm.sh then CELL_RUNTIME=microvm ./bin/celld serve … |
| Python SDK | pip install -e sdk/python → Sandbox.create / commands.run / files.* / snapshot |
| MCP (Cursor) | pip install -e integrations/mcp → cell-mcp |
| DeepSeek Harness | dsh plugin add ./integrations/dsh-cell |
| Cell | Typical hosted sandbox | |
|---|---|---|
| License / ops | MIT, you operate | Usage SaaS (+ optional OSS runtime) |
| Isolation | Hardened Docker or Firecracker microVM | Usually Firecracker fleet |
| Egress | none / allowlist + audit log |
Vendor policy |
| Snapshots | Workspace tar restore (snapshot_id) |
Often memory pause/fork |
| Fit | Self-host, air-gap-ish, DSH/Cursor plugins | Zero-ops cloud |
Isolation story and diagrams: ARCHITECTURE.md · MicroVM design: internal/worker/runtime/microvm/DESIGN.md.
- Control plane — HTTP Agent API, scheduler, meta store, TTL reaper
- Workers — create / exec / destroy / snapshot; local or remote
- Source —
git clone --mirror+ worktree into the workspace - Runtime — Docker (default), host (dev), or
CELL_RUNTIME=microvm - Caches — durable host dirs; env templates declare mounts
- Network —
default|none|allowlist(cell-egress)
Module: github.com/YanChao1999/Cell · version 0.8.1-dev (post-0.8.0).
export PATH=$HOME/.local/bin:$HOME/.local/go/bin:/usr/local/go/bin:$PATH
go build -o bin/celld ./cmd/celld
go build -o bin/cell ./cmd/cell
CGO_ENABLED=0 go build -o bin/cell-egress ./cmd/cell-egress
CGO_ENABLED=0 go build -o bin/cell-guest-agent ./cmd/cell-guest-agent
go test ./internal/worker/... ./internal/control/... ./internal/version/./bin/celld serve --mode=all \
--cell-home ~/.cell \
--environments ./environments \
--cache-dir ~/.cell/cache \
--socket ~/.cell/celld.sock| Flag | Default |
|---|---|
--cell-home |
~/.cell |
--repos |
<cell-home>/repos |
--workspaces |
<cell-home>/workspaces |
--cache-dir |
<cell-home>/cache |
--state-dir |
<cell-home>/state |
--environments |
./environments |
--socket |
<cell-home>/celld.sock |
Without Docker, celld logs a host-fallback line (dev/CI only).
./scripts/setup-microvm.sh # firecracker + jailer + kernel + ~11MiB rootfs
./scripts/microvm-smoke.sh # artifact check; skips guest boot without /dev/kvm
export PATH="$HOME/.cell/runtime/microvm:$PATH"
export CELL_RUNTIME=microvm
export CELL_MICROVM_DIR=$HOME/.cell/runtime/microvm
export CELL_MICROVM_JAILER=$HOME/.cell/runtime/microvm/jailer
# Dev only: export CELL_MICROVM_ALLOW_UNJAILED=1CI uploads a cell-microvm-rootfs artifact from the Ultra-tiny MicroVM rootfs job (14-day retention).
pip install -e sdk/pythonimport asyncio
from cell import Sandbox
async def main():
async with await Sandbox.create(environment="python-3.12") as sbx:
await sbx.files.write("hi.py", "print(42)\n")
print((await sbx.commands.run("python hi.py")).stdout)
snap = await sbx.snapshot()
print(snap.id)
asyncio.run(main())- MCP — integrations/mcp (
cell_create/cell_exec/cell_snapshot/cell_kill/cell_list) - DeepSeek Harness — integrations/dsh-cell
On start, celld ensures well-known dirs under --cache-dir:
go-mod, go-build, pip-cache, python-venv, zephyr-modules, west-cache, yocto-downloads, yocto-sstate, ccache
Env templates declare mounts (see environments/).
Default Cell TTL is 30m (override with create ttl). The reaper ticks on start and every 15s.
docker compose up --build -d
./scripts/cluster-smoke.sh
# Optional Grafana/Prometheus: docker-compose.obs.yml- Support matrix: docs/ops/SUPPORT.md
- Restart / rolling: docs/ops/PLAYBOOK.md
- Upgrades: docs/ops/UPGRADE.md
- Release cut: docs/ops/RELEASE.md (
./scripts/release.sh 0.8.0when ready) - Changelog: CHANGELOG.md
- Threat model: docs/security/THREAT_MODEL.md
- Escape checklist: docs/security/ESCAPE_CHECKLIST.md
- Tech debt: TECH_DEBT.md