claudia

Run Claude Code in an OS-native sandbox using Landlock on Linux and Seatbelt (sandbox-exec) on macOS.

Each profile gets its own isolated Claude config, cache, and conversation history. The host filesystem is read-only except for explicitly mounted directories.

See Getting started for install instructions, requirements, and first-run setup. The contract between claudia and what runs inside the sandbox is the guest ABI. Upgrading from 3.x? See the 3.x → 4.0 migration guide.

Usage

claudia                              # launch the agent in sandbox with cwd writable
claudia exec -- <cmd> [args...]      # run any command in the sandbox (no agent env)
claudia -a claude exec -- <cmd>      # ...with an agent's environment
claudia status                       # show profile config
claudia doctor                       # check for silent misconfiguration
claudia doctor --accept              # keep drifted seed files as they are
claudia shell                        # open a shell in the sandbox
claudia update                       # update claudia itself
claudia version                      # show claudia, agent and shim versions

claudia card list                    # installed agent cards
claudia card use codex               # make codex this profile's default agent
claudia -a codex prompt "take over"  # run a different agent for one invocation

claudia mount add <path>             # add a read-only path (default)
claudia mount add <path>:rw          # add a read-write path
claudia mount rm <path>              # remove a mounted path

claudia secret add K V               # set a secret (hidden from agent)
claudia secret add K                 # read value from stdin if piped, else prompt (no echo)
claudia secret add K -               # read secret value from stdin
claudia secret rm K                  # remove a secret

claudia config                       # show current profile config
claudia config set env.K V          # set a profile env var
claudia config rm  env.K            # remove a profile env var
claudia config add --scope seed env-host GOFLAGS   # seed a default for new profiles

claudia edit config                  # open profile config in $EDITOR
claudia edit prompt                  # edit profile CLAUDE.md
claudia edit statusline              # edit statusline script
claudia edit --scope seed prompt     # edit the seed CLAUDE.md (default for new profiles)

claudia resume                       # resume most recent session for cwd
claudia resume --list                # list resumable sessions

claudia audit                        # pretty-print audit log
claudia audit -n 50                  # print only the last 50 entries
claudia audit -f                     # print last 10 entries, then stream new ones (--follow)
claudia audit -f -n 50               # stream with 50 entries of backlog
claudia audit path                   # print audit log file path
claudia audit clear                  # truncate audit log

claudia reset mount                  # reset mounts (also: secret, env, prompt, env-host, ...)

claudia profile get                  # list profiles
claudia profile create               # check prerequisites, set up a profile
claudia profile use <n>              # switch active profile
claudia profile rm <n>               # delete a profile (--all for everything)

claudia memory                       # show the memory subcommands
claudia memory list                  # list current project + profile-global memories
claudia memory show <name>           # print memory body
claudia memory add --scope project   # draft a new project memory in $EDITOR
claudia memory add --scope profile   # draft a new profile-global memory
claudia memory add --scope seed      # draft a memory every new profile inherits
claudia memory edit <name>           # open memory in $EDITOR
claudia memory rm --scope project <name>...  # delete a project memory
claudia memory rm --scope profile <name>     # delete a profile-global memory

Running claudia with no arguments is the main workflow: it ensures the profile is set up, adds your current directory as writable, and launches the profile's agent inside the sandbox.

claudia does not install or house the agent binary — install it however you like and claudia resolves it from the sandbox PATH. claudia status prints which copy it resolved to, and its version.

Profiles

Each profile is fully isolated — its own agent state, conversations, cache, and writable paths. Profiles share nothing.

A profile is one security posture and one workspace identity; an agent is one binary and one state dir. They are orthogonal, so a profile can host several agents: they share its mounts, secrets, egress allowlist, memory and audit stream, and differ only in where their state lives. That is what makes hand-off a flag — claudia -a codex prompt "take this over" runs in the same cwd with the same everything.

