Skip to main content

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:

LayerWhereUse it for
CLI flagenclave --tool codexa single run
Project config~/.config/enclave/projects/<hash>/config.jsonone repository
Global config~/.config/enclave/config.jsonyour 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"]
}
macOS

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-agent gets its own hash, its own project config, and its own persistent state.

Precedence​

Highest wins:

  1. CLI flags
  2. Per-tool overrides (tool_overrides.<tool>, see below)
  3. Project config
  4. Global config
  5. 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​

KeyFlagWhat 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-yoloFull 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 3000Publish a container port to the host, so the agent's dev server is reachable from your browser.
bridge_ports--bridge-port 9800The other direction: make a host service reachable at localhost:9800 inside the container.
note

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​

KeyFlagWhat 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 readonlyMount the project read-only: the agent can read and analyze, only you can write.

Network​

KeyFlagWhat 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-networkTurn network filtering off entirely for the session. The gateway still logs HTTP/HTTPS traffic.
disable_gateway--disable-gatewayRun an unrestricted session without the network gateway, so no network log is written. Fails in restricted mode.
network_log--network-log requestsLog request-level audit events instead of coarse pass/deny. full also stores request and response headers and bodies in restricted mode.

Auth and secrets​

KeyFlagWhat it does
auth_name--auth-name <slug>Keep several logins per agent (personal, api, …) and pick one per run.
auth_scope--auth-scope projectIsolate credentials per project instead of sharing them per agent.
pass_env--pass-env KEY1,KEY2Forward specific host environment variables in. Nothing else leaks in.
secrets_scope--secrets-scope globalWhich 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​