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.
What an agent can reach
Section titled “What an agent can reach”| 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 credentials
Section titled “Your credentials”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).
Limits
Section titled “Limits”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’scontainerwhere 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.
Organization policy
Section titled “Organization policy”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.
odette policyprints 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.
Encryption at rest
Section titled “Encryption at rest”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:
ssh-add -l # list the keys in the agentodette setup # pick a key againPicking 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
Section titled “The dashboard”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.