claudia profile create work   # create a profile named "work"
claudia -p work               # run claude in the "work" profile
claudia profile get       # list all profiles
claudia profile use work  # set "work" as active profile

direnv integration

Add to ~/.config/direnv/direnvrc:

use_claudia() { eval "$(claudia profile load "$@")"; }

Then in any project's .envrc:

use claudia myproject

Plugins

claudia does not manage Claude Code plugins — Claude Code does. What claudia provides is the per-profile plugin dir (<profile>/plugins/, exported as CLAUDE_CODE_PLUGIN_CACHE_DIR and granted read-write-exec in the sandbox), so each profile's plugins stay isolated from every other profile's.

Install and manage them with the agent's own tooling, run inside the sandbox so they land in this profile:

claudia -a claude exec -- claude plugin marketplace add your-org/plugins
claudia -a claude exec -- claude plugin install my-tool@your-plugins

Same for MCP servers, which are likewise the agent's own config:

claudia -a claude exec -- claude mcp add playwright npx @playwright/mcp@latest

A server that needs a credential, its own binary on PATH, or a host in the egress allowlist needs a little more than that. See MCP servers.

Memories

Each profile keeps a file-backed memory store that Claude reads and writes across sessions. Memories survive /clear, --resume, and new conversations — they're how the agent remembers user preferences, project decisions, and prior corrections instead of relearning them every session.

Memories have two scopes:

• Project-local — under <profile>/memory/projects/<slug>/. Apply only to the current project.
• Profile-global — under <profile>/memory/profile/. Apply to every project in the profile. New profile-globals can be seeded into every new profile via ~/.local/share/claudia/seed/memories/ (see Seeding profiles).

Both scopes live in claudia's own directory, not inside an agent's state tree, so every agent in the profile reads the same notes — which is what makes claudia -a codex a hand-off rather than a fresh start.

Preload merges both at session start; on filename collision, project-local wins.

claudia memory                # show the memory subcommands
claudia memory list           # list memories (project + profile, with scope tags)
claudia memory add --scope project  # draft a new project-local memory
claudia memory add --scope profile  # draft a new profile-global memory
claudia memory show <n>       # print one memory's body
claudia memory edit <n>       # open in $EDITOR (resolves project then profile)
claudia memory rm --scope project <n>  # delete a project memory
claudia memory rm --scope profile <n>  # delete a profile-global

A SessionStart hook (claudia memory preload) injects the full body of every memory file into context at the start of each session, so recall doesn't depend on the agent guessing relevance from a one-line index hook.

See Memories workflow for the file format, the four memory types (user / feedback / project / reference), the pre-written / git-tracked draft workflow, and tips for writing memories Claude actually retrieves.

Style rules

A memory tells the agent what you prefer. A rule refuses the write that ignores it — which is the difference between an instruction that gets outvoted over a long session and one that cannot be.

claudia rules list                     # what's in effect here
claudia rules add --scope profile      # draft a rule in $EDITOR
claudia rules test <file>              # dry run against a file on disk
claudia config set rules.mode warn     # downgrade every rule to a warning

Each rule is a regex, a target (code, comment, commit, prose) and the instruction to show when it fires. A PreToolUse hook (claudia rules check) matches every Write, Edit and git commit against them: severity: block refuses the call and feeds the rule text back as the reason, severity: warn allows it and says so.

The rules directory is granted read-only in the sandbox. Memory is read+write because an agent recording what it learned is the feature; a rule is a constraint on the agent, and one it could edit is one it could relax.

See Style rules workflow for the file format, the two scopes, when to block versus warn, and what regexes deliberately cannot express.

Secrets

For tokens, API keys, and credentials, use claudia secret. Unlike profile config env values (which the agent can read directly), secret values are kept out of the agent's environment entirely. The agent sees a placeholder (NPM_TOKEN=__claudia_secret_NPM_TOKEN__); the real value is substituted at execve time, only for a curated set of wrapped tools.

