Skip to content

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.

You need:

  • macOS on Apple silicon, or Linux (arm64 or amd64).
  • A container runtime: Docker, or Apple’s container CLI.
  • 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 gh CLI, 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:

Terminal window
curl -fsSL https://getodette.io/install.sh | sh

It prints a reminder if ~/.local/bin is not on your PATH. Installing there keeps odette update free of sudo. To update later, see Upgrading.

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:

Terminal window
ssh-keygen -t ed25519 -f ~/.ssh/odette -C odette
ssh-add ~/.ssh/odette

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

Terminal window
odette setup

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

Terminal window
cd ~/code/my-project
odette

The first launch in a project:

  • creates .odette/ (the same as running odette init first; 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.

Open the printed address, or run odette dashboard, and sign in with the dashboard password. If your browser warns about the certificate, see Dashboard.

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:

Terminal window
odette gates egress manual --session swift-otter

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

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:

Terminal window
cat ~/.ssh/id_ed25519 # your keys are not there
curl -m 5 --noproxy '*' https://example.com # no way out except odette

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

Theme