Skip to content

Configuration

Change how odette behaves for every project, or for just one.

odette has three places to configure:

  • Global settings in ~/.odette/config.json, for every project.
  • Project files in .odette/ at the root of each project.
  • Environment variables, mostly for one-off overrides.

~/.odette is odette’s data folder. Set ODETTE_DATA_DIR to use another one. Where configuration comes from lists every source a session reads, and what survives a restart or a move to a new machine.

Read and change them with the CLI rather than editing the file:

Terminal window
odette config get # every key, its value and its default
odette config get web_port
odette config set approval_timeout 600
Key in config.json config set name Default Meaning
backend backend chosen by setup docker or apple. odette setup writes it: the one runtime installed, or your pick when both are (Docker by default).
log_level log_level INFO DEBUG, INFO, WARN, WARNING or ERROR.
web_port web_port 7900 Dashboard port.
proxy_port proxy_port 7901 Egress proxy port.
mcp_port mcp_port 7902 Port agents use to reach odette’s tools.
default_timeout default_timeout 0 Seconds a host command may run; 0 is no limit.
approval_timeout approval_timeout 300 Seconds a held request waits for you before it is denied; 0 waits forever.
heartbeat_interval heartbeat_interval 15 Seconds between progress messages while a host command an agent asked for is waiting or running; they keep the agent’s connection open.
gate.mcp_mode, gate.proxy_mode (use odette gates) judge Commands and Egress gate modes. See Approvals.
marketplaces (use odette marketplace) none Plugin marketplaces for every project. See Plugins and marketplaces.
flags feature.<name> none Feature flag overrides, on or off. See Feature flags.
ssh_key_fingerprint (use odette setup) none The SSH key odette encrypts with.

The daemon reads config.json when it starts. After config set, run odette daemon restart; it takes the new values. Gate modes and feature flags apply at once, but status_row and pod_clear change what new sessions get; a session already running keeps what it started with.

Runtime Notes
Docker The default on Linux, and on macOS without the container CLI. On macOS, size containers in Docker Desktop’s settings.
Apple container Each session is its own small VM, capped at half your CPUs (1 to 4) and half your memory (1 to 8 GiB). If the container service is stopped, odette and odette build start it for you. It needs a default kernel, which odette does not install; on a new machine run container system kernel set --recommended once. The first time odette’s daemon starts, macOS asks whether to allow incoming connections for it; allow it once.

ODETTE_BACKEND=docker (or apple) overrides the setting for one command.

Variable Effect
ODETTE_BACKEND Force docker or apple.
ODETTE_DATA_DIR Use another data folder instead of ~/.odette.
ODETTE_JUDGE=1 Start the daemon with both gates in judge mode.
ODETTE_YOLO=1 Start the daemon with both gates in yolo mode.
ODETTE_JUDGE_MODEL Model the AI judge uses.
ODETTE_LISTEN_HOST Address the daemon listens on for containers. Only needed on Linux when Docker’s bridge address is not detected (Troubleshooting).
ODETTE_OAUTH_CLIENT_ID, ODETTE_OAUTH_AUTHORIZE_URL, ODETTE_OAUTH_TOKEN_URL, ODETTE_OAUTH_SCOPES, ODETTE_OAUTH_REDIRECT_URI Override the Claude sign-in endpoints, in case Anthropic moves them.

ODETTE_JUDGE, ODETTE_YOLO and ODETTE_JUDGE_MODEL take effect only when the daemon starts; if it is already running, odette daemon restart from the shell that sets them.

ODETTE_UNATTENDED=1 is set by odette, never by you, in a command an agent ran without your approval. odette commands that change settings, gates or credentials refuse to run under it; read-only ones still work. Run those in your own terminal.

Inside a session odette sets ODETTE_POD and ODETTE_POD_ROLE (see Pods).

odette init creates the folder; any launch creates it if it is missing. Commit the folder, except the *.local.json files.

