Getting started
odette runs Claude Code agents in sandboxed containers on your machine, so an agent can work in your project without reaching the rest of your files, your credentials or the internet unless you, or the AI judge, allow it. This page takes you from a fresh install to an agent working in your project, to the first request you approve, and to proof that the sandbox holds.
Install
Section titled “Install”You need:
- macOS on Apple silicon, or Linux (arm64 or amd64).
- A container runtime: Docker, or Apple’s
containerCLI. - A Claude Pro/Max subscription, or an Anthropic API key.
- An ed25519 or RSA key loaded in your
ssh-agent. odette uses it to encrypt everything it stores. - The
ghCLI, signed in with access to the releases (they are private for now).
Run the installer. It downloads the release for your platform, checks its
SHA-256 and puts odette in ~/.local/bin:
curl -fsSL https://getodette.io/install.sh | shIt prints a reminder if ~/.local/bin is not on your PATH. Installing there
keeps odette update free of sudo. To update later, see
Upgrading.
1. Load an SSH key
Section titled “1. Load an SSH key”odette encrypts everything it stores (your Claude token, its certificates, the
dashboard password) with a key derived from an ed25519 or RSA key in your
ssh-agent. Use a dedicated key, so rotating other keys never locks you out
of odette:
ssh-keygen -t ed25519 -f ~/.ssh/odette -C odettessh-add ~/.ssh/odetteAn SSH key is the one secret that works the same on macOS and Linux, and your
ssh-agent can make it ask you first: a hardware key,
Secure Enclave or 1Password prompts before every use. So someone who copies
your disk, or a program running as you, cannot decrypt odette’s files without
you noticing.
Keep this key. If you lose it, nothing odette stored can be decrypted and you
start again from odette setup. See Security.
2. Run setup
Section titled “2. Run setup”odette setupIt runs five steps, and you can re-run it at any time; each step offers to keep what is already there.
| Step | What happens |
|---|---|
| Container backend | Docker, or Apple’s container. With only one installed it is chosen for you; with both, you are asked and Docker is the default. |
| SSH Agent | Lists usable agent keys; you pick one by number. |
| Cryptographic material | Creates the proxy’s certificate authority and the dashboard’s certificate. On macOS it offers to trust the dashboard certificate in your login keychain, and removes the obsolete dashboard certificates earlier ones left there. |
| Dashboard password | Sets the password for the dashboard. |
| Claude authentication | [1] signs in with your Anthropic account in the browser; [2] takes a pasted API key or token. |
On macOS, if the claude CLI is installed on your machine, option [1] runs
its own login and imports the result. Otherwise odette opens the browser
itself.
When setup finishes it offers a few suggested
plugin marketplaces, one [y/N] each; none is added unless you say yes. A re-run offers only the ones you have not added.
See Plugins and marketplaces.
It then offers kits that apply to the whole machine, in the same way: one
[y/N] each, none applied unless you say yes. See Kits.
Last, it prints the gate modes, which start as judge:
Gates: commands judge, egress judge. Change them with `odette gates` or the dashboard.You do not have to run it first: in a terminal, the first command that needs
setup runs it for you and then carries on. After an upgrade that adds a
requirement, it asks only about the new part. Without a terminal, such a
command stops with odette is not set up — run: odette setup.
3. Start an agent
Section titled “3. Start an agent”cd ~/code/my-projectodetteThe first launch in a project:
- creates
.odette/(the same as runningodette initfirst; run it by hand if you want to edit the files before the first launch, see Configuration), - adds
.memory/to.gitignore, - allows the hosts of your git remotes, so the agent can fetch and push without asking,
- builds the container image and installs Claude Code (a few minutes, once),
- starts odette’s background service (the daemon).
Then it prints a line like:
odette 0.x (docker) — session swift-otter | egress proxied | web https://localhost:7900/and Claude Code starts in your terminal, in plan mode. Claude Code’s own permission prompts are switched off: the container and odette’s checks take their place.
swift-otter is the session’s name, chosen at random. When you quit Claude
Code, the container is removed. Conversation history and Claude settings are
kept in the project’s Claude home, so you can pick up again with
odette -- --continue. See Sessions.
4. Open the dashboard
Section titled “4. Open the dashboard”Open the printed address, or run odette dashboard, and sign in with the
dashboard password. If your
browser warns about the certificate, see
Dashboard.
5. Approve the first request
Section titled “5. Approve the first request”By default the AI judge decides routine requests, so you may never see one. To see an approval, make this one session ask you about everything. In a second terminal, use the session name from the launch line:
odette gates egress manual --session swift-otterOnly that session changes; the global mode stays judge. Then ask the agent to
fetch something from a host that isn’t allowed yet, such as
curl https://example.com. The request is held, and the dashboard’s
Overview shows it under what is waiting on you.
- Allow once lets this one request through.
- Deny refuses it.
- Open it in the Inbox to allow or deny it for this project or for every project, so you aren’t asked again.
To hand the session back to the global mode, run
odette gates egress inherit --session swift-otter. How much odette asks you,
and what the choices mean, is in Approvals.
6. Check that the sandbox holds
Section titled “6. Check that the sandbox holds”Don’t take the claims on trust. In the session (ask the agent to run these, or
open odette shell), try what a sandbox must stop:
cat ~/.ssh/id_ed25519 # your keys are not therecurl -m 5 --noproxy '*' https://example.com # no way out except odetteThe first fails with No such file or directory: the session sees your project
and its own home, not your ~/.ssh. The second fails: with the proxy bypassed,
the container has no route to the internet (typically a timeout such as
curl: (28); the exact message depends on the container runtime). Only
connections that go through odette, and that its gates allow, get out. What
the sandbox does not cover is on Security.