claudia secret add NPM_TOKEN npm_abc123
claudia secret add GITHUB_TOKEN ghp_...
claudia secret get                     # list secret names (never values)
claudia secret rm NPM_TOKEN

Read a value from stdin instead of argv (avoids shell history capture):

pass show npm/token | claudia secret add NPM_TOKEN -

How it works

1. Values live in ~/.local/share/claudia/secrets/<profile>.json (mode 0600), outside any directory that's bind-mounted into the sandbox. The agent cannot read this file.
2. At launch, claudia starts a broker process outside the sandbox holding the values in memory, and creates ~/.local/share/claudia/runtime/<profile>/<pid>-<rand>/ containing the broker's unix socket and one shims/<tool> symlink → the installed claudia-shim per wrapped tool. No plaintext snapshot is written to disk.
3. The sandbox env gets a placeholder like NPM_TOKEN=__claudia_secret_NPM_TOKEN__. PATH is prefixed with the shims directory.
4. When the agent runs npm, the shim intercepts, fetches the values from the broker over the socket, substitutes them into its own env, strips itself from PATH, and syscall.Execs the real npm. From that point npm sees the real token; nothing else does.

Wrapped tools: npm, npx, yarn, pnpm, bun, git, gh, aws, s4cmd, gcloud, gsutil, bq, curl. Shells (bash, sh, zsh) and interpreters (python, node, ruby, perl, java, go) are deliberately not wrapped — wrapping a shell would leak the real values into any command the agent runs through that shell, including printenv.

Trust model

This is hardening, not containment. It prevents leakage into transcripts, agent self-inspection (process.env, /proc/self/environ, printenv), and normal tool output. What it buys concretely: no plaintext at rest, every access peer-authenticated so only the managed claudia-shim binary is served, and every access recorded in the audit log (claudia audit) from outside the sandbox, where the agent can neither forge nor suppress the record.

What it does not stop: an agent that can invoke a shimmed tool can still make that tool hand out its own secret — curl --data "$TOKEN" … substitutes the placeholder into the request, and the shim has no way to tell that apart from legitimate use. Authorizing a tool authorizes what it does with the secret it was given.

One platform caveat: with isolate_processes off, the broker is the session's own child under the same uid, so the agent can ptrace it. On the default Linux path the broker lives outside the session's PID namespace and that route is closed too.

How isolation works

Cross-platform

Path	Access	Purpose
/dev	read-write	device nodes (/dev/null, /dev/tty, etc.)
$PATH dirs under $HOME	read-only	user bin directories
~/.gitconfig, ~/.gitignore, ~/.npmrc, ~/.yarnrc, ~/.curlrc, ~/.wgetrc	read-only	tool config dotfiles
<profile>/<agent>/	read-write	per-profile agent state (CLAUDE_CONFIG_DIR, CODEX_HOME)
<profile>/cache/	read-write	per-profile cache (XDG_CACHE_HOME)
<profile>/plugins/	read-write	per-profile plugins + content (CLAUDE_CODE_PLUGIN_CACHE_DIR)
<profile>/	read-write	lockfiles
cwd and mounted paths	configurable	your project files

Everything else under $HOME — including ~/.ssh, ~/.aws, ~/.gnupg, and all other dotfiles and directories — is not accessible.

Environment variables are filtered to a safe allowlist (system, locale, toolchains, proxy settings). Host env vars like AWS_SECRET_ACCESS_KEY, GITHUB_TOKEN, etc. are not passed into the sandbox.

For non-secret env vars, use the profile config env key (claudia config set env.K V). Values set this way are visible to the agent.

For actual secrets (tokens, API keys, credentials), use claudia secret. The real value never enters the agent's environment — the agent sees a placeholder __claudia_secret_<NAME>__, and a small claudia-shim helper substitutes the real value at execve time, only for a curated list of wrapped tools (npm, npx, yarn, pnpm, bun, git, gh, aws, s4cmd, gcloud, gsutil, bq, curl). See the Secrets section below.

Cross-platform defaults

Both backends apply the same policy: deny-default on $HOME, with explicit allow rules per profile. On Linux this is enforced by Landlock (kernel ≥ 5.13); on macOS by Seatbelt.

Path	Access	Purpose
/bin, /sbin, /lib, /lib64, /usr, /nix	read+exec	system tools and libraries
/etc, /proc, /sys, /run, /var	read-only	system config and runtime
/dev	read+write	PTY, /dev/null, /dev/urandom
/tmp	read+write+exec	scratch dir (real /tmp, observable on host)
$HOME (default)	denied	only explicit mounts and dotfiles allowed
$HOME/.gitconfig, $HOME/.ssh/config, ...	read-only	dotfiles tools need

macOS only

Uses Seatbelt (sandbox-exec) to apply a deny-default policy.

Path	Access	Purpose
Everything outside $HOME	read-only	system tools and libraries
~/Library/Caches	read-write	tool caches (go, npm, etc.)
/private/tmp	read-write	temporary files
/private/var/folders	read-write	system temporary directories
$HOME	denied	reads blocked except for allowlisted paths above

Dotfile security

The dotfiles listed above are passed into the sandbox read-only. Do not store secrets directly in these files. Instead, use environment variable references and pass the values through the profile config.

npm — use a token variable in ~/.npmrc:

//registry.npmjs.org/:_authToken=${NPM_TOKEN}

Then set the token as a secret:

claudia secret add NPM_TOKEN npm_abc123...

npm is a wrapped tool, so it sees the real token at execve time via the shim. The agent itself only ever sees the placeholder NPM_TOKEN=__claudia_secret_NPM_TOKEN__, so transcripts never leak the token — even if the agent calls printenv in a Bash tool.

git — if your ~/.gitconfig includes credentials or tokens, move them to a credential helper or environment variable. The sandbox can read your gitconfig, so anything hardcoded there is visible inside the sandbox.

That same gitconfig usually sets commit.gpgsign, which cannot work in a sandbox where ~/.gnupg and ~/.ssh are blocked. See Git identity and SSH for the managed author and signing key that fixes it, and gives git push over SSH a key to use.

curl / wget — avoid storing credentials in ~/.curlrc or ~/.wgetrc. Use environment variables or pass auth headers explicitly. Note that curl is not currently a wrapped tool, so a secret value in its env would appear as the placeholder, not the real token. If you need curl to authenticate, either call it from within npm run/yarn run scripts, or pass the header explicitly from a script that reads the secret at runtime from a mounted file.

As a general rule: if a dotfile supports ${VAR} substitution, prefer that over hardcoded secrets, and set the variable with claudia secret rather than claudia config set env.* so the value is never visible to the agent.

Data

Everything lives in ~/.local/share/claudia/ (respects XDG_DATA_HOME):

cards/                      # one JSON file per agent — what an agent IS
  claude.json               # dir env names, agent env, egress hosts, argv, owned keys
  codex.json
  pi.json
seed/                       # user-owned source-of-truth for tunable defaults
  memories/                 # profile-global memory seed (*.md, copied on init)
  agents/<agent>/           # copied verbatim into a NEW agent state dir
    settings.json           # product opinions; yours to edit, yours to delete
    CLAUDE.md
    statusline.sh
  profile/
    env-host                # gitignore-style list, merged into config.env_host
    exec-dirs               # gitignore-style list, merged into config.exec_dirs
    shim                    # gitignore-style list, merged into config.shim