File Created by init Purpose
Dockerfile yes Your project’s layer on top of odette’s base image.
domains.allow yes Hosts this project may reach without asking. Seeded with your git remotes’ hosts.
domains.deny no Hosts this project may never reach. Created when you deny a host “in this project”.
plugins.json yes Plugins to enable, as "plugin@marketplace" strings.
marketplaces.json yes Plugin marketplaces for this project.
marketplaces.local.json no Same, for your machine only.
mounts.json yes Extra folders to mount into sessions.
mounts.local.json no Same, for your machine only.
volumes.json yes Folders that get a separate copy inside the container.
startup.sh yes Shell code run in the container before Claude Code starts.
kits.lock no The kits applied to this project (Kits). Written by odette kit, not by hand.

All .json files hold a JSON array ([] when empty).

odette init adds .odette/*.local.json to .gitignore, so the machine-only files are never committed. If a project lacks that line, run odette init again: it adds what is missing and leaves your files alone. An .odette/environment file is never read; set variables in startup.sh.

Inside a session, .odette/ is read-only, so an agent can’t change its own allowlist or build. Edit these files on your machine. A changed Dockerfile is rebuilt on the next launch; the other files are read at every launch.

Starts FROM odette-base:local, which already has Claude Code’s runtime, your user and common tools. Add what your project needs:

FROM odette-base:local
RUN apt-get update -qq && apt-get install -y --no-install-recommends postgresql-client

A kit is a reusable setup you apply to a project: a toolchain, plugins, egress hosts, project rules. They have their own page: Kits.

Sourced, not executed, inside the container just before Claude Code starts, with the project root as the current folder. Anything it exports reaches Claude Code, for example:

Terminal window
eval "$(direnv export bash)"

The file form of --mount-ro / --mount-rw. Each folder appears at the same absolute path inside the container. Edit them with odette mount, or by hand:

Terminal window
odette mount add ~/.trellis --rw # mounts.local.json: this project, this machine
odette mount add vendor/shared --shared # mounts.json: committed with the project
odette mount # list both, and whether the next launch mounts each
odette mount rm ~/.trellis

add writes mounts.local.json unless you pass --shared, and mounts read-only unless you pass --rw. A path that doesn’t exist yet is written with a warning. --shared refuses a path the committed file would skip: outside the project, the project root itself, or a file. A path already in the other file is refused too, since one folder can only be mounted once. rm looks in mounts.local.json first, then mounts.json; --shared looks only in mounts.json. Changes take effect on the next launch.

[{ "path": "vendor/shared", "mode": "ro" }]
  • path: relative to the project root, absolute, or starting with ~/.
  • mode: "ro" (default) or "rw".

Because mounts.json is committed, anyone who can change your branch can change it. odette therefore only accepts paths inside the project (not the project root itself, and not through a symlink), and skips anything else with a warning. Put mounts outside the project, such as ~/.aws, in mounts.local.json, which has no such limit. A path that doesn’t exist is skipped with a warning. File entries and command-line flags add up.

Another session of the same project can change files in it while you launch, so odette also checks, from inside the new session and before anything else runs, that each mounts.json folder is the one it looked at. If it changed in between, the session stops with odette: WARNING — mount <path> changed since the launch check; aborting; launch again. This needs something to compare, so a mounts.json folder that is empty, holds more than 5000 files or 64 MiB, or has a newline or backslash in a file name is skipped with a warning. mounts.local.json entries are not checked this way.

Folders such as node_modules, .venv or target hold builds for one operating system. If your machine and the container share them, whichever installed last breaks the other. List them here and sessions get their own copy, kept between launches:

[{ "path": "node_modules" }, { "path": ".venv" }]

Paths must be relative and inside the project.

The copy is a folder on your machine, ~/.odette/overlays/<project>/<path>, shared by all of the project’s sessions, under every profile and on both container runtimes. Two sessions installing into it at the same moment can race; run one install at a time. It covers the project folder only, not worktrees: a worktree is only used inside containers, so it needs no separate copy. odette sessions home list shows these folders, and odette sessions home prune --orphans and odette clean remove them.

A marketplace is a source of Claude Code plugins. odette does not download marketplaces itself: at every launch it tells Claude Code which marketplaces and plugins to use, and Claude Code fetches and updates them inside the session, as it would on your laptop. Removing an entry takes effect at the next launch: the marketplace is removed and its plugins are switched off.

Every session has one marketplace without asking: odette, which comes inside odette itself and needs no network. Its odette-internals plugin teaches the agent how odette works: its commands, its configuration files and the container it runs in. You cannot add another marketplace named odette.

No other marketplace is on by default. odette setup offers a short list of suggested public marketplaces, each with a line on what it does, and adds the ones you pick. Add any other with odette marketplace:

Terminal window
odette marketplace add org/market --plugins lint,review # this project, committed
odette marketplace add ./vendor/tools # a folder inside the project
odette marketplace add ~/my-market --local # this project, this machine
odette marketplace add JuliusBrussee/caveman --global # every project
odette marketplace list
odette marketplace rm caveman # from whichever file declares it

Without --plugins, add reads the marketplace’s plugin list and lets you pick (all are checked); without a terminal it enables them all. It reads the list from a local folder, or from GitHub for an owner/repo source; a private repository is read with your gh login. For anything else, or a GitHub repository it cannot read, name the plugins with --plugins. Adding a marketplace already in the file adds the plugins you name to the ones it enables; a different source under the same name replaces it. Outside a git project, only --global works. rm finds the entry in whichever file declares it; if both the local file and config.json do, pass --local or --global. list shows each entry’s file and, for a GitHub marketplace odette may read with your login, approved.

Switch plugins on and off afterwards with odette marketplace plugins:

Terminal window
odette marketplace plugins caveman # enabled, disabled and offered
odette marketplace plugins caveman --disable review # off, and kept off
odette marketplace plugins caveman --enable review # on again

A disabled plugin stays off when you apply a kit that declares it again; odette kit apply says it left the plugin disabled.

Sessions never hold a GitHub credential. Instead, odette reads a private marketplace for them with your own GitHub login, from the gh CLI on your machine, and only for a repository you approved. Log in once with gh auth login; without it, private marketplaces fail with GitHub’s own error and everything else works.

Each private repository is approved once, the first time odette meets it:

  • odette marketplace add asks in your terminal when the repository is private.
  • Otherwise the launch asks, before the session starts: in your terminal and in the dashboard at once, and the first answer counts. With no terminal it waits up to 10 minutes for the dashboard, then starts without that marketplace.

An approval covers where the marketplace is declared: every project for one in config.json, or only that project for one in its .odette files. If you deny it, the session starts without that marketplace and the next launch asks again; odette marketplace rm stops the question. The dashboard’s Rules zone lists approvals under GitHub logins, grouped by scope; revoking one stops odette using your login for it from the next fetch, in a running session too. odette uses your login only to fetch an approved repository, never to push, and never for any other repository or GitHub request.

There are two lists, with the same entry format:

List Where Applies to
Global marketplaces in config.json Every project
Project .odette/marketplaces.json, .odette/marketplaces.local.json This project

Both take effect at the next launch; no rebuild is needed.

An entry is a source string, or an object:

[
"org/market",
{ "source": "./vendor/tools", "name": "tools", "autoEnable": ["lint"] },
{ "source": "https://gitlab.com/org/other-market.git", "autoEnable": ["one-plugin", "another"] }
]
Field Meaning
source A GitHub owner/repo, a git URL, or a local folder. A GitHub ssh URL (git@github.com:org/repo.git) is fetched over https. ssh URLs for other hosts are not supported. A local folder is mounted read-only into the session, uncommitted changes included.
name Optional; defaults to the last part of source. It must match the name in the marketplace’s own .claude-plugin/marketplace.json, or Claude Code will not use it; if they differ, the launch says which name to set.
autoEnable The plugins to enable from this marketplace, by name. Without it the marketplace is only made available, for /plugin or plugins.json.
disabledPlugins Plugins kept off even when a kit that declares them is applied again. odette marketplace plugins <name> --disable writes it, and --enable removes the name.

Plugins listed in .odette/plugins.json, as "plugin@marketplace" strings, are enabled too.

Any other key, or a missing or empty source, is an error: odette stops and names the key instead of skipping the entry. There is no url or ref key; put the URL in source. Two keys from older versions are still read but no longer work, and the launch warns about them: "autoEnable": true (list the plugin names instead) and installDeps (odette no longer installs a plugin’s dependencies; a plugin that needs packages installs them inside the session or ships them).

A project entry replaces a global one with the same name, and an entry in marketplaces.local.json replaces one in marketplaces.json. The entry that wins replaces the other whole, so its plugins and disabled plugins are not merged. A launch warns when this happens and says what is dropped, and odette marketplace list marks the row that was replaced.

In marketplaces.json, a local-folder source must be inside the project and must not be, or pass through, a symlink — even one pointing back inside the project; anything else is skipped with a warning. marketplaces.local.json has no such limit.

A local folder from marketplaces.json is copied for each session, and the session mounts the copy, so changes you make to the folder after launching do not reach a running session. A folder over 5000 files or 64 MiB is skipped with a warning. A folder that is the project itself is mounted as it is, not copied, so its changes do reach a running session.

A marketplace a project declares in its own .claude/settings.json still works, because Claude Code reads that file itself, but odette does not manage it.

Scope names in the terminal and the dashboard

Section titled “Scope names in the terminal and the dashboard”

Commands that keep a list per scope use the same flags; the dashboard shows two of the scopes.

Terminal Dashboard Applies to
(no flag) In this project This project, for everyone who clones it
--local (marketplace) In this project This project, this machine only
--global Every project Every project on this machine
--inspect (rules) Every project The inspected-hosts list, machine-wide

A session reads its configuration from these places, and nothing else:

Source Holds Kept by On a new machine
odette itself What odette needs to work (Claude Code’s own settings) odette, with each release Comes with odette
Your organization’s Claude Code policy, if any (Security) Whatever your organization enforces; where it and odette disagree, the policy wins Your organization’s administrators The machine’s policy file comes with the machine; settings set on claude.ai follow your account
~/.odette (config.json, egress/) Your global choices: marketplaces, gate modes, ports, feature flags, global allow, deny and inspect lists You Copy it, or keep it in your dotfiles
Plugins from marketplaces Skills, agents, hooks, MCP server definitions Plugin authors Fetched again
The project’s Claude Code files (.claude/settings.json, .mcp.json, CLAUDE.md/AGENTS.md, .claude/ skills, agents, rules) The project’s Claude configuration The project’s team, in git Comes with the repository
The project’s .odette/ The container, egress and project marketplaces The project’s team, in git Comes with the repository
Machine-only project files (.claude/settings.local.json, .odette/*.local.json) Your overrides for one project on this machine You Stays behind
Profile secrets (~/.odette/profiles/, encrypted) Claude credentials, service API keys You Sign in again

What survives what:

  • Rebuilt anywhere from the sources above, except the machine-only rows.
  • Kept on this machine only: the Claude home (conversations, /plugin install, /config changes, MCP sign-ins), the machine-only files and the profile secrets. odette never reads the home as configuration; to make a change there reproducible, move it into a plugin or the project’s Claude Code files.
  • Lost when the session ends: anything written in the container outside the home, the project and declared mounts or volumes, such as apt-get install, npm -g or edits under /etc. To keep a tool, put it in .odette/Dockerfile.

To set up a new machine, bring ~/.odette/config.json, ~/.odette/egress/ and your repositories, then sign in to each profile. Homes stay on the old machine unless you copy their folders across.

odette fixes a few Claude Code settings in every session, and nothing inside a session can override them: its notification and status hooks, its host command tools, the git ref worktrees start from, the classic screen mode, and skipping the bypass-permissions warning. Everything else is yours to set through Claude Code’s usual files.

Commit and pull-request attribution is one of those. odette leaves Claude Code’s default in place, so commits get a Co-Authored-By trailer unless the project turns it off in its committed .claude/settings.json:

{
"attribution": { "commit": "", "pr": "", "sessionUrl": false }
}

Optional behaviour that is still being proven.

Terminal window
odette config # checkbox picker (in a terminal)
odette config get # every setting and flag
odette config set feature.status_row on
odette config set feature.pod_clear off
Flag Default Effect
status_row off Show what is waiting on you in the session’s terminal (Dashboard).
pod_clear on Let pod sessions be cleared with a handoff (Pods).
self_clear off Let a pod supervisor or conductor clear itself. Needs pod_clear.

Flags are stored in config.json under flags and apply to every project.

Theme