Config basics

ZeroCode reads configuration details from more than one location. Your personal defaults live in ~/.zerotwo/config.toml, and you can add project overrides with .zerotwo/config.toml files. For security, ZeroCode loads project .zerotwo/ layers only when you trust the project.

ZeroCode configuration file

ZeroCode stores user-level configuration at ~/.zerotwo/config.toml. To scope settings to a specific project or subfolder, add a .zerotwo/config.toml file in your repo. To open the configuration file from the ZeroTwo desktop app, select the gear icon in the top-right corner, then select ZeroCode Settings > Open config.toml. The CLI and desktop app share the same configuration layers. You can use them to:

Set the default model and provider.
Configure approval policies and sandbox settings.
Configure MCP servers.

Configuration precedence

ZeroCode resolves values in this order (highest precedence first):

CLI flags and --config overrides
Project config files: .zerotwo/config.toml, ordered from the project root down to your current working directory (closest wins; trusted projects only)
Profile files selected with --profile profile-name (~/.zerotwo/profile-name.config.toml)
User config: ~/.zerotwo/config.toml
System config (if present): /etc/zerotwo/config.toml on Unix
Built-in defaults

Use that precedence to set shared defaults in config.toml and keep profile files focused on the values that differ. If you mark a project as untrusted, ZeroCode skips project-scoped .zerotwo/ layers, including project-local config, hooks, and rules. User and system config still load, including user/global hooks and rules. For one-off overrides via -c/--config (including TOML quoting rules), see Advanced Config. On managed machines, your organization may also enforce constraints via requirements.toml (for example, disallowing approval_policy = "never" or sandbox_mode = "danger-full-access"). See Managed configuration and Admin-enforced requirements.

Common configuration options

Here are a few options people change most often:

Default model

Choose the model ZeroCode uses by default in the CLI and IDE.

model = "gpt-5.6"

Approval prompts

Control when ZeroCode pauses to ask before running generated commands.

approval_policy = "on-request"

For behavior differences between untrusted, on-request, and never, see Run without approval prompts and Common sandbox and approval combinations.

Sandbox level

Adjust how much filesystem and network access ZeroCode has while executing commands.

sandbox_mode = "workspace-write"

For mode-by-mode behavior (including protected .git/.zerocode paths and network defaults), see Sandbox and approvals, Protected paths in writable roots, and Network access.

Permission profiles

ZeroCode also supports named permission profiles for reusable filesystem and network policies. Built-in profiles are :read-only, :workspace, and :danger-full-access. Custom profiles use [permissions.<name>] tables and a matching default_permissions value. See Permissions.

Windows sandbox mode

When running ZeroCode natively on Windows, set the native sandbox mode to elevated in the windows table. Use unelevated only if you don’t have administrator permissions or if elevated setup fails.

[windows]
sandbox = "elevated"   # Recommended
# sandbox = "unelevated" # Fallback if admin permissions/setup are unavailable

Web search mode

ZeroCode enables web search by default for local chats and serves results from a web search cache. The cache is an ZeroTwo-maintained index of web results, so cached mode returns pre-indexed results instead of fetching live pages. This reduces exposure to prompt injection from arbitrary live content, but you should still treat web results as untrusted. If you are using --yolo or another full access sandbox setting, web search defaults to live results. Choose a mode with web_search:

"cached" (default) serves results from the web search cache.
"indexed" permits external web access only when the search index gates the request.
"live" fetches the most recent data from the web (same as --search).
"disabled" turns off the web search tool.

web_search = "cached"  # default; serves results from the web search cache
# web_search = "indexed" # gate external web access through the search index
# web_search = "live"  # fetch the most recent data from the web (same as --search)
# web_search = "disabled"

Reasoning effort

Tune how much reasoning effort the model applies when supported.

model_reasoning_effort = "high"

Communication style

Set a default communication style for supported models.

personality = "friendly" # or "pragmatic" or "none"

You can override this later in an active session with /personality or per thread/turn when using the app-server APIs.

