claudeers.
// MCP Servers

cocoon

Self-hosted platform for running AI coding agents (Claude Code, Codex, …) in isolated sandboxes – web UI, CLI, API and MCP

// MCP Servers[ cli ][ api ][ desktop ][ web ][ claude ]#claude#ai-agents#claude-code#docker#mcp#sandbox#self-hosted#mcp-servers◷ MIT$open-sourceupdated 20 days ago
Actively maintained
99/100
last commit 8 days ago
last release none
releases 0
open issues 7

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.
// or clone
git clone https://github.com/adziendziolD/cocoon

// compatibility

Platformscli, api, desktop, web
Operating systems—
AI compatibilityclaude
LicenseMIT
Pricingopen-source
LanguageTypeScript

Get your FREE $2.50 API credits to access TickAtlas financial data ↗

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

Onboarding wizardAfter 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
Cockpitherdr-style multi-agent window: tiled live terminals (split, resize, maximize), workspace tree, attention queue, broadcast input, keyboard control, layouts saved per workspace
Scheduled agentsAgents 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
OrchestrationWorkspaces, 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 UISetup 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 backendsDocker, 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 footprintSlim 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 controlPer 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 proxyAPI keys stay on the server – sandboxes only see placeholders, the proxy adds the real key on the way out
Many agentsClaude 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 LLMsEach 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 APIsBring 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 & portsServers 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 servicesOne 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 statusworking / blocked / done / idle / exited, from native hooks (Claude Code, Codex) plus screen heuristics
PersistenceAgents run in tmux inside the sandbox – they survive control-plane restarts and client disconnects
ResultsChanges leave the sandbox only as a git patch, a download, or a pushed branch + GitHub pull request
IntegrationsCLI, typed TypeScript client, REST/RPC, WebSocket events, MCP server
LanguagesUI, server messages and CLI in English and German (browser language, English fallback)
Zero-config startAdmin 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:

StepWhat happens
1. WelcomeWhat CoCoon is, language choice (optionally also for server messages)
2. System checkLive status of Docker, sandbox image (with build log) and egress proxy
3. AI accessAnthropic 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 & defaultsDefault internet access and size for new sandboxes
6. First sandboxName and optional repository – created right away
7. First agentPick an available agent type, choose or write a first task, watch its live status
8. DoneSummary, 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

