Skip to content
YanChao1999Public

About

A onetime agent use VM.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

Cell

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

Why Cell (vs cloud sandboxes)

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.

Architecture (short)

  • 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).

Build

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/

Run (mode=all)

./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).

MicroVM (one shot)

./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=1

CI uploads a cell-microvm-rootfs artifact from the Ultra-tiny MicroVM rootfs job (14-day retention).

Python SDK

pip install -e sdk/python
import 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())

Integrations

Caches

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/).

TTL reaper

Default Cell TTL is 30m (override with create ttl). The reaper ticks on start and every 15s.

Cluster / observability

docker compose up --build -d
./scripts/cluster-smoke.sh
# Optional Grafana/Prometheus: docker-compose.obs.yml

Ops & security

About

A onetime agent use VM.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages