Skip to content

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.

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.

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.

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.

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.

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:

Terminal window
ip -4 addr show docker0 # note the inet address
ODETTE_LISTEN_HOST=<address> odette

macOS 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:

Terminal window
container system kernel set --recommended

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.

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).

Theme