PageWhat you can do
Onboarding (/onboarding)Guided first-time setup (see Quickstart)
OverviewSetup checklist with a direct action per step, agents waiting for you, running agents, recent activity
SandboxesList and create sandboxes (wizard: project/repository → internet access → size → advanced: image, runtime, env vars)
Sandbox detailAgents (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 detailLive 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
AgentsAll agents across sandboxes, blocked ones first
ActivityLive log of everything that happened
SettingsGeneral (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. /workspace is a git repository: either cloned from a URL (optionally a branch/tag/commit, private GitHub repos via GITHUB_TOKEN) or empty. A cocoon-baseline tag marks the starting point, so all changes can be exported as a patch. Lifecycle: creating → running ⇄ stopped, plus error / 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:

BackendWhat it isFootprintIsolationNotes
PodmanContainer engine without a background daemon, runs rootlesssmall, no root servicecontainers (+ gVisor / Kata / krun runtimes)uses Podman's Docker-compatible API socket
DockerThe standard container enginedaemon (~100 MB), rootcontainers (+ gVisor / Kata runtimes)Docker Desktop on macOS/Windows
bubblewrapLinux process sandboxes (namespaces, as used by Flatpak and Claude Code's own sandbox)tiny – no daemon, no imagesuser/pid/ipc/uts/(net) namespaces, read-only host, no capabilitiesLinux 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 rootful systemctl enable --now podman.socket. On macOS, podman machine works too. Containers reach the host as host.containers.internal.
  • bubblewrap: apt install bubblewrap tmux git (or dnf 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 on 127.0.0.1:7431/7432 (COCOON_PROXY_PORT). Sandbox options and secrets are passed to bwrap via 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]):

VariantContentsSize
slim (default)bash, git, tmux, ripgrep, curl, jq, less, procps, CA certificates< 250 MB (checked in CI)
dbslim + database clients: psql, mysql/MariaDB, redis-cli – handy with shared services+ ~100 MB
fulldb + 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

ModeImplementationUse 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 enforcedNormal work – agents can reach model APIs, GitHub, npm, PyPI
openBridge network / host network, unrestricted internetProjects that need arbitrary downloads
noneNo network at allUntrusted code, offline analysis

Egress proxy (images/egress-proxy, dependency-free Node.js, read-only container, no capabilities):

  • :3128 forward proxy enforcing the domain allowlist (*.example.com matches 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.
  • :8080 credential proxy: agents call http://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)

SecretUsed by
ANTHROPIC_API_KEYClaude Code (via credential proxy in egress mode)
CLAUDE_CODE_OAUTH_TOKENClaude Code with a Claude Pro/Max subscription (claude setup-token)
OPENAI_API_KEYCodex (via credential proxy in egress mode)
GITHUB_TOKENPrivate 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.

KindThe agent receivesTypical targets
anthropicANTHROPIC_BASE_URL, ANTHROPIC_API_KEY (or ANTHROPIC_AUTH_TOKEN for bearer auth), ANTHROPIC_MODELCompany gateway, LiteLLM, DeepSeek, Bedrock proxy – for Claude Code
openaiOPENAI_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_KEYAny 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 egress mode the base URL points to the credential proxy (http://cocoon-proxy:8080/p-<id>), which adds the real key. In open mode the agent talks to the provider directly.
  • localhost in a base URL is rewritten to host.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 anthropic provider, the default ANTHROPIC_API_KEY is not injected (same for openai / 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:

LevelApplies toIdentified by
Workspaceevery sandbox of the workspaceworkspace
Repositoryevery sandbox that clones the repository, in any workspacethe repository URL – https://github.com/o/r.git, [email protected]:o/r and ssh://[email protected]/o/r are the same repository
Sandboxthis sandboxsandbox
Agent typeagents of that typeSettings → 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 of sandbox.exec (never in the container's own configuration, so not in docker inspect).
  • file – a .env file in the repository folder (/workspace/.env, or /workspace/<folder>/.env per repository; the path is configurable per level). CoCoon adds the file to the repository's .git/info/exclude before it creates it, so it never appears in git status, diffs, commits, patches or pushes. It is written with mode 0600, starts with a # cocoon-managed line, 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 .env the 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 --repo repeated 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 /workspace itself.
  • Add later: Add repository on the sandbox page (sandbox.add_repo, pnpm cocoon repo add), remove with sandbox.remove_repo.
  • Git per repository: status, commit, push and pull request work per folder (repository selector in the UI, --repo <folder> on the CLI, repo parameter in the API/MCP). The Changes view shows all repositories; a combined patch has folder-prefixed paths. git.repos lists branch and number of changes per repository.
  • Agents know the layout: they start in /workspace and 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 *.localhost to the local machine), or https://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 *.localhost would 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 as X-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 sees Host: 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).

ServiceKindWhat each sandbox getsEnv vars for agents
PostgreSQL 17/16databaseown database + user (sb_<id>), may create schemas and extra (test) databasesDATABASE_URL, POSTGRES_URL, PGHOST, PGPORT, PGUSER, PGPASSWORD, PGDATABASE
MySQL 8.4 / MariaDB 11databaseown 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/7databaseown database + user (dbOwner)MONGODB_URI, MONGO_URL
Redis 7/8databaseown ACL user limited to keys/channels sb_<id>:*REDIS_URL, REDIS_KEY_PREFIX
WireMock 3mockown URL prefix /sb_<id>; its stubs are removed with the sandboxMOCK_API_URL, WIREMOCK_URL, WIREMOCK_ADMIN_URL, MOCK_API_PREFIX
Mailpitmockshared mailbox: mail sent via SMTP never leaves the server, readable via API and web UISMTP_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 on 127.0.0.1 only, 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.env is 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 includes psql, mariadb and redis-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.start creates/uses the sandbox and spawns the agent; the task status then follows the agent: blocked agents set attention, a finished agent moves the task to review (you look at the result), errors to failed with a note.
  • task.approve continues with the next workflow stage or marks the task done; task.reject sends 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 failed task 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_finished moves a failed task to review by hand, so you can approve it (or send it back).
  • dependsOn – a task only starts when all its dependencies are done.
  • Auto-run: in workspaces with autoRun, queued tasks are started automatically (high priority first) up to maxParallel.
  • 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 ok are 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–9jump to pane N
Entermaximize / restore
D / Wsplit / close pane
Gauto-grid
Bbroadcast
? 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).

TypeCLI (npm package)Custom/local modelsNotes
claude-codeclaude (@anthropic-ai/claude-code)Anthropic Messages – or any chat server via translationstatus hooks, onboarding/trust dialogs skipped
codexcodex (@openai/codex)OpenAI Responses – or any chat server via translationnotify hook, workspace trusted, runs with --sandbox danger-full-access (CoCoon isolates)
opencodeopencode (opencode-ai)Chat / Messages / Responses nativelyconfig passed via OPENCODE_CONFIG_CONTENT, -m cocoon/<model>
pipi (@earendil-works/pi-coding-agent)Chat / Messages / Responses nativelyprovider written to ~/.pi/agent/models.json, --provider cocoon --model …
qwen-codeqwen (@qwen-code/qwen-code)Chat nativelyOPENAI_BASE_URL / OPENAI_API_KEY / OPENAI_MODEL, -m
geminigemini (@google/gemini-cli)– (Gemini API key only)
shellbash -lenv vars onlyprompt 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

  1. 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),
  2. 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),
  3. 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-size in router listings, vLLM max_model_len, OpenRouter context_length, LM Studio max_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,
  4. 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

StatusMeaning
workingbusy
blockedwaiting for a human decision (permission prompt, y/n question, …)
donefinished the task it was given
idlewaiting, no open task
exitedprocess ended (exit code available)
unknowncould not be determined

Two sources, reported as statusSource:

  1. Hooks – installed into each sandbox: Claude Code hooks in ~/.claude/settings.json (UserPromptSubmit/PreToolUse/PostToolUse → working, Notification[permission_prompt] → blocked, Stop → done) and Codex notify in ~/.codex/config.toml (→ done). They write to /opt/cocoon/status/<agentId> – no network access to the control plane needed.
  2. 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-lang or query ?lang= → Accept-Language → settings.general.language (default en, used for CLI/API/MCP and console output).
  • CLI: --lang en or COCOON_LANG=en.

Updates

Settings → Updates (or pnpm cocoon update) shows whether everything is current and updates it with one click:

PartChecked againstUpdate

…view the full README on GitHub.

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

15 views
★ 29 stars
unclaimed
updated 20 days ago

// embed badge

cocoon on Claudeers
[![Claudeers](https://claudeers.com/api/badge/cocoon.svg)](https://claudeers.com/cocoon)

// retro hit counter

cocoon hit counter
[![Hits](https://claudeers.com/api/counter/cocoon.svg)](https://claudeers.com/cocoon)

// reviews

// guestbook

0/500

// 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…

// mcp-serversf/⟨HTML⟩★ 175,627◷ NOASSERTION[ claude ]
🔓

A cross-platform desktop All-in-One assistant for Claude Code, Codex, OpenCode, OpenClaw, Gemini CLI & Hermes Agent. Only official website: ccswitch.io

// mcp-serversfarion1231/⟨Rust⟩★ 151,540◷ MIT[ claude ]
🔓

🪨 why use many token when few token do trick — Claude Code skill that cuts 65% of tokens by talking like caveman

// mcp-serversJuliusBrussee/⟨JavaScript⟩★ 117,780◷ MIT[ claude ]
🔓

An open-source AI agent that brings the power of Gemini directly into your terminal.

// mcp-serversgoogle-gemini/⟨TypeScript⟩★ 108,744◷ Apache-2.0[ claude ]
→ see how cocoon connects across the ecosystem