Skip to content

Security

odette protects you in two ways: the sandbox limits what an agent can reach, and encryption at rest limits what someone who reads your disk gets. Your real credentials never enter an agent’s container: odette adds them to each request on the way out.

An agent can An agent cannot
Read and write your project folder. Write to the project’s .odette/ folder (it is read-only inside).
Read and write its Claude home (conversation history, Claude settings), which the project’s other sessions under the same profile share. See the rest of your files, your ~/.ssh, your SSH agent, or odette’s stored secrets.
Read and write folders you mount read-write with --mount-rw or odette mount add --rw, and the odette-exchange folder in your home folder (~/odette-exchange on your machine, odette-exchange in the session’s home). Open a network connection that doesn’t go through odette.
Reach hosts that are allowed, plus those you approve. See your real Claude token, Gemini key or Google token.
Ask odette to run a command on your machine, through the command gate. Change its own allowlist, gate mode or mounted folders.

Two things deserve care:

  • Host commands run as you. A command you allow through the command gate runs on your machine, outside the sandbox, with your permissions. Read it before you allow it. Commands that could write to .odette/ or odette’s data folder are always held for you, in every gate mode.
  • Allowed hosts are open in both directions. An agent that can reach a host can send it your project’s contents. Some hosts are reachable without asking (Approvals), including all of googleapis.com. Deny a host to block it.

Claude Code runs with its own permission prompts off; the sandbox and the gates replace them.

Git over SSH does not work inside a session (there is no SSH client or key). Over HTTPS a session can fetch public repositories and approved marketplaces, but cannot push: it holds no GitHub credential. Let the agent run git push on your machine through the command gate.

Your Claude token, Gemini key and Google tokens never enter a container. A session holds a placeholder; odette swaps in the real credential on each request, only for the service it belongs to, and only over an encrypted connection.

To do that, odette decrypts traffic to those services with its own certificate authority, which every session trusts.

Never trust odette’s certificate authority on your own machine (the files in ~/.odette/ca/). It can issue a certificate for any website, so anyone holding its key could impersonate any site to you. The dashboard has a separate certificate that is safe to trust (Dashboard).

odette narrows what an agent can do. It does not make a hostile or mistaken agent harmless. Know where it stops:

  • The judge can be wrong. It decides from the host, or from the command and the method and address of a request, never from the content an agent sends. Something it allows may be something you would have refused. Use manual where a wrong “yes” costs you (Approvals).
  • Text the agent reads can steer it. A web page, a file or a package’s README can carry instructions the agent follows. odette does not detect that. It limits the damage to what the gates allow, so keep commands on manual and be slow to allow hosts that take uploads.
  • An allowed host can receive anything the agent can read. That includes your project’s files and everything in a folder you mounted. A host is allowed or it is not; odette does not filter what is sent to it.
  • Isolation depends on the container runtime. With Apple’s container, each session runs in its own virtual machine. With Docker, sessions share your machine’s kernel, so a flaw in the kernel or in Docker can let a session out. Choose Apple’s container where you can (Configuration).
  • Your project and mounted folders are not protected from the agent. It can change or delete anything it can write. Commit before a long run.
  • Claude Code’s own permission prompts are off. The sandbox and the gates replace them; there is no second line of defence inside the session.

If your organization restricts Claude Code with managed settings (a policy file on your machine, or settings your administrators set on claude.ai), odette applies that policy to every session. It copies the machine’s policy in at each launch, so a change reaches the next session, and where the policy and odette disagree the policy wins. Settings your administrators set on claude.ai are fetched by Claude Code itself.

odette tells you every time. Each launch says that a policy is in force, where it was read from, what it restricts and, if it differs from the last launch in that project, what changed. The terminal status row and the session’s entry in the dashboard carry an “organization policy” marker while the session runs, and the Sessions page of the dashboard lists the policy read-only.

Terminal window
odette policy

prints the policy in force and what it restricts.

odette refuses to start a session when the policy forbids what it needs, and has no flag to override that:

  • Bypass mode is disabled. odette keeps Claude Code’s permission prompts off on purpose: its protection is the container, the egress proxy and the command gates. Ask your administrators for an exception for odette.
  • Only managed MCP servers are allowed. odette’s host tools (the exec-daemon) are not one, so the session would have no way to reach the host. Ask your administrators to allow it.

A marketplace or plugin the policy does not allow is left out: the launch lists what it dropped and starts without it.

Everything secret odette stores is encrypted with AES-256-GCM. The key is derived from the SSH key you picked in odette setup, by asking your ssh-agent to sign with it. The key is only held in memory, never written to disk. Your SSH private key never leaves the agent.

Secret File under ~/.odette/
Claude token, per profile profiles/<name>/credentials.enc
Service API keys (Gemini), per profile profiles/<name>/<service>.key.enc
Proxy certificate authority key ca/ca-key.enc
Dashboard certificate key webui/webui-key.enc
Dashboard password (hashed) web.passhash.enc
Dashboard sign-in keys web.cookiekey.enc, web.cookiegen.enc

The chosen key’s fingerprint is saved as ssh_key_fingerprint in config.json. Every command that needs a secret asks the agent to sign again, so the key must stay loaded. If your key needs a confirmation to sign (a hardware key, Secure Enclave, 1Password), confirm on your machine when odette starts.

Keep the SSH key. If it is lost or no longer in the agent, nothing odette stored can be decrypted. To check or switch keys:

Terminal window
ssh-add -l # list the keys in the agent
odette setup # pick a key again

Picking a different key does not re-encrypt what is already stored. Setup then creates new certificates and asks for a new dashboard password and a new Claude sign-in. Sign any other profiles in again with odette login --profile <name>, and set their Gemini keys again.

The dashboard listens only on your own machine, over HTTPS, behind your password. Sign-ins last 7 days; changing the password (odette dashboard password) or signing out ends every sign-in.

Theme