Deployment¶
Local development¶
uv sync
CASAPI_ALLOW_UNAUTHENTICATED=true uv run uvicorn casapi.main:app --host 127.0.0.1 --port 8000
Remote server¶
- Install dependencies on the server:
-
Authenticate Claude on the server. The SDK spawns the Claude Code CLI, so either set
ANTHROPIC_API_KEYin the environment file below, or log in once withclaudeas the user that runs the service. -
Create
/etc/casapi.env(mode0600):
CASAPI_API_KEY=<long random secret, e.g. openssl rand -hex 32>
CASAPI_WORKSPACE_ROOT=/srv/workspaces
ANTHROPIC_API_KEY=sk-ant-...
-
Run uvicorn on loopback or a private interface, and expose it only through TLS (a reverse proxy) or a private network such as Tailscale or an SSH tunnel (
ssh -L 8000:127.0.0.1:8000 server). Disable proxy response buffering for/v1/query/stream(casapi sendsX-Accel-Buffering: no). -
Run it as an unprivileged user that owns only the workspace directory. Workspace confinement limits the starting
cwd, not whatBashcan reach. The agent inherits this environment file, so a run can readCASAPI_API_KEYandANTHROPIC_API_KEYfrom its own environment — the API key is effectively a shell as this user (see the README security model). The concurrency limit is per process: running uvicorn with--workers NmultipliesCASAPI_MAX_CONCURRENCYby N.
systemd unit¶
[Unit]
Description=casapi
After=network-online.target
[Service]
User=casapi
WorkingDirectory=/opt/casapi
EnvironmentFile=/etc/casapi.env
ExecStart=/opt/casapi/.venv/bin/uvicorn casapi.main:app --host 127.0.0.1 --port 8000
Restart=on-failure
NoNewPrivileges=true
[Install]
WantedBy=multi-user.target
Bash sandbox (optional)¶
Runs that send sandbox: true execute Bash inside the Claude CLI sandbox.
- Prerequisites on the host:
bwrap(bubblewrap),socat, andrg(ripgrep). - Sandboxed runs are pinned to the CLI bundled with the installed
claude-agent-sdk(cli_path), never anyclaudeonPATH; if the bundled executable is missing or not executable the request fails (503). Its version decides how sandbox settings are interpreted, so redo the probe below after every SDK update. - Sandboxed requests are rejected (403) when the effective permission mode is
autoorbypassPermissions, and when the working directory overlaps~/.cache(for example a workspace root equal to the service home with nocwd). KeepCASAPI_WORKSPACE_ROOTaway from the service home, or ensure clients send acwdbelow a project directory. ~/.cache/casapi-sandboxis created with mode 0700 on first use; it must be a real directory owned by the service user (symlinks are rejected). Its mode is set to and verified as exactly 0700, and~/.cacheitself must not be group- or other-writable; otherwise requests fail with 503.CASAPI_SANDBOX_MODEaccepts exactlyofforopt-in; anything else aborts startup.- The sandbox is fail-closed. On Ubuntu releases that ship the
bwrap-userns-restrictAppArmor profile, the sandbox's seccomp helper cannot start, sosandbox: truerequests fail until the host policy is adjusted (for example with a dedicated, AppArmor-profiled copy ofbwrapplaced first on the servicePATH). Do not weaken this by disabling the sandbox checks.
To enable it:
- Set
CASAPI_SANDBOX_MODE=opt-in(optionallyCASAPI_SANDBOX_ALLOWED_DOMAINS) and restart the service. - Run an acceptance probe with
sandbox: true:echo oksucceeds; writes outside the working directory and the sandbox cache are denied; secret directories such as~/.sshare unreadable;envshows noCASAPI_API_KEY;curlto a non-allow-listed host is denied; andsystemctl --user statusfails.
Clients must never retry a failed sandbox: true request with
sandbox: false; that would reintroduce fail-open behaviour.
Client smoke test¶
From the client machine (here via an SSH tunnel on localhost:8000):
curl -sS http://localhost:8000/health
curl -sS http://localhost:8000/v1/info -H "Authorization: Bearer $CASAPI_API_KEY"
curl -sS http://localhost:8000/v1/query \
-H "Authorization: Bearer $CASAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt": "Reply with the single word: pong", "max_turns": 1}'
A 200 response with "result": "pong" confirms authentication, Claude
credentials, and the SDK/CLI path all work.