AI coding agents are most useful when they can run commands, install packages and edit files without asking for permission at every step. They are also most dangerous in exactly that mode: one bad command, leaked secret or prompt injection, and your laptop or credentials are at risk.
On 19 November 2026 the Eclipse Foundation released Eclipse Enclave 1.0, an open-source (MIT) sandbox that runs coding agents such as Claude Code, Codex and OpenCode inside isolated containers with a filtered network. This tutorial shows how Enclave works, how to install it, and how to run your first sandboxed agent session with a locked-down network.
What Enclave does
Enclave originated at EclipseSource and was contributed to the Eclipse Foundation. According to its README and website, each session works like this:
- See: the agent only sees your project worktree and any extra mounts you choose.
- Run: the agent runs in “YOLO mode” (no confirmation prompts) inside its own container on Docker or Podman.
- Reach: all traffic goes through a gateway that allows only allowlisted domains and logs what it allows and blocks.
- Keep: logins, config, history and agent memory persist on the host across sessions.
Supported agents listed in the README include Claude Code, Codex, Copilot, OpenCode and Pi, with more (such as Amp and Antigravity) available as extensions.
Prerequisites
- Linux, macOS, or Windows through WSL2
- Rootful Docker with buildx, or Podman (rootless works)
- Git 2.26+ with an author and committer identity configured
Set your Git identity first, because Enclave exits before starting the container if it is missing:
git config --global user.name "Your Name"
git config --global user.email "[email protected]"
docker buildx version # or: podman --version
Install
Download a package from the latest release, then:
# Ubuntu 24.04, x86-64
sudo apt install ./enclave_*_amd64.deb
# Fedora, x86-64
sudo dnf install ./enclave-*.x86_64.rpm
Standalone binaries for Linux and macOS (x86-64 and arm64) are also available and can update themselves with enclave self-update.
Your first sandboxed session
Run Enclave as a regular user (it refuses to run as root) from a project directory:
cd ~/code/my-api
enclave
The first interactive run asks which agent to use and saves the answer as "tool" in ~/.config/enclave/config.json. Log in to the agent once inside the container; the login is stored and reused.
Useful commands from the README:
| Command | What it does |
|---|---|
enclave |
Start a session with the configured agent |
enclave --tool codex |
Use a different agent for one run |
enclave continue |
Continue the latest session |
enclave --background |
Start a session you can detach from |
enclave attach [name] |
Reattach to a background session |
enclave ps |
List running sessions |
enclave shell |
Open a shell in the container |
enclave network log |
Show what the agent tried to reach |
enclave info |
Show config and image details |
A foreground session ends with its terminal; closing it or pressing Ctrl-\ stops the container.
Running agents in parallel
Enclave’s website recommends giving each parallel agent its own git worktree so their changes never collide:
cd ~/code/my-api
git worktree add ../my-api-auth -b agent/auth-refactor
git worktree add ../my-api-tests -b agent/more-tests
(cd ../my-api-auth && enclave --background)
(cd ../my-api-tests && enclave --tool codex --background)
enclave ps # see both sessions
enclave attach # jump into one when it needs you
When the agents finish, review each branch like any pull request and merge on your terms.
Controlling the network
By default a session runs in restricted mode: DNS only resolves allowlisted domains, and the gateway checks the HTTP Host header or TLS SNI against the same list. Each agent ships its own built-in allowlist so it can reach its model API.
If your project needs another domain, for example a private package registry, add it:
enclave network add-domain registry.example.com --global
enclave network apply # push the policy to running gateways
enclave network diff # what changed versus built-in defaults
For a single project, set allow_domains in that project’s config file under ~/.config/enclave/projects/<hash>/config.json. Project config lives outside the worktree, so neither the repository nor the agent can change its own isolation policy.
Reading the network log
The log is where Enclave earns its keep. You can see exactly what an agent tried to contact:
enclave network log --summary # per-domain totals
enclave network log --verdict deny # only blocked requests
enclave network log --follow # live stream
enclave network log --json | jq '.' # machine-readable
If you see an unfamiliar domain in the denied list right after the agent read a README or web page, that is a strong hint of a prompt-injection attempt, and it was blocked.
Unrestricted mode, if you must
enclave --allow-all-network
The gateway still logs ports 80 and 443 in this mode, but the docs warn that other traffic such as SSH, UDP and DNS passes unlogged. Use it only for trusted tasks.
Configuration basics
Global config lives in ~/.config/enclave/config.json. A minimal example based on the documented keys:
{
"tool": "claude",
"project_mount": "readonly",
"pass_env": ["GITHUB_TOKEN"],
"allow_all_network": false
}
toolis the default agent.project_mount: "readonly"is useful for review-only sessions where the agent should read code but not change it.pass_envpasses specific environment variables into the session; keep this list short.
Settings are layered: CLI flags beat tool overrides, which beat project config, which beats global config. enclave config --view source shows where each value came from.
What Enclave does not do
Read the security docs before relying on it. Container isolation limits damage, but a mounted worktree is still writable unless you mount it read-only, and anything you allowlist is reachable. Always review agent changes before merging, and don’t put production credentials in pass_env.
Takeaway
Eclipse Enclave gives you a practical middle ground: let coding agents run autonomously, but inside a container that sees only your project and talks only to domains you approve, with a log of everything it tried. Install it, run enclave in a project, and check enclave network log after your first session. Find the docs at enclave.eclipse.dev.
