Configuration
Enclave works without any configuration: enclave starts an agent at full
autonomy, in a container, behind a restricted network. The first interactive
session asks which agent and remembers the answer (a non-terminal run is never
asked; until a tool is configured it fails and points at --tool and the tool
key). You configure it when you want something else, such as a different agent,
one more allowed domain, or an extra directory mounted in.
A setting can come from three places:
| Layer | Where | Use it for |
|---|---|---|
| CLI flag | enclave --tool codex | a single run |
| Project config | ~/.config/enclave/projects/<hash>/config.json | one repository |
| Global config | ~/.config/enclave/config.json | your defaults everywhere |
Both files are plain JSON. Every key is optional, and most keys have a matching CLI flag:
{
"tool": "codex",
"features": ["+gitlab-cli"],
"add_readonly_dirs": ["~/reference/specs"]
}
The config root is ~/Library/Application Support/org.eclipse.enclave/config/
instead of ~/.config/enclave/. Substitute it in every path on this page.
Find your config files
Project config is keyed by a hash of the project directory, so you never have to
write that path yourself. enclave config prints both files, whether or not they
exist yet:
enclave config
Global Config: /home/you/.config/enclave/config.json (missing)
Project Config: /home/you/.config/enclave/projects/1a2b3c4d5e6f/config.json (missing)
Create either file yourself, with mkdir -p on its directory and {} as the
starting content, and Enclave picks it up on the next run. JSON comments are not
supported, so keep the file strict JSON.
Two things follow from the layout:
- Project config lives outside the worktree, keyed by hash. A repository cannot carry its own sandbox policy, and an agent working in it cannot rewrite the rules it runs under.
- Each git worktree is its own project. A worktree at
../myproject-agentgets its own hash, its own project config, and its own persistent state.
Precedence
Highest wins:
- CLI flags
- Per-tool overrides (
tool_overrides.<tool>, see below) - Project config
- Global config
- Built-in defaults
Lists such as ports, add_dirs, allow_domains, and pass_env combine
across these layers. A plain list replaces the inherited one, +x adds,
-x removes, and [] (or none) clears, in config files and on the command
line alike. --add-dir is the exception: a plain path adds to the configured
directories.
enclave -p 3000 # publish only 3000
enclave -p +3000 # publish 3000 on top of the configured ports
enclave -p -8080:80 # drop a configured port for this run
enclave --add-dir ~/notes # mount ~/notes next to the configured dirs
The full rules, including features and port clashes, are in List Options.
When a value is not what you expect, ask Enclave where it came from:
enclave config --view source # annotate every value with its origin
enclave config --view effective # just the resolved values
enclave config --view diff # only values that something overrode
enclave config --json # the same data, machine-readable
Most commonly used options
Agent and session
| Key | Flag | What it does |
|---|---|---|
tool | --tool <name> | Which agent runs. Asked once on the first interactive session and saved here; enclave tools lists what is installed. |
yolo | --no-yolo | Full autonomy, on by default. Pass --no-yolo to make the agent ask for confirmation again. Every bundled CLI agent pins the mode in its own profile, so "yolo": false in a config file does not reach them; use the flag. |
features | --features <list> | Extra tooling baked into the image (see Features). |
ports | -p 3000 | Publish a container port to the host, so the agent's dev server is reachable from your browser. |
bridge_ports | --bridge-port 9800 | The other direction: make a host service reachable at localhost:9800 inside the container. |
On Linux, a bridged host service has to listen on the Docker bridge IP rather
than 127.0.0.1, and the host firewall has to let the bridge network through.
See Bridging host ports.
Files
| Key | Flag | What it does |
|---|---|---|
add_dirs | --add-dir <path> | Mount another host directory, writable, at the same path inside the container. |
add_readonly_dirs | --add-readonly-dir <path> | The same, read-only. Good for reference material you do not want touched. |
sensitive_dir_exceptions | --add-sensitive-dir <path>, --add-readonly-sensitive-dir <path> (this run only, and mount it) | Allow mounting a sensitive directory, such as a dotfiles repository or ~/.m2, and everything below it. Warns on every start. See Sensitive mounts. |
project_mount | --project-mount readonly | Mount the project read-only: the agent can read and analyze, only you can write. |
Network
| Key | Flag | What it does |
|---|---|---|
allow_domains | --allow-domain <domain> | Add domains to the gateway allowlist. Bare DNS names only, no scheme or path. |
allow_all_network | --allow-all-network | Turn network filtering off entirely for the session. The gateway still logs HTTP/HTTPS traffic. |
disable_gateway | --disable-gateway | Run an unrestricted session without the network gateway, so no network log is written. Fails in restricted mode. |
network_log | --network-log requests | Log request-level audit events instead of coarse pass/deny. full also stores request and response headers and bodies in restricted mode. |
Auth and secrets
| Key | Flag | What it does |
|---|---|---|
auth_name | --auth-name <slug> | Keep several logins per agent (personal, api, …) and pick one per run. |
auth_scope | --auth-scope project | Isolate credentials per project instead of sharing them per agent. |
pass_env | --pass-env KEY1,KEY2 | Forward specific host environment variables in. Nothing else leaks in. |
secrets_scope | --secrets-scope global | Which layers of the secrets files are read. |
The full key list, including build and persistence options, is in docs/configuration.md.
Features
Features are optional tool stacks compiled into the image. devtools,
github-cli, node-dev, and python-dev are on by default; gitlab-cli,
golang-dev, and theia-dev are opt-in. More features, such as debug-tools,
are in enclave-extensions.
Use + and - to adjust the inherited set instead of replacing it:
{
"features": ["+gitlab-cli", "-python-dev"]
}
A list without prefixes replaces the set entirely, and [] means none. On the
command line, --features +gitlab-cli adds to the configured features while
--features a,b replaces them. Check the
result before you build with enclave features, which marks every feature ✓
or ✗ and names the config file that switched it off:
enclave features
The same syntax works on the command line: --features +gitlab-cli, or the
keywords --features default|all|none.
Reuse the agent config you already have
By default the container starts from Enclave's own agent config, not your host one. Two ways to change that:
Pass reviewed paths through from the host. host_config: "passthrough"
copies a per-tool allow-list of files out of your host config directory. For
Claude that is agents/, commands/, settings.json, and skills/ under
~/.claude. Auth files, OAuth JSON, and session/history state are blocked even
if you add them to the list. Narrow or widen the list per tool, under the
per-tool override for that agent:
{
"host_config": "passthrough",
"tool_overrides": {
"claude": {
"host_config_paths": ["default", "-skills/"]
}
}
}
Or keep a separate, container-only config. Files under
~/.config/enclave/tools/<tool>/ mirror the agent's native config layout and are
overlaid at session start, so ~/.config/enclave/tools/claude/settings.json
becomes the container's ~/.claude/settings.json. Per project, use
~/.config/enclave/projects/<hash>/<tool>/config/. Shared skills go in
~/.config/enclave/skills/<skill>/ and reach every skill-capable agent.
Both mechanisms compose, and JSON/TOML patches can merge into a file instead of replacing it. The precedence order, the patch merge semantics, and the full passthrough safety rules are documented in docs/configuration.md.
What project config can do
Project config lives in Enclave's host config root, out of reach of the
repository and of the agent, so only you can edit it. It can therefore set
anything global config can, for that project only: a different default tool,
extra allowed domains, a writable mount, or yolo mode. The exceptions are
auto_update and update_channel, which control the Enclave binary itself, and
disabled_commands, because commands are resolved before the project is known.
These are read from global config only.
Mounting a sensitive directory such as your home directory or ~/.ssh still
needs --allow-sensitive-mounts (or ENCLAVE_ALLOW_SENSITIVE_MOUNTS=1),
whichever config file asks for it: that opt-in has no config key.
Per-tool overrides
tool_overrides.<tool> applies to one agent only, and wins over the surrounding
project and global values:
{
"tool": "claude",
"allow_domains": ["api.deepseek.com"],
"tool_overrides": {
"codex": {
"auth_name": "personal",
"features": ["+python-dev"]
}
}
}
Overrides take the same keys as the surrounding file, except tool itself and a
nested tool_overrides.
Going further
- Configuration reference: every key, patches, skills, precedence details
- CLI reference: every command and flag
- Networking: allowlists, the gateway, port forwarding
- Authentication and secrets: logins, secrets layers, API keys