Troubleshooting
Find the symptom, then the fix. For the daemon’s own log, see
~/.odette/daemon.log; odette daemon status tells you whether it is up and
healthy.
Setup and keys
Section titled “Setup and keys”odette is not set up — run: odette setup
In a terminal odette runs setup for you, asking only about what is missing.
This message appears when there is no terminal to ask in (a script, a pipe):
run odette setup yourself. Setup keeps whatever is already there.
no SSH agent reachable: SSH_AUTH_SOCK not set and no IdentityAgent in ~/.ssh/config
No ssh-agent is running in this shell, which is common on a minimal Linux
or a remote login. Start one with eval "$(ssh-agent)", then ssh-add ~/.ssh/odette.
no usable keys in agent (need ed25519 or rsa)
Load a key: ssh-add ~/.ssh/odette, then check with ssh-add -l. Commands
other than odette setup print the same complaint as at-rest key: no usable keys in SSH agent (need ed25519 or rsa); the fix is the same.
no container runtime found — install Docker or Apple's container CLI
Setup found neither Docker nor Apple’s container CLI. Install one, start it,
and run odette setup again.
configured fingerprint not in agent
The key odette encrypts with isn’t loaded. ssh-add it again. If the key is
gone for good, run odette setup and pick another; what was stored under the
old key cannot be recovered (Security).
A command stops at starting daemon (will contact SSH agent for key derivation)...
Your SSH key needs a confirmation to sign (hardware key, Secure Enclave,
1Password). Confirm it on your machine. This is not a dashboard approval.
Claude sign-in
Section titled “Claude sign-in”The session shows odette: Anthropic rejected the credentials for profile "<name>" — run on the host: odette login --profile <name>
Run that command on your machine, not /login inside Claude Code. The session recovers on its next
request; no restart.
Sessions stop with “token expired”, or odette profiles says EXPIRED or no refresh token stored
The stored token can’t renew itself, usually because it was pasted with
--token. Run odette login for a normal sign-in.
--from-claude-cli needs the macOS Keychain
That option is macOS-only. Use odette login, or odette login --paste on a
machine without a browser.
Agents waiting or blocked
Section titled “Agents waiting or blocked”An agent seems stuck on a network request or command.
It is probably waiting for you. Look in the dashboard’s Inbox. Unanswered
requests are denied after approval_timeout (300 seconds by default).
A host is refused straight away, without asking.
It is on a deny list. Check the dashboard’s Rules zone and remove the
entry, or the line in .odette/domains.deny or ~/.odette/egress/global.deny.
datadoghq.com is always blocked.
An agent can’t write to .odette/ (Read-only file system).
By design. Edit those files on your machine.
git fetch or git push fails inside a session with cannot run ssh.
Sessions have no SSH client. Let the agent run the git command on your
machine through the command gate.
git push over HTTPS fails inside a session with Authentication failed.
By design. A session holds no GitHub credential, so it cannot push, or fetch a
private repository that is not an approved marketplace. Only fetching a public
repository works inside a session. Let the agent run the git command on your
machine through the command gate.
Text appears appended to what you were typing in a session. odette types short fixed messages into idle sessions: a reminder to read inbox replies, and the steps of a pod clear. Leave the prompt empty while those are expected.
Launching
Section titled “Launching”The launch asks [w] worktree / [o] overlap / [c] cancel and then says cancelled.
Another agent is already working in the shared tree and you didn’t answer
within 30 seconds. Launch again and choose, or use odette -w
(Sessions).
worktree <path> already exists; remove it …
A bare -w names the worktree after the new session, and a worktree with that
name is already on disk. Move your work out of it and remove it
(git worktree remove <path>), or name the worktree with --worktree=<name>.
home for <project> (profile <name>) has layout <n>, this odette needs <m>
The project’s Claude home was made by an odette that stored it differently.
Run the odette sessions home reset command the message prints: it keeps
conversations and memory and lets the rest be set up again.
A launch prints orphaned home(s) or overlay folder(s) use …
Some homes or overlay folders belong to project folders that no longer exist.
Nothing is deleted on its own. If a project only moved, run
odette sessions home mv <old-path> <new-path>; otherwise
odette sessions home prune --orphans removes them.
no running session with that name
odette sessions stop takes the name of a running session. odette sessions lists
them.
home is in use by a running session
odette sessions home rm, reset and mv refuse while a session of that project
runs, under any profile. Stop it (odette sessions stop <name>) and try again.
odette: WARNING — could not add marketplace <name> at session start
Claude Code could not fetch that marketplace; its own message is printed just
above. The session starts without that marketplace’s plugins. A private
GitHub repository is the usual cause: check that gh auth login is done on
your machine and that the repository was approved
(Private marketplaces on GitHub).
Otherwise fix the source, or remove the entry
(Configuration).
skipping marketplace "<name>": reading private <repo> with your GitHub login was not allowed
You denied the approval, or nobody answered within 10 minutes on a launch
with no terminal. The next launch asks again; odette marketplace rm <name>
stops it.
marketplace <name> is named "<other>" in its manifest
The entry’s name does not match the name the marketplace gives itself, so
Claude Code ignores the declaration. Set "name": "<other>" on the entry.
A plugin doesn’t work and the launch warned installDeps is no longer supported.
odette no longer installs a plugin’s packages. Claude Code installs npm
dependencies for some plugins itself, but not ones that use a yarn or pnpm
lockfile; such a plugin has to install them inside the session or ship them.
Linux: sessions cannot reach the daemon
Section titled “Linux: sessions cannot reach the daemon”On Linux, odette’s daemon listens on Docker’s bridge address, which it reads
from Docker (falling back to 172.17.0.1). If your bridge uses another
address and sessions can’t connect, set it yourself:
ip -4 addr show docker0 # note the inet addressODETTE_LISTEN_HOST=<address> odettemacOS with Apple container: a firewall prompt
Section titled “macOS with Apple container: a firewall prompt”The first time odette’s daemon starts, macOS asks whether it may accept incoming connections. Allow it; sessions can’t reach the daemon otherwise.
macOS with Apple container: no default kernel
Section titled “macOS with Apple container: no default kernel”On a machine where container was just installed, odette stops with
apple container has no default kernel. odette does not download one for you;
run the command it prints, then try again:
container system kernel set --recommendedDashboard
Section titled “Dashboard”The browser warns about the certificate. See Dashboard. Never trust the proxy certificate authority instead.
Forgot the dashboard password.
odette dashboard password sets a new one.
No desktop notifications. Click the bell in the rail and allow notifications for the page. Alerts are skipped while the dashboard tab is visible and focused.
Updating and cleaning
Section titled “Updating and cleaning”gh CLI not found in PATH from odette update
Install gh and run gh auth login.
permission denied replacing … — try: sudo odette update
The binary is in a root-owned folder. Use sudo, or move it to
~/.local/bin.
daemon is running — stop it first (odette daemon stop) from odette clean
Run odette daemon stop, then odette clean.
Can I use an API key instead of a subscription?
Yes: choose [2] in odette setup, or run odette login --token and paste an Anthropic API key.
Does odette send my code anywhere? Only an agent does, and only to hosts that are allowed or that you approve. Claude Code itself sends context to Anthropic, as it always does.
Can I run Claude Code’s permission prompts as well? No. odette starts Claude Code with them off; the sandbox and the gates are the checks.
What if the AI judge allows something I wouldn’t?
Every decision is recorded: the dashboard’s Activity history shows the
request with judge as the reason. Delete an allow entry in the Rules zone
to ask again, add a deny entry to block the host (a deny rule wins in every
mode), or set the gate to manual so nothing is decided without you
(Approvals). A command that was allowed has already
run; commit before a long run.
Does odette work offline? Mostly not. A session needs to reach Claude, and the first launch downloads Claude Code and builds the image. The judge needs the network too; when it cannot run, requests are held for you, never allowed. Reading the dashboard, rules and settings works without a network.
Can I run odette in CI? It is not built for that. A session starts Claude Code in an interactive terminal, and a held request waits for a person to answer it in the dashboard.
Where does my data go?
Stored secrets and settings stay in ~/.odette on your machine, encrypted
where they are secret. odette itself makes network calls to Anthropic (sign-in
renewal, the judge, model information), to Google if you use Google Workspace,
to GitHub for odette update, and to the git repositories you register for
kits and marketplaces. An agent sends data only to hosts that are allowed. See
Security.
Where does odette keep its files?
In ~/.odette, or ODETTE_DATA_DIR. Per-project settings are in .odette/
in each project (Configuration).