TUI keymap

Customize terminal shortcuts under tui.keymap. Selected composer actions fall back to matching tui.keymap.global bindings; context-specific bindings take precedence when supported. An empty list unbinds the action.

[tui.keymap.global]
open_transcript = "ctrl-t"

[tui.keymap.composer]
submit = ["enter", "ctrl-m"]

[tui.keymap.chat]
interrupt_turn = "f12"

Command environment

Control which environment variables ZeroCode forwards to spawned commands. Use keyed filters to keep only the variables you need:

[shell_environment_policy]
ignore_default_excludes = false

[shell_environment_policy.filters]
"PATH" = "include"
"HOME" = "include"

ignore_default_excludes defaults to true, which skips automatic filtering for variable names containing KEY, SECRET, or TOKEN. Set it to false when you want that automatic filtering. For exclusion rules, precedence, and legacy configuration, see Shell environment policy.

Log directory

Override where ZeroCode writes local log files. Setting log_dir explicitly also enables the opt-in plaintext TUI log, zerocode-tui.log, in that directory.

log_dir = "/absolute/path/to/zerocode-logs"

For one-off runs, you can also set it from the CLI:

zerocode -c log_dir=./.zerocode-log

Feature flags

Use the [features] table in config.toml to toggle optional and experimental capabilities.

Common feature flags

Key	Default	Maturity	Description
`apps`	true	Stable	Enable app (connector) integrations
`goals`	true	Stable	Enable persisted goals and automatic continuation
`hooks`	true	Stable	Enable lifecycle hooks from `hooks.json` or inline `[hooks]`. See Hooks.
`fast_mode`	true	Stable	Enable Fast mode selection and the `service_tier = "fast"` path
`memories`	false	Experimental	Enable Memories
`multi_agent`	true	Stable	Enable subagent collaboration tools
`personality`	true	Stable	Enable personality selection controls
`remote_plugin`	true	Stable	Enable the remote plugin catalog
`shell_snapshot`	true	Stable	Snapshot your shell environment to speed up repeated commands
`shell_tool`	true	Stable	Enable the default `shell` tool
`unified_exec`	`true` except Windows	Stable	Use the unified PTY-backed exec tool
`web_search`	true	Deprecated	Legacy toggle; prefer the top-level `web_search` setting
`web_search_cached`	false	Deprecated	Legacy toggle that maps to `web_search = "cached"` when unset
`web_search_request`	false	Deprecated	Legacy toggle that maps to `web_search = "live"` when unset

This table lists common user-facing flags, not every internal or under-development feature. The Maturity column uses labels such as Experimental, Beta, and Stable. See Feature Maturity for how to interpret these labels. Omit feature keys to keep their defaults. For lifecycle hook configuration, see Hooks.

Enabling features

In config.toml, add feature_name = true under [features].
From the CLI, run `
To enable more than one feature, run `
To disable a feature, set the key to false in config.toml.

Overview

Customization

Config file

Agent configuration

Extend ZeroTwo

Environments

Permissions

Windows

Connections

ZeroCode configuration file

Configuration precedence

Common configuration options

Default model

Approval prompts

Sandbox level

Permission profiles

Windows sandbox mode

Web search mode

Reasoning effort

Communication style

TUI keymap

Command environment

Log directory

Feature flags

Common feature flags

Enabling features

​ZeroCode configuration file

​Configuration precedence

​Common configuration options

​Default model

​Approval prompts

​Sandbox level

​Permission profiles

​Windows sandbox mode

​Web search mode

​Reasoning effort

​Communication style

​TUI keymap

​Command environment

​Log directory

​Feature flags

​Common feature flags

​Enabling features

ZeroCode configuration file

Configuration precedence

Common configuration options

Default model

Approval prompts

Sandbox level

Permission profiles

Windows sandbox mode

Web search mode

Reasoning effort

Communication style

TUI keymap

Command environment

Log directory

Feature flags

Common feature flags

Enabling features