
cocoon
Self-hosted platform for running AI coding agents (Claude Code, Codex, …) in isolated sandboxes – web UI, CLI, API and MCP
Install with your AI
Paste into Claude Code, Cursor, or any agent — it reads the repo and wires the tool into your project.
Install and set up cocoon (git-clone project) into my current project. Found on https://claudeers.com/cocoon Repo: https://github.com/adziendziolD/cocoon Homepage/docs: — Detected install method: git-clone → git clone https://github.com/adziendziolD/cocoon Category: mcp-servers. Platforms: cli, api, desktop, web. Read the repo's README for exact setup and env vars, then install it and wire it into my project. Claudeers Health Verdict: active; community-verified: false. Confirm the source before running anything.
git clone https://github.com/adziendziolD/cocoon
// compatibility
| Platforms | cli, api, desktop, web |
|---|---|
| Operating systems | — |
| AI compatibility | claude |
| License | MIT |
| Pricing | open-source |
| Language | TypeScript |
CoCoon
Website with screenshots: https://adziendziold.github.io/cocoon/
CoCoon is a self-hosted platform for running AI coding agents – Claude Code, OpenAI Codex, plain shells or any other CLI – in isolated sandboxes on your own server, and for steering them remotely. It ships with a beginner-friendly web UI (English and German – follows the browser language), a CLI, an HTTP/WebSocket API and an MCP server, so that other agents can orchestrate it too. The design is inspired by herdr.
Browser (web UI) · CLI · scripts · Claude Code via MCP
│ HTTPS (reverse proxy / VPN / SSH tunnel)
┌───────────────────▼───────────────────────────────────────────┐
│ cocoond – control plane (Node.js, 127.0.0.1:7420) │
│ web UI · REST/RPC · WebSocket events · terminal attach · MCP │
└───────┬───────────────────────────────────────────┬───────────┘
│ Docker API │ policy
▼ ▼
sandbox containers (one per workspace) egress proxy container
└ tmux ─ agent processes ├ domain allowlist
└ /workspace (git repo + baseline) └ credential proxy (API keys)
Contents
- Features
- Quickstart
- Using the web UI
- Core concepts
- Sandbox backends
- Network modes & security
- Credentials and custom API providers
- Environment variables (.env injection)
- Several repositories per sandbox
- Shared services: databases & mocks
- Servers & ports: previews and sharing
- Orchestration: workspaces, tasks & workflows
- Cockpit
- Agent types
- Agent status detection
- Languages
- Updates
- CLI
- MCP integration
- HTTP & WebSocket API
- Configuration
- Deployment
- Project structure
- Development
- Limitations & roadmap
- Support
- License
Features
| Onboarding wizard | After installation a guided, full-screen wizard walks new users through system check, AI access (with key verification), GitHub, safety defaults, the first sandbox and the first agent |
| Cockpit | herdr-style multi-agent window: tiled live terminals (split, resize, maximize), workspace tree, attention queue, broadcast input, keyboard control, layouts saved per workspace |
| Scheduled agents | Agents that run on a schedule (cron + time zone) in a workspace – templates to run every check of a project (format, lint, typecheck, unit/integration tests, build, audit), update dependencies or do a security check. Every run is a task with a report; runs without findings close themselves, findings land in Review with a notification |
| Orchestration | Workspaces, a task board (backlog → queued → running → review → done), multi-stage workflows (e.g. plan → build → review) with approvals, review feedback loop, dependencies, auto-run with parallelism limits, webhook notifications |
| Web UI | Setup checklist, sandbox wizard, live in-browser terminals, file browser/editor, diff viewer, commit/push/pull request, activity log, every setting – written for non-technical users |
| Sandbox backends | Docker, Podman (rootless, no daemon) or bubblewrap (lightweight Linux process sandboxes, no images, start in ~0.3 s) – picked automatically. Containers are hardened (non-root, no capabilities, no-new-privileges, CPU/RAM/PID limits) with optional gVisor or Kata/Firecracker runtimes |
| Small footprint | Slim base image under 250 MB (Debian, no Node.js); agent CLIs and their Node.js runtime live in a shared, read-only toolbox that is installed once and updated without rebuilding images |
| Network control | Per sandbox: no internet, allowlisted domains only (via egress proxy, default), or open internet. Blocked connections are logged and can be allowed with one click |
| Credential proxy | API keys stay on the server – sandboxes only see placeholders, the proxy adds the real key on the way out |
| Many agents | Claude Code, OpenAI Codex, OpenCode, Pi, Qwen Code, Gemini CLI and plain shells – switch the agent of a sandbox at any time, with handover of task, changes and last output |
| Local LLMs | Each agent is started with the right parameters for your own model server; CoCoon detects which APIs a server speaks and translates Anthropic Messages / OpenAI Responses to Chat Completions, so Claude Code and Codex work with chat-only servers (llama.cpp, vLLM, LM Studio, …) |
| Custom APIs | Bring your own model endpoint (Anthropic- or OpenAI-compatible: company gateway, LiteLLM, OpenRouter, Ollama, DeepSeek, …) or give agents access to any HTTP API, with model selection and connection test |
| Previews & ports | Servers that agents start (dev servers, APIs, docs) are detected automatically and can be opened as an authenticated preview in the browser or shared on the network – WebSockets/HMR included |
| Shared services | One click starts PostgreSQL, MySQL/MariaDB, MongoDB, Redis or the mocks WireMock (HTTP APIs) and Mailpit (email) for all sandboxes – or connects your own server. Every sandbox gets its own database and user; agents get the connection as env vars and may create schemas and test databases freely |
| Agent status | working / blocked / done / idle / exited, from native hooks (Claude Code, Codex) plus screen heuristics |
| Persistence | Agents run in tmux inside the sandbox – they survive control-plane restarts and client disconnects |
| Results | Changes leave the sandbox only as a git patch, a download, or a pushed branch + GitHub pull request |
| Integrations | CLI, typed TypeScript client, REST/RPC, WebSocket events, MCP server |
| Languages | UI, server messages and CLI in English and German (browser language, English fallback) |
| Zero-config start | Admin token, internal network, egress proxy and sandbox image are set up automatically on first start |
Quickstart
Requirements: Node.js ≥ 24, pnpm and one sandbox backend: Docker, Podman or – on Linux – bubblewrap + tmux (see Sandbox backends).
git clone <repository-url> cocoon && cd cocoon
pnpm setup # install dependencies and build the web UI
pnpm start # start cocoond on 127.0.0.1:7420
On first start the console prints a login link, and the token is also stored in .data/admin-token.txt:
CoCoon is running: http://127.0.0.1:7420
Log in: http://127.0.0.1:7420/?token=cct_…
Open the link. In the background CoCoon prepares the sandbox backend – for Docker/Podman it creates the internal network, builds and starts the egress proxy and builds the slim sandbox image – and installs the agent toolbox (Claude Code, Codex). This takes a few minutes the first time.
On a fresh installation the onboarding wizard opens automatically and guides you through the setup:
| Step | What happens |
|---|---|
| 1. Welcome | What CoCoon is, language choice (optionally also for server messages) |
| 2. System check | Live status of Docker, sandbox image (with build log) and egress proxy |
| 3. AI access | Anthropic API key, Claude subscription token, OpenAI API key or a custom API provider – keys are verified against the provider; rejected keys block the step |
| 4. GitHub (optional) | Token for private repositories, push and pull requests, with step-by-step instructions |
| 5. Safety & defaults | Default internet access and size for new sandboxes |
| 6. First sandbox | Name and optional repository – created right away |
| 7. First agent | Pick an available agent type, choose or write a first task, watch its live status |
| 8. Done | Summary, next steps, CLI/MCP tips |
Progress is derived from the server state and kept per browser tab, so you can leave and come back. Completing or skipping the
wizard is stored in settings.general.onboardingCompletedAt; installations that are already set up are never redirected. Run it
again anytime from Settings → General or the dashboard checklist.
Remote access: cocoond only listens on localhost. Use an SSH tunnel (ssh -L 7420:127.0.0.1:7420 user@server), a VPN, or a
TLS reverse proxy (see Deployment).
Step-by-step guides for beginners: English · Deutsch. Architecture and design details (German): docs/ARCHITECTURE.md.
Using the web UI
| Page | What you can do |
|---|---|
Onboarding (/onboarding) | Guided first-time setup (see Quickstart) |
| Overview | Setup checklist with a direct action per step, agents waiting for you, running agents, recent activity |
| Sandboxes | List and create sandboxes (wizard: project/repository → internet access → size → advanced: image, runtime, env vars) |
| Sandbox detail | Agents (start an agent with a task), Files (browse, edit, upload, download, new file/folder), Changes (diff, download patch, commit, push to GitHub, open a pull request), Console (run commands, open an interactive terminal), Manage (start/stop/delete) |
| Agent detail | Live terminal (type directly), status with plain-language explanation, "waiting for your decision" banner with Yes/No buttons, send messages, quick keys (Enter, Esc, Ctrl+C, arrows, Tab), stop |
| Agents | All agents across sandboxes, blocked ones first |
| Activity | Live log of everything that happened |
| Settings | General (language), Credentials / API keys, API providers, Agent types, Sandbox defaults (incl. image builds), Network & security (allowlist, credential proxy, blocked connections), Access & integrations (API tokens, MCP and CLI snippets), Advanced (status timings, git author) |
Everything updates live over a WebSocket. The sidebar and browser tab show how many agents are waiting for you.
Core concepts
- Sandbox – an isolated container with its own filesystem.
/workspaceis a git repository: either cloned from a URL (optionally a branch/tag/commit, private GitHub repos viaGITHUB_TOKEN) or empty. Acocoon-baselinetag marks the starting point, so all changes can be exported as a patch. Lifecycle:creating → running ⇄ stopped, pluserror/missing. - Agent – a CLI process in a tmux session inside a sandbox. Several agents can share one sandbox (e.g. planner + implementer).
- Agent type (profile) – how an agent is launched and which credentials/providers it gets (see Agent types).
- Secret – an API key or token stored on the server (
.data/state.json, mode 0600); falls back to environment variables. - API provider – a custom endpoint agents may use (see below).
- Settings – all runtime configuration, editable in the UI or via
settings.update.
Sandbox backends
CoCoon talks to sandboxes through a small driver interface, so the isolation technology is interchangeable:
| Backend | What it is | Footprint | Isolation | Notes |
|---|---|---|---|---|
| Podman | Container engine without a background daemon, runs rootless | small, no root service | containers (+ gVisor / Kata / krun runtimes) | uses Podman's Docker-compatible API socket |
| Docker | The standard container engine | daemon (~100 MB), root | containers (+ gVisor / Kata runtimes) | Docker Desktop on macOS/Windows |
| bubblewrap | Linux process sandboxes (namespaces, as used by Flatpak and Claude Code's own sandbox) | tiny – no daemon, no images | user/pid/ipc/uts/(net) namespaces, read-only host, no capabilities | Linux only; shares the host kernel and installed tools; no resource limits and "Restricted" network is not enforced (proxy is configured, but could be bypassed) |
Selection: COCOON_DRIVER=auto (default) uses an explicit DOCKER_SOCKET, then a Podman socket, then Docker, then bubblewrap.
Force one with COCOON_DRIVER=docker|podman|bwrap. The UI shows the active backend and its capabilities
(Settings → Sandbox defaults), and system.info reports driverKind and capabilities.
- Podman: enable the API socket – rootless
systemctl --user enable --now podman.socket(socket under$XDG_RUNTIME_DIR/podman/podman.sock) or rootfulsystemctl enable --now podman.socket. On macOS,podman machineworks too. Containers reach the host ashost.containers.internal. - bubblewrap:
apt install bubblewrap tmux git(ordnf install …); unprivileged user namespaces must be allowed (default on most distributions). Each sandbox is a directory under.data/sandboxes/<id>(workspace, home, tmp); the host system is mounted read-only, a long-running keeper (tmux server) per sandbox keeps agents alive across cocoond restarts, and the egress proxy runs as a local process on127.0.0.1:7431/7432(COCOON_PROXY_PORT). Sandbox options and secrets are passed tobwrapvia a file descriptor, so they never show up in the host's process list.
Agent toolbox: the agent CLIs – and the Node.js runtime they need – are not part of the sandbox image. They are installed once
(npm install -g --prefix /opt/agents …) into a Docker/Podman volume (cocoon-agents) or .data/agents for bubblewrap, and
mounted read-only at /opt/agents in every sandbox (PATH includes /opt/agents/bin, also in login shells; self-updaters are
disabled). Docker/Podman install with node:24-bookworm-slim and copy its node, npm, npx and corepack into the toolbox;
bubblewrap copies the Node.js that runs CoCoon. Install or update them in Settings → Sandbox defaults or via
image.build({ kind: "agents" }) – no image rebuild needed. A toolbox installed by an older CoCoon (without Node.js) is reinstalled
automatically on the next start.
Sandbox image variants (images/sandbox, Debian bookworm-slim, build argument TOOLCHAIN; pick one in
Settings → Sandbox defaults, image.build({ kind: "sandbox", variant }) or pnpm build:image[:db|:full]):
| Variant | Contents | Size |
|---|---|---|
slim (default) | bash, git, tmux, ripgrep, curl, jq, less, procps, CA certificates | < 250 MB (checked in CI) |
db | slim + database clients: psql, mysql/MariaDB, redis-cli – handy with shared services | + ~100 MB |
full | db + compilers (build-essential) and Python 3 for projects that build native code | + ~400 MB |
Debian rather than Alpine on purpose: the agent CLIs ship glibc binaries (Claude Code, Codex, OpenCode) and most projects' prebuilt
native modules assume glibc too. CI builds every variant, checks its contents and fails if slim reaches 250 MB; multi-arch
(amd64/arm64) builds are published as ghcr.io/<owner>/cocoon-sandbox:{slim,db,full} (.github/workflows/images.yml).
Agent secrets are written to a private file (mode 0600) that the agent's session sources and deletes immediately, so API keys
never appear in a command line (ps/docker top).
Network modes & security
| Mode | Implementation | Use for |
|---|---|---|
egress (default, "Restricted") | Docker/Podman: the sandbox is only attached to the internal network cocoon-internal (no gateway, no external DNS); the only way out is the egress proxy (HTTP(S)_PROXY is preset): allowlisted domains, ports 80/443, known sandboxes only. bubblewrap: proxy configured, not enforced | Normal work – agents can reach model APIs, GitHub, npm, PyPI |
open | Bridge network / host network, unrestricted internet | Projects that need arbitrary downloads |
none | No network at all | Untrusted code, offline analysis |
Egress proxy (images/egress-proxy, dependency-free Node.js, read-only container, no capabilities):
:3128forward proxy enforcing the domain allowlist (*.example.commatches subdomains). Denied attempts appear under Settings → Network & security with an "Allow" button.- Sandboxes are identified by a per-sandbox token (
Proxy-Authorization//t/<token>/path prefix) or, on the internal container network, by their IP. :8080credential proxy: agents callhttp://cocoon-proxy:8080/t/<token>/<route>/…; the proxy swaps placeholders (cocoon_<sandboxToken>_<SECRET>) for real keys or injects the provider's auth header, then forwards over TLS. A sandbox may only use a route after an agent using it was started there.- cocoond writes the policy to
.data/egress/policy.json; the proxy reloads it immediately and acknowledges the version, so e.g. a repository clone only starts once the proxy knows the new sandbox.
Sandbox hardening: non-root user, CapDrop: ALL, no-new-privileges, CPU/memory/PID limits, /tmp as tmpfs, init process,
RestartPolicy: unless-stopped. Optional runtimes (must be installed on the host and registered with Docker; the UI only offers
available ones): runsc = gVisor user-space kernel, kata-fc = Kata Containers with Firecracker microVMs.
Control plane: binds to 127.0.0.1 by default. API tokens are stored as SHA-256 hashes and compared in constant time.
Admin methods (settings, secrets, tokens, images) are not exposed via MCP. Git credentials are passed per command as GIT_CONFIG_*
variables and never written into the sandbox. Note: with Docker, cocoond needs the Docker socket, which is root-equivalent – run
it as a dedicated user on a dedicated host, or prefer rootless Podman / bubblewrap, which need no root at all.
Credentials and custom API providers
Built-in credentials (Settings → Credentials / API keys)
| Secret | Used by |
|---|---|
ANTHROPIC_API_KEY | Claude Code (via credential proxy in egress mode) |
CLAUDE_CODE_OAUTH_TOKEN | Claude Code with a Claude Pro/Max subscription (claude setup-token) |
OPENAI_API_KEY | Codex (via credential proxy in egress mode) |
GITHUB_TOKEN | Private repositories, push, pull requests (fine-grained token: Contents + Pull requests read/write) |
Any other secret name can be added and referenced by agent types or providers.
Custom API providers (Settings → API providers)
Use your own model endpoint instead of (or in addition to) the default access, or give agents access to any HTTP API.
| Kind | The agent receives | Typical targets |
|---|---|---|
anthropic | ANTHROPIC_BASE_URL, ANTHROPIC_API_KEY (or ANTHROPIC_AUTH_TOKEN for bearer auth), ANTHROPIC_MODEL | Company gateway, LiteLLM, DeepSeek, Bedrock proxy – for Claude Code |
openai | OPENAI_BASE_URL, OPENAI_API_KEY, OPENAI_MODEL (+ --model for Codex) | OpenRouter, Groq, Mistral, Ollama, vLLM – for Codex and other tools |
http | <PREFIX>_BASE_URL, <PREFIX>_API_KEY | Any REST API, e.g. internal services |
Each provider has a base URL, the name of the secret holding its key, an auth mode (bearer, x-api-key, custom header, none),
a list of models and a default model. The UI offers templates (OpenRouter, Ollama, LiteLLM, DeepSeek, Groq, Mistral, custom
Anthropic/OpenAI/HTTP) and a Test connection button (providers.test) that checks reachability and authentication from the
server and discovers available models – even before saving.
How it is wired:
- In
egressmode the base URL points to the credential proxy (http://cocoon-proxy:8080/p-<id>), which adds the real key. Inopenmode the agent talks to the provider directly. localhostin a base URL is rewritten tohost.docker.internal, so services on the server itself (e.g. Ollama) work.- Provider hosts are added to the egress allowlist automatically.
- If a profile uses an
anthropicprovider, the defaultANTHROPIC_API_KEYis not injected (same foropenai/OPENAI_API_KEY). - Assign providers per agent type (
providers,model) or per start (agent.spawn { providers, model }).
Environment variables (.env injection)
Projects need their own configuration – a Stripe test key, a database URL, a Sentry DSN, feature flags – to run their tests.
Define it once and CoCoon injects it into sandboxes and agents, instead of typing variables for every sandbox or committing a .env.
Levels (Workspace page → Settings, Sandbox page → Environment, cocoon env …); later levels override earlier ones:
| Level | Applies to | Identified by |
|---|---|---|
| Workspace | every sandbox of the workspace | workspace |
| Repository | every sandbox that clones the repository, in any workspace | the repository URL – https://github.com/o/r.git, [email protected]:o/r and ssh://[email protected]/o/r are the same repository |
| Sandbox | this sandbox | sandbox |
| Agent type | agents of that type | Settings → Agent types (env), as before |
The sandbox page shows the merged result with the origin of every value (and what it overrides). agent.spawn { env } and CoCoon's own
variables (credentials, provider wiring, COCOON_*) still come last. With several repositories in a sandbox, the agents get the
variables of all of them (later repository wins); each repository's .env file only gets its own level.
Two ways to inject, per variable (target):
env– environment variables of agents started afterwards and ofsandbox.exec(never in the container's own configuration, so not indocker inspect).file– a.envfile in the repository folder (/workspace/.env, or/workspace/<folder>/.envper repository; the path is configurable per level). CoCoon adds the file to the repository's.git/info/excludebefore it creates it, so it never appears ingit status, diffs, commits, patches or pushes. It is written with mode0600, starts with a# cocoon-managedline, and CoCoon never overwrites or removes a file without that line, never writes into a folder that is not a git repository and never into a.envthe repository tracks (all reported as skipped). Note that an agent can read the file – use the proxy for keys the agent does not need to see.both.
Updates: new agents get the current values immediately; the .env file is re-written when a sandbox is created or started and
before every agent start. Apply now (cocoon env apply, env.apply) updates a running sandbox without starting an agent.
Changing the file path of a level does not remove the file at the old path.
Secrets: values are encrypted at rest (AES-256-GCM; key in <data dir>/env.key, mode 0600, kept apart from state.json and bound
per variable), masked in the UI and API (env.get, env.resolve, sandbox.get, the activity log – only variables marked not secret show
their value) and never logged. The env.* methods are admin-only and not offered over MCP. Names starting with COCOON_ and the proxy
variables (HTTP_PROXY, HTTPS_PROXY, NO_PROXY, …) are reserved. Back up env.key together with state.json; without it the stored values
cannot be decrypted (they are skipped and have to be set again).
Credential proxy: mark a variable as API key for host X (proxyHost, e.g. api.stripe.com, optional port, http:// for internal APIs).
The sandbox gets a placeholder (cocoon_<token>_STRIPE_API_KEY) plus a base URL (STRIPE_BASE_URL, or baseUrlEnv) pointing at the
credential proxy; the proxy swaps the placeholder for the real value – in Authorization: Bearer …, other headers and Basic credentials –
only for requests to that host and only for that sandbox. The real value never enters the sandbox, not even in the .env file.
The application has to call the base URL (most SDKs have a setting for it); HTTPS traffic that bypasses it is a tunnel the proxy cannot rewrite.
Without a credential proxy (sandbox network none, or the API key protection switched off) such a variable is not injected at all
and flagged in the merged view – it is never handed over in plain text. Proxied variables are sandbox-wide: if two repositories define the
same proxied name, the later one wins everywhere.
pnpm cocoon env set --workspace ws_… STRIPE_KEY=sk_test_… --target both
pnpm cocoon env set --repo https://github.com/acme/api.git DATABASE_URL=postgres://…
pnpm cocoon env set --sandbox sb_… SENTRY_DSN --stdin < dsn.txt # keeps the value out of the shell history
pnpm cocoon env set --repo github.com/acme/api STRIPE_API_KEY=sk_test_… --proxy-host api.stripe.com
pnpm cocoon env set --sandbox sb_… --file-path config/.env.test # where the .env file goes
pnpm cocoon env import .env --repo github.com/acme/api [--target file] [--replace]
pnpm cocoon env ls --workspace ws_… # one level (secrets masked)
pnpm cocoon env ls --sandbox sb_… --merged # what the sandbox gets, with origins (--agent <type> to include it)
pnpm cocoon env rm --sandbox sb_… SENTRY_DSN
pnpm cocoon env apply sb_… # write the .env files now
Several repositories per sandbox
A platform made of several services (API, web app, workers, shared libraries …) often lives in several repositories. A sandbox can hold any number of them, so one agent can work across all of them at once:
/workspace
├── api/ ← https://github.com/acme/api.git
├── web/ ← https://github.com/acme/web.git (branch develop)
└── shared/ ← https://github.com/acme/shared-types.git
- Create: add more repositories in the sandbox wizard (+ Add another repository), in a workspace (all task
sandboxes get them) or with
--reporepeated on the CLI. Each one gets its own folder – derived from the URL or chosen freely (services/api). A single repository without a folder is still cloned into/workspaceitself. - Add later: Add repository on the sandbox page (
sandbox.add_repo,pnpm cocoon repo add), remove withsandbox.remove_repo. - Git per repository: status, commit, push and pull request work per folder (repository selector in the UI,
--repo <folder>on the CLI,repoparameter in the API/MCP). The Changes view shows all repositories; a combined patch has folder-prefixed paths.git.reposlists branch and number of changes per repository. - Agents know the layout: they start in
/workspaceand get a short note listing the folders and their remotes; Codex trusts every repository folder; when switching agents, the handover lists the changes per repository.
Servers & ports: previews and sharing
When an agent starts a server in a sandbox, it shows up under Sandbox → Ports within a few seconds (CoCoon reads the listening TCP ports of every running sandbox). From there:
- Open preview – opens the server in the browser, only for people logged in to CoCoon. The preview runs on its own host
name,
http://p<port>-<sandbox>.localhost:7420/(browsers resolve*.localhostto the local machine), orhttps://p<port>-<sandbox>.<COCOON_PREVIEW_DOMAIN>/with a wildcard domain behind your reverse proxy. When CoCoon is opened from another machine (e.g. via Tailscale Serve, where*.localhostwould point to your own computer) and no preview domain is set, the link is path-based instead:<CoCoon URL>/preview/p<port>-<sandbox>/(cookie scoped to that path, prefix stripped before it reaches the app and sent asX-Forwarded-Prefix; apps with absolute asset paths need a base path setting). The link contains a one-time token that is exchanged for a cookie valid for that preview only. The app seesHost: localhost:<port>, so dev servers that only allow localhost (e.g. Vite) work, and WebSockets / hot reload are proxied as well. - Share on the network – publishes the server on a host port (
http://<host-ip>:7550) for everyone who can reach the machine, without login. Opt-in per port, logged in the activity log, can be turned off entirely.
How it works: a small gateway container (cocoon-ports, runs in the egress-proxy image) sits on the internal network and the
bridge and publishes two host port ranges – 127.0.0.1:7500-7549 for previews and 0.0.0.0:7550-7599 for shared ports.
cocoond writes which host port goes to which sandbox port; changes apply immediately and close existing connections of a
closed port. Opened ports survive stopping and starting the sandbox and are removed with it.
Servers must listen on all addresses – npm run dev -- --host 0.0.0.0, python -m http.server --bind 0.0.0.0. Servers
bound to localhost only are listed as internal only; CoCoon tells agents about this in their notes.
pnpm cocoon ports ls <sandbox-id>
pnpm cocoon ports open <sandbox-id> 5173 # preview, prints a one-time link
pnpm cocoon ports open <sandbox-id> 5173 --shared # reachable on the network
pnpm cocoon ports close <sandbox-id> 5173
Available with Docker and Podman (not yet with bubblewrap), in network modes Restricted and Open.
Shared services: databases & mocks
Agents often need a database or a fake external API to run tests. Instead of installing one into every sandbox,
CoCoon runs them once on the server and gives every sandbox its own isolated slice
(Settings → Services, or pnpm cocoon services add postgres).
| Service | Kind | What each sandbox gets | Env vars for agents |
|---|---|---|---|
| PostgreSQL 17/16 | database | own database + user (sb_<id>), may create schemas and extra (test) databases | DATABASE_URL, POSTGRES_URL, PGHOST, PGPORT, PGUSER, PGPASSWORD, PGDATABASE |
| MySQL 8.4 / MariaDB 11 | database | own database + user, may create databases named sb_<id>_… | MYSQL_URL, MYSQL_HOST, MYSQL_PORT, MYSQL_USER, MYSQL_PASSWORD, MYSQL_DATABASE (DATABASE_URL if no PostgreSQL) |
| MongoDB 8/7 | database | own database + user (dbOwner) | MONGODB_URI, MONGO_URL |
| Redis 7/8 | database | own ACL user limited to keys/channels sb_<id>:* | REDIS_URL, REDIS_KEY_PREFIX |
| WireMock 3 | mock | own URL prefix /sb_<id>; its stubs are removed with the sandbox | MOCK_API_URL, WIREMOCK_URL, WIREMOCK_ADMIN_URL, MOCK_API_PREFIX |
| Mailpit | mock | shared mailbox: mail sent via SMTP never leaves the server, readable via API and web UI | SMTP_HOST, SMTP_PORT, SMTP_URL, MAILPIT_API_URL |
Every service also gets COCOON_<ID>_URL, so a second instance of the same kind (e.g. postgres-2) is usable too.
How it works
- Managed (default, Docker/Podman): CoCoon pulls the official image, starts
cocoon-svc-<id>with a data volume and a random admin password, joins it to the internal network (sandboxes reach it by its id, e.g.postgres:5432) and publishes its port on127.0.0.1only, for CoCoon itself and database tools on the server (Credentials for database tools in the UI,pnpm cocoon services credentials <id>). - External (databases): connect an existing server with an admin user that may create databases and users.
Container sandboxes reach it through a TCP relay in the egress proxy (so
localhost= the CoCoon server works even for restricted sandboxes); bubblewrap sandboxes connect directly. - Automatic per sandbox: services set to every sandbox are attached when a sandbox is created (choose others
in the sandbox dialog); new services can be attached to existing sandboxes. Deleting a sandbox drops its databases,
users, keys and stubs. Empty (
services reset) gives a sandbox a clean database with the same credentials. - Agents know about it: on start, agents get the env vars,
/opt/cocoon/services.envis sourced by shells, and a short "shared test services" section is written into each agent's user memory (~/.claude/CLAUDE.md,~/.codex/AGENTS.md, OpenCode, Pi, Gemini, Qwen). The sandbox image includespsql,mariadbandredis-cli. Running agents need a restart to see newly attached services. - One instance, not one per sandbox: each service runs once (e.g. PostgreSQL ~60 MB RAM); another sandbox only adds its own database (a few MB on disk).
- Paused when unused (default, per service): a managed service that no running sandbox has used for 10 minutes is stopped (status Paused, no memory used) and starts again automatically when an agent or a sandbox with that service starts – usually within seconds. Turn it off per service to keep it running.
- Restricted sandboxes get the service hosts in
NO_PROXY; sandboxes without network cannot use services. - Agents can manage their services themselves over MCP (
services_list,services_connections,services_attach,services_reset, …).
Isolation is meant for development and tests: sandboxes cannot read each other's databases, but they share the server's resources, and WireMock/Mailpit are shared by design (prefixes keep stubs apart).
Orchestration: workspaces, tasks & workflows
The orchestration logic runs in the server, so it keeps working when no browser is open and is available to the UI, the CLI, the API and MCP alike (a lead agent can orchestrate just like you).
Workspaces group sandboxes, agents and tasks – e.g. one per project or customer. A workspace can define a repository that is
cloned into task sandboxes, a network mode, and a sandbox strategy: per-task (every task gets its own sandbox – parallel and
isolated, default) or shared (all tasks work in one sandbox – an existing sandbox of the workspace is taken over before a new
one is created). Default agent type / workflow, autoRun and maxParallel complete the setup.
A task can also be pinned to an existing sandbox of its workspace (Sandbox in the task dialog; a running one is preselected).
When a task that got its own sandbox is accepted, CoCoon commits all changes, pushes them as branch cocoon/<task>-<id> and
removes the sandbox. If the push fails (e.g. no GitHub token), the task stays in Review and the sandbox is kept. Shared and
hand-picked sandboxes are kept.
Tasks live on a board and move through:
backlog ──▶ queued ──▶ running ──▶ review ──▶ done
▲ (auto-run) │ ▲ │
└──── stop ─────────────┘ └─reject─┘ (feedback goes to the agent) running ──▶ failed (agent error)
task.startcreates/uses the sandbox and spawns the agent; the task status then follows the agent: blocked agents setattention, a finished agent moves the task toreview(you look at the result), errors tofailedwith a note.task.approvecontinues with the next workflow stage or marks the taskdone;task.rejectsends your feedback to the agent (or a new agent of the same stage) and the task runs again.- Failed, but actually finished? If the agent of a
failedtask becomes active again or finishes after all (e.g. it was declared gone during a server restart, or you continued it in the cockpit or switched agents), the task follows it again.task.mark_finishedmoves afailedtask toreviewby hand, so you can approve it (or send it back). dependsOn– a task only starts when all its dependencies aredone.- Auto-run: in workspaces with
autoRun, queued tasks are started automatically (high priority first) up tomaxParallel. - Every stage run is recorded in
runs(stage, agent, outcome). Running tasks are reconciled after a server restart.
Task numbers and branches. Every workspace has a short key (derived from its name, e.g. FocusDigital → FD,
editable) and numbers its tasks: FD-1, FD-2, … The handle is shown on cards and in the drawer, and gives the task's git
branch FD-12-add-apple-pay – a sandbox created for a task works on it from the start, pushes and pull requests use it.
Prompts can use {{task.key}} and {{task.branch}}.
Code review when approving (workspace setting). Approving a finished task then starts review agents one after another
in the same sandbox instead of pushing right away. Each reviews the full diff, may fix small problems, and reports a verdict
(approved / changes_requested + summary) in a file outside the repositories.
- Changes requested (or no result) → the task goes back to Review with the summary; Request changes sends it to the working agent, Approve runs the review again.
- All approved → CoCoon commits, pushes the task branch and opens a pull request per changed repository (target: the configured base branch or the repository default; repositories outside GitHub are only pushed). A sandbox that belonged to the task alone is removed. The drawer shows the reviews and the pull request links.
- Review agent may push and open the pull request itself gives the last review agent the GitHub token (
GITHUB_TOKEN/GH_TOKEN) – off by default; all other review agents get the token removed. If no token is stored, the task goes back to Review with a clear note instead of starting the agent. Use a fine-grained token limited to the repositories. - Reviewers commit their own fixes (
Review fixes: …); their verdict file lives in<workspace>/.cocoon/, which is excluded from every repository.
GitHub access for agents. Agent types that list GITHUB_TOKEN in their secrets (Claude Code, Codex and OpenCode by
default) get the stored token in their environment, and CoCoon sets up a git credential helper for github.com, so plain
git push works for them. Remove GITHUB_TOKEN from an agent type (Settings → Agent types) to keep it away from that agent.
Workflows (Settings → Workflows) chain stages, each a fresh agent in the task's sandbox. Prompt templates may use
{{task}}, {{task.title}}, {{task.description}}, {{previous.output}} (last screen of the previous stage),
{{diff}} (changed files) and {{feedback}} (review feedback). Stages with approval pause in review until you approve.
Built-in: Plan → Build → Review (approve the plan before implementation) and Build → Review.
Scheduled agents (Schedules in the navigation, or the Schedules tab of a workspace) start a task on a schedule: "run all checks every night at 03:00", "look for dependency updates every Monday", or anything you write yourself.
- When: hourly / daily / weekdays / weekly / monthly in the UI, or any five-field cron expression
(
minute hour day month weekday, with lists, ranges, steps, names and@daily-style macros), evaluated in an IANA time zone (daylight saving time included). The dialog previews the next runs. - Templates prefill the instructions (editable): Run all checks – the agent discovers every check of the project (package scripts, Makefile, CI config, pyproject, Cargo, …) and runs formatting, linting, type checking, unit/integration tests, build and a dependency audit, without changing code; Update dependencies – lists outdated packages and vulnerabilities, applies patch/minor updates and security fixes, runs all checks, reverts what breaks, lists major updates with migration notes and commits; Security check; Own task.
- Each run is a task (
Name · 2026-10-17 03:00) that is started right away (independent of auto-run) with the schedule's agent type or workflow, in a fresh sandbox (per-task workspaces) or the shared sandbox. - Report: the last agent of a run writes
{"status": "ok" | "action_needed", "summary", "report"}to<workspace>/.cocoon/report/<task>.json(excluded from git; the path is also in$COCOON_REPORT_FILE, so a plain shell command can write it, e.g.pnpm test && echo '{"status":"ok"}' > "$COCOON_REPORT_FILE"). The task drawer shows it. - Auto-close (default on): runs whose report says
okare marked done and their sandbox is removed – no review needed. Findings, changed files or a missing report move the task to Review (notification "Scheduled run needs you"); approving it then works like any task (push, code review, pull request). - Overlap (default skip): no new run while the previous one is still queued, running or waiting for review, so the same task does not pile up; Run now can force an extra run. Runs missed while the server was down are made up once on start.
- Housekeeping: only the newest
keepRuns(default 10) finished runs are kept; older ones are deleted with their sandbox. The schedule list shows next/last run, the last result and a coloured history of recent runs.
Notifications (Settings → Notifications): an incoming webhook (Slack, Mattermost, Discord via /slack, or any JSON
endpoint) receives { text, content, event, url } when an agent is waiting for you, a task is ready for review, failed or done.
Messages use the server's default language; set COCOON_PUBLIC_URL to get links.
Cockpit
The cockpit (/cockpit) is the "agent window" for working with many agents at once: a tiled layout of live, interactive agent
terminals next to the workspace tree and the attention queue (blocked agents, tasks in review). Panes can be split, resized,
maximized and swapped; layouts are saved per workspace on the server (layout.get/save), so they look the same on every device.
- Rail: "Waiting for you" (blocked agents with Yes/No, tasks in review with Approve/Request changes), then the tree Workspace → Sandbox → Agent. Drag an agent onto a pane or click it to show it in the focused pane.
- Panes: live agent terminal, compact task board, attention list, or empty picker. Splitting, closing and swapping panes never restarts a terminal; dividers can be dragged. Presets: Grid (all running agents), 2 columns, Focus + sidebar.
- Broadcast: tick several pane headers and send one message to all of those agents.
- Board integration: task cards link to
/cockpit?agent=<id>; dragging cards on the board starts (→ Running), stops (Running → Backlog) or approves (Review → Done) tasks. - Only visible panes connect (max. 12 live terminals); below 1024 px the cockpit shows the attention list instead.
| Shortcut (Ctrl+Alt or ⌘+Alt) | Action |
|---|---|
| ← ↑ → ↓ | move focus to the neighbouring pane |
| 1–9 | jump to pane N |
| Enter | maximize / restore |
| D / W | split / close pane |
| G | auto-grid |
| B | broadcast |
? or / | shortcut help |
Agent types
Built-in types (editable, resettable). The CLIs live in the shared toolbox – install the ones you want under Settings → Sandbox defaults → Agent tools (default: Claude Code, Codex, OpenCode, Pi).
| Type | CLI (npm package) | Custom/local models | Notes |
|---|---|---|---|
claude-code | claude (@anthropic-ai/claude-code) | Anthropic Messages – or any chat server via translation | status hooks, onboarding/trust dialogs skipped |
codex | codex (@openai/codex) | OpenAI Responses – or any chat server via translation | notify hook, workspace trusted, runs with --sandbox danger-full-access (CoCoon isolates) |
opencode | opencode (opencode-ai) | Chat / Messages / Responses natively | config passed via OPENCODE_CONFIG_CONTENT, -m cocoon/<model> |
pi | pi (@earendil-works/pi-coding-agent) | Chat / Messages / Responses natively | provider written to ~/.pi/agent/models.json, --provider cocoon --model … |
qwen-code | qwen (@qwen-code/qwen-code) | Chat natively | OPENAI_BASE_URL / OPENAI_API_KEY / OPENAI_MODEL, -m |
gemini | gemini (@google/gemini-cli) | – (Gemini API key only) | |
shell | bash -l | env vars only | prompt typed into the terminal |
A profile defines command, promptMode (arg | input) and promptFlag, adapter (how providers are wired in;
derived from the command if omitted), tool, secrets, env, providers, model, hooks, workingPatterns,
blockedPatterns and idleForeground.
Skills: a profile can list skills – GitHub references such as owner/repo, owner/repo/path/to/skill or
owner/repo@v1 (also https://github.com/… and /tree/<ref>/<path> URLs). When an agent of this type starts, CoCoon
clones each repository (shallow) inside the sandbox and copies every folder containing a SKILL.md into the CLI's skills
folder (~/.claude/skills, ~/.codex/skills, ~/.gemini/skills, ~/.config/opencode/skills, ~/.pi/agent/skills,
~/.qwen/skills). A path pointing at a skill installs that one; otherwise all skills directly in the folder (or its
skills/ subfolder) are installed. Needs sandbox internet access; private repos use the sandbox's GitHub token.
Create e.g. a "Claude Code + Ponytail" agent type by duplicating Claude Code and adding the skill.
Switching agents: agent.switch (UI: Switch agent on the agent page or in a cockpit pane) starts another agent type – with
its own provider/model – in the same sandbox. With handover the new agent receives the original task, a git diff --stat of the
changes so far and the previous agent's last output; the previous agent is stopped and a running task follows the new agent.
Local LLMs
Add your server under Settings → API providers (kind OpenAI-compatible for llama.cpp, vLLM, LM Studio, Ollama …; Anthropic-
compatible for gateways speaking /v1/messages) and click Test connection: CoCoon lists the models and probes which API styles the
server speaks (Chat Completions, Responses, Anthropic Messages). When an agent is started with that provider, CoCoon
- picks the API style the agent speaks natively, or – for Claude Code and Codex on chat-only servers – routes it through the translating credential proxy (Anthropic Messages ↔ Chat, Responses ↔ Chat, including streaming and tool calls),
- passes the agent-specific start parameters / config (see table above) and the model (required: chosen at start, the agent type's model, the provider's default model or the first discovered one),
- passes the model's context window and answer length, so the agent compacts its history in time and never sends more than
the model can handle (Claude Code:
CLAUDE_CODE_AUTO_COMPACT_WINDOW/CLAUDE_CODE_MAX_OUTPUT_TOKENS; Codex:model_context_window/model_auto_compact_token_limit; OpenCode:limit.context/limit.output; Pi:contextWindow/maxTokens; Qwen Code:model.sessionTokenLimit). The connection test reads the limits from the server where it reports them (llama.cpp--ctx-sizein router listings, vLLMmax_model_len, OpenRoutercontext_length, LM Studiomax_context_length, …); they can be set or overridden per model, per agent type and per start. The answer length defaults to a quarter of the context window (1k–32k), and the translating proxy caps requests to it, - keeps the key on the server (the proxy injects it).
Translation runs in the credential proxy, which serves every sandbox with network access (identified by its token) as long as API key protection is on. Tested end to end with a llama.cpp-based server (chat only) and Claude Code, Codex, OpenCode and Pi. Example of a fully autonomous Claude Code (safe because it runs in a sandbox):
{
"claude-yolo": {
"label": "Claude Code (autonomous)",
"command": ["claude", "--dangerously-skip-permissions"],
"promptMode": "arg",
"hooks": "claude-code",
"secrets": ["ANTHROPIC_API_KEY", "CLAUDE_CODE_OAUTH_TOKEN", "GITHUB_TOKEN"]
}
}
Agent status detection
| Status | Meaning |
|---|---|
working | busy |
blocked | waiting for a human decision (permission prompt, y/n question, …) |
done | finished the task it was given |
idle | waiting, no open task |
exited | process ended (exit code available) |
unknown | could not be determined |
Two sources, reported as statusSource:
- Hooks – installed into each sandbox: Claude Code hooks in
~/.claude/settings.json(UserPromptSubmit/PreToolUse/PostToolUse→ working,Notification[permission_prompt]→ blocked,Stop→ done) and Codexnotifyin~/.codex/config.toml(→ done). They write to/opt/cocoon/status/<agentId>– no network access to the control plane needed. - Heuristics – a poller takes one snapshot per sandbox per second (tmux state, foreground process, screen): changing screen → working; quiet with a permission prompt visible → blocked; quiet after a task → done.
Hook reports win. If a hook says "working" but the screen has been quiet for 15 s (e.g. an API error without a Stop hook),
the heuristic takes over. Statuses survive control-plane restarts.
Languages
- The web UI is available in English and German. It follows the browser language (German browsers get German, everything else English) and can be switched in the sidebar footer or on the login page; the choice is stored per browser. Dates and numbers follow the selected locale.
- The server localizes error messages, the activity log and the setup checklist per request: header
x-cocoon-langor query?lang=→Accept-Language→settings.general.language(defaulten, used for CLI/API/MCP and console output). - CLI:
--lang enorCOCOON_LANG=en.
Updates
Settings → Updates (or pnpm cocoon update) shows whether everything is current and updates it with one click:
| Part | Checked against | Update |
|---|
// faq
What is cocoon?
Self-hosted platform for running AI coding agents (Claude Code, Codex, …) in isolated sandboxes – web UI, CLI, API and MCP. It is open-source on GitHub.
Is cocoon free to use?
cocoon is open-source under the MIT license, so it is free to use.
What category does cocoon belong to?
cocoon is listed under mcp-servers in the Claudeers registry of Claude-compatible tools.
// embed badge
[](https://claudeers.com/cocoon)
// retro hit counter
[](https://claudeers.com/cocoon)
// reviews
// guestbook
// related in MCP Servers
f.k.a. Awesome ChatGPT Prompts. Share, discover, and collect prompts from the community. Free and open source — self-host for your organization with complete…
A cross-platform desktop All-in-One assistant for Claude Code, Codex, OpenCode, OpenClaw, Gemini CLI & Hermes Agent. Only official website: ccswitch.io
🪨 why use many token when few token do trick — Claude Code skill that cuts 65% of tokens by talking like caveman
An open-source AI agent that brings the power of Gemini directly into your terminal.