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.
Global settings
Section titled “Global settings”Read and change them with the CLI rather than editing the file:
odette config get # every key, its value and its defaultodette config get web_portodette config set approval_timeout 600Key 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.
Container runtime
Section titled “Container runtime”| 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.
Environment variables
Section titled “Environment variables”| 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).
Project files (.odette/)
Section titled “Project files (.odette/)”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.
Dockerfile
Section titled “Dockerfile”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:localRUN apt-get update -qq && apt-get install -y --no-install-recommends postgresql-clientA kit is a reusable setup you apply to a project: a toolchain, plugins, egress hosts, project rules. They have their own page: Kits.
startup.sh
Section titled “startup.sh”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:
eval "$(direnv export bash)"mounts.json and mounts.local.json
Section titled “mounts.json and mounts.local.json”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:
odette mount add ~/.trellis --rw # mounts.local.json: this project, this machineodette mount add vendor/shared --shared # mounts.json: committed with the projectodette mount # list both, and whether the next launch mounts eachodette mount rm ~/.trellisadd 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.
volumes.json
Section titled “volumes.json”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.
Plugins and marketplaces
Section titled “Plugins and marketplaces”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.
odette’s own marketplace
Section titled “odette’s own marketplace”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.
Adding marketplaces
Section titled “Adding marketplaces”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:
odette marketplace add org/market --plugins lint,review # this project, committedodette marketplace add ./vendor/tools # a folder inside the projectodette marketplace add ~/my-market --local # this project, this machineodette marketplace add JuliusBrussee/caveman --global # every projectodette marketplace listodette marketplace rm caveman # from whichever file declares itWithout --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:
odette marketplace plugins caveman # enabled, disabled and offeredodette marketplace plugins caveman --disable review # off, and kept offodette marketplace plugins caveman --enable review # on againA disabled plugin stays off when you apply a kit that declares it again;
odette kit apply says it left the plugin disabled.
Private marketplaces on GitHub
Section titled “Private marketplaces on GitHub”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 addasks 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.
The marketplace files
Section titled “The marketplace files”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 |
Where configuration comes from
Section titled “Where configuration comes from”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,/configchanges, 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 -gor 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.
Claude Code’s own settings
Section titled “Claude Code’s own settings”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 }}Feature flags
Section titled “Feature flags”Optional behaviour that is still being proven.
odette config # checkbox picker (in a terminal)odette config get # every setting and flagodette config set feature.status_row onodette 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.