profiles.json               # profile registry
profiles/<name>.json        # profile config — NOT reachable from the sandbox
profiles/<name>/            # per-purpose grants into the sandbox
  cache/                    # XDG_CACHE_HOME (per-profile, shared by its agents)
  plugins/                  # per-profile plugin cache
  debug-logs/               # agent debug logs (read+write, no exec)
  scratch/                  # cwd of a `-t` launch, which mounts no project dir
  memory/                   # claudia's memories (read+write, no exec)
    profile/                #   profile-global, preloaded in full
    projects/<slug>/        #   scoped to one working directory
  git/                      # managed gitconfig, allowed_signers, signing .pub (read-only)
agents/<profile>/<agent>/   # per-agent state dir (CLAUDE_CONFIG_DIR, CODEX_HOME, ...)
sessions/index.jsonl        # what claudia has launched; backs `claudia resume`
sessions/<pid>/state.json   # live session state (the only part mounted, read-write)
audit/<name>/log.jsonl      # per-profile audit log (mounted; sibling dirs not reachable)
secrets/<name>.json         # per-profile secret store (NOT mounted; mode 0600)
keys/<name>/signing_ed25519 # signing/auth private key (NOT mounted in agent mode)
runtime/<name>/<pid>-<rand>/ # per-instance broker socket + shim symlinks
  broker.sock               # broker socket; values stay in broker memory
  shims/                    # symlinks to claudia-shim, one per wrapped tool
runtime/<name>/<pid>-agent/ # ssh-agent socket, git.signing = agent only

The directories under profiles/<name>/ are granted individually, each at the narrowest access that works — memory and debug-logs get no exec, the git dir is read-only. profiles/<name>.json is granted nothing at all: it holds the profile's security posture, so a sandboxed agent able to write it could set its own egress allowlist and mounts for the next launch. Agent homes live under agents/ for the same reason — the lock-by-mkdir their parent needs is safe only over a directory that holds nothing else. seed/ is the user-owned source-of-truth for tunable defaults — claudia profile create materializes starter files there from Go constants the first time around, then treats anything you've edited as authoritative on every subsequent init. The secrets/ and runtime/ siblings are deliberately outside the bind-mounted profile subtree: secrets/ is never mounted, and runtime/<name>/<pid>-<rand>/ is bind-mounted read-only via a separate explicit mount so only the shim — not the agent's other code paths — has a natural reason to reach it.

See Seeding profiles for what each seed file controls and how to back up / restore your tunable defaults.

Config

Profile config lives at <profile>/config.json. Edit with claudia edit config.

{
  "paths": [
    "/home/user/dev/project:rw",
    "/home/user/data:ro"
  ],
  "cache_dirs": [
    "~/.cache/go-build",
    "~/.cache/gopls",
    "~/.cache/npm",
    "~/.cache/bun",
    "~/.cache/uv",
    "~/.cache/pip",
    "~/.cache/nix",
    "~/.cache/node",
    "~/.cache/direnv"
  ],
  "exec_dirs": [
    "~/.cargo/bin:path",
    "/opt/homebrew/bin:path",
    "~/.local/share/mise"
  ],
  "env": {
    "NODE_ENV": "development"
  }
}

The env map is for non-secret environment variables — things visible to the agent, like NODE_ENV or AWS_PROFILE. For tokens and credentials, use claudia secret instead so values never appear in the agent's view. See the Secrets section.

exec_dirs grants subtrees read+exec, so tools installed outside the default system paths are runnable. An entry with a :path suffix also joins the sandbox PATH; one without is granted but not put on PATH.

That split is the point. A bin directory wants both (~/.cargo/bin:path). A toolchain store root wants only the grant — Go execs <GOROOT>/pkg/tool/*/compile, which lives outside any bin dir, so ~/.local/share/mise has to be readable and executable without a store root landing on PATH.

Dirs that do join PATH sit after the shim dir but before the host PATH, so they can override problematic host entries while never shadowing a secret-bearing tool's wrapper. PATH itself is protected and cannot be overridden via env.

Manage the list with claudia config add exec-dirs <dir>[:path] and claudia config rm exec-dirs <dir>[:path].