devondragon/cyrus-claude-code-linux-docker-setup.md

## cyrus-claude-code-linux-docker-setup.md

      
    Raw
  

              cyrus-claude-code-linux-docker-setup.md
            
          
    Cyrus + Claude Code on a Local Linux Server (Docker)

A step-by-step guide to running Cyrus as a 24/7 background agent on your own Linux box, driven by Linear, with Claude Code authenticated through your Max 20x subscription so the work draws from your subscription instead of pay-as-you-go API billing.
Last verified: June 2026 · cyrus-ai v0.2.65 · Claude Code 2.1.x · AlmaLinux 9 Docker host.

This guide is battle-tested against cyrus-ai v0.2.65 / Claude Code 2.1.x on an AlmaLinux 9 Docker host. It includes a number of fixes the upstream docs don't mention. Each is called out inline with ⚠️ Why so you understand what you're working around. Follow it top to bottom and you'll get a working loop on the first pass.


Billing model and status (verified June 2026). Cyrus drives the real Claude Code CLI in headless mode, authenticated with the documented CLAUDE_CODE_OAUTH_TOKEN from claude setup-token. With that subscription token, runs draw from your normal Claude subscription rather than platform.anthropic.com pay-as-you-go API billing. Anthropic had announced that on June 15, 2026, Agent SDK and claude -p usage would move off subscription limits onto a separate monthly Agent SDK credit, but postponed that change on the day it was due. For now, agent and headless usage keeps running against your subscription exactly as before, with no separate credit to claim and subscription limits unchanged, and Anthropic has said it will give advance notice before any future change. Note that most public write-ups still describe the credit as live, so treat the billing model as in flux and confirm your current usage at claude.ai/settings/usage. Whatever the model, the rule below holds: keep ANTHROPIC_API_KEY out of the environment so you stay on subscription auth and off metered API billing.


What you're building

A single Docker container (cyrus, the agent runner) that watches Linear for issues delegated to it, spins up an isolated git worktree per issue, runs a sandboxed Claude Code session, and opens a PR.
Linear reaches it over your existing cloudflared tunnel. The container publishes its port on loopback only (127.0.0.1:3456), and you add one public hostname route to the tunnel you already run.
State lives in two named Docker volumes so it survives restarts:

cyrus-data → /home/cyrus/.cyrus: config.json, cloned repos, worktrees, Linear tokens, the egress CA.
cyrus-claude → /home/cyrus/.claude: Claude Code conversation transcripts. Persisting this is mandatory: without it, every container restart loses in-flight sessions and makes existing issues' agent sessions unresumable (No conversation found with session ID …).

The Bash sandbox (egress allowlist + filesystem isolation) runs via bubblewrap inside the container, which requires relaxing two container security options, covered in Step 4.

The one thing that decides whether this is "free"

Cyrus accepts two Claude Code auth methods. They are not interchangeable for your purpose:


Method
Env var
Where it bills


API key (the Cyrus README's default)
ANTHROPIC_API_KEY
Your API account, full pay-as-you-go rates, no credit offset


OAuth token (use this one)
CLAUDE_CODE_OAUTH_TOKEN
Your Max 20x subscription (normal usage limits)


Use CLAUDE_CODE_OAUTH_TOKEN. Make sure ANTHROPIC_API_KEY is not present anywhere in the environment, or Claude Code will silently prefer it and bill the API account. This is the exact mistake that has produced four-figure surprise bills.
With subscription auth, headless Claude Code draws from your normal Claude subscription, not a separate metered API bill. Default the agent to Sonnet to keep it light on your subscription limits, and reserve Opus for tickets that need it. Model selection is covered in Step 8.

Prerequisites


A Linux server with Docker Engine and the Docker Compose plugin.
Linear workspace admin access (required to create an OAuth app).
A domain managed in Cloudflare (you'll point a subdomain like cyrus.yourdomain.com at the tunnel).
A machine where you already run Claude Code (your laptop) to mint the OAuth token.
A fine-grained GitHub PAT scoped to only the repos you want the agent to touch (Contents + Pull Requests: read/write). Do not use a broad classic token.
The host kernel must allow user namespaces (default on RHEL/AlmaLinux 9; the container relaxes seccomp to use them, see Step 4). Verify with cat /proc/sys/user/max_user_namespaces (should be > 0).


Step 1: Mint the subscription OAuth token (on your laptop)

On a machine where Claude Code is installed and logged in to your Max account:
claude setup-token
This prints a long-lived OAuth token tied to your subscription. Copy it. You'll paste it into the server's env file in Step 4. Keep it secret; treat it like a password.

Step 2: Create the Linear OAuth application


In Linear, click your workspace name (top-left) → Settings → API (under the Account section) → OAuth Applications.
Click Create new OAuth Application and fill in:

Name: Cyrus
Description: Self-hosted Cyrus agent
Callback URL: https://cyrus.yourdomain.com/callback


Enable the Client credentials toggle.
Enable the Webhooks toggle, then configure:

Webhook URL: https://cyrus.yourdomain.com/linear-webhook
App events. Check Agent session events (required; this is what makes Cyrus show up as an assignable agent), and optionally Inbox notifications and Permission changes.


Save, then copy these three values (the secret may only be shown once):

Client ID
Client Secret
Webhook Signing Secret


The webhook is authenticated by that signing secret, so the /linear-webhook path can be publicly reachable through the tunnel without additional gating.

Note: "Authorized Applications" (the user grant under your Linear account) is different from the OAuth app itself. If you revoke the authorization to retry the flow, the OAuth app and its Client ID/Secret stay valid. You just need to re-run self-auth-linear to mint a fresh token. You do not need to recreate the app.


Step 3: Add a route to your existing Cloudflare Tunnel

You already run cloudflared with other hostnames, so this is just one new public hostname pointing at the cyrus container's loopback-published port.
If your tunnel is dashboard/token-managed (Zero Trust → Networks → Tunnels → your tunnel → Public Hostnames), add:

Subdomain/Domain: cyrus / yourdomain.com
Service: HTTP → localhost:3456

If your tunnel is config-file managed, add an ingress rule alongside your existing ones:
ingress:
  - hostname: cyrus.yourdomain.com
    service: http://localhost:3456
  # ... your other rules ...
  - service: http_status:404
This works because the cyrus container publishes its port to 127.0.0.1:3456 on the host (Step 4). Binding to loopback keeps it off the public internet; only the tunnel can reach it.

⚠️ If you protect your domain with Cloudflare Access (e.g. a wildcard *.yourdomain.com Access policy in Zero Trust), it will intercept cyrus.yourdomain.com and redirect Linear's webhook POSTs to a login page. The agent then never fires. Add an Access application for cyrus.yourdomain.com with a Bypass policy (Everyone). A path-scoped bypass for just /linear-webhook is the most surgical option (keeps the rest behind Access); bypassing the whole host is simplest. The webhook is signature-verified, so a public /linear-webhook is safe by design.
⚠️ If localhost resolves to IPv6 (::1) on your host and you see intermittent 502s, set the tunnel Service to http://127.0.0.1:3456 instead of localhost:3456 to force IPv4 (Docker publishes the port on IPv4 only). Most hosts are fine with localhost; this is a fallback.


Step 4: Project files on the server

Create a working directory, e.g. ~/cyrus-stack/, with the four files below.
cyrus.env

# --- Claude Code auth (subscription credit path) ---
CLAUDE_CODE_OAUTH_TOKEN=paste-token-from-step-1
# Leave ANTHROPIC_API_KEY UNSET. Its presence overrides the OAuth token and bills the API account.
# NOTE: ANTHROPIC_MODEL does NOT control Cyrus's model; use CYRUS_CLAUDE_DEFAULT_MODEL below.

# --- Cyrus server ---
LINEAR_DIRECT_WEBHOOKS=true
CYRUS_BASE_URL=https://cyrus.yourdomain.com
CYRUS_SERVER_PORT=3456
# REQUIRED in Docker: bind 0.0.0.0 INSIDE the container so Docker's port-forward can reach it.
# Without this, Cyrus binds container-localhost and is unreachable through the tunnel (502s).
# The host still only publishes on 127.0.0.1:3456, so it stays private.
CYRUS_HOST_EXTERNAL=true

# --- Default model (the REAL Cyrus lever; see Step 8) ---
CYRUS_CLAUDE_DEFAULT_MODEL=sonnet

# --- Linear OAuth (from Step 2) ---
LINEAR_CLIENT_ID=your_client_id
LINEAR_CLIENT_SECRET=your_client_secret
LINEAR_WEBHOOK_SECRET=your_webhook_signing_secret

# --- GitHub (for opening PRs) ---
GH_TOKEN=your_fine_grained_pat
GIT_AUTHOR_NAME=Cyrus Agent
GIT_AUTHOR_EMAIL=cyrus@yourdomain.com
GIT_COMMITTER_NAME=Cyrus Agent
GIT_COMMITTER_EMAIL=cyrus@yourdomain.com
Lock it down: chmod 600 cyrus.env.

⚠️ CYRUS_HOST_EXTERNAL=true is the single most important addition. The Cyrus server binds localhost inside the container by default; Docker's published port forwards to the container's bridge IP, so the app is unreachable and the tunnel returns 502 / "connection reset". This env var makes it bind 0.0.0.0 inside the container while the host still publishes loopback-only.

claude-settings.json

This is Claude Code's user settings, baked into ~/.claude so the Bash sandbox can write git worktree metadata and read the egress CA. (Details in the "Sandbox inside Docker" box below.)
{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": [
        "/home/cyrus/.cyrus/repos",
        "/home/cyrus/.cyrus/worktrees"
      ],
      "allowRead": [
        "/home/cyrus/.cyrus/certs/cyrus-egress-ca.pem"
      ]
    }
  }
}
Dockerfile

FROM node:20-bookworm-slim

# System deps:
#   git, jq (Claude Code parsing), gh (PRs), certs/curl/gnupg for the gh apt repo
#   socat + bubblewrap: REQUIRED by Claude Code's Bash sandbox on Linux
RUN apt-get update && apt-get install -y --no-install-recommends \
        git jq curl ca-certificates gnupg openssh-client socat bubblewrap \
 && mkdir -p -m 755 /etc/apt/keyrings \
 && curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg \
        | tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null \
 && chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg \
 && echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" \
        > /etc/apt/sources.list.d/github-cli.list \
 && apt-get update && apt-get install -y --no-install-recommends gh \
 && rm -rf /var/lib/apt/lists/*

# Claude Code + Cyrus
RUN npm install -g @anthropic-ai/claude-code cyrus-ai

# Make git use gh (which reads GH_TOKEN from the env) as the HTTPS credential helper,
# so `git clone https://github.com/...` works non-interactively in the container.
# System scope (/etc/gitconfig) so it applies to the non-root cyrus user too.
RUN git config --system credential."https://github.com".helper "!gh auth git-credential" \
 && git config --system credential."https://gist.github.com".helper "!gh auth git-credential"

# Non-root runtime user. Pre-create BOTH state dirs owned by cyrus BEFORE declaring the
# VOLUMEs, so the named volumes inherit cyrus ownership on first creation. Otherwise the
# volume root is owned by root and the cyrus user gets EACCES (mkdir .cyrus/repos fails).
RUN useradd -m -s /bin/bash cyrus \
 && mkdir -p /home/cyrus/.cyrus /home/cyrus/.claude \
 && chown -R cyrus:cyrus /home/cyrus/.cyrus /home/cyrus/.claude

# Seed Claude Code user settings into the image. A fresh named volume mounted at
# ~/.claude initializes from this, so the sandbox filesystem grants are present.
COPY --chown=cyrus:cyrus claude-settings.json /home/cyrus/.claude/settings.json

USER cyrus
WORKDIR /home/cyrus

VOLUME ["/home/cyrus/.cyrus", "/home/cyrus/.claude"]

ENTRYPOINT ["cyrus"]
docker-compose.yml

services:
  cyrus:
    build: .
    image: cyrus-local
    container_name: cyrus
    restart: unless-stopped
    env_file:
      - ./cyrus.env
    volumes:
      - cyrus-data:/home/cyrus/.cyrus
      - cyrus-claude:/home/cyrus/.claude   # persist Claude Code transcripts across restarts
    ports:
      - "127.0.0.1:3456:3456"   # loopback only; your existing cloudflared reaches it here
    mem_limit: 8g               # starting point; size for concurrency (see sizing note)
    pids_limit: 4096            # each sandboxed session spawns many procs (bwrap/node/git/socat); 512 throttles parallelism
    security_opt:
      - seccomp=unconfined      # bubblewrap needs to create user namespaces
      - systempaths=unconfined  # unmask /proc so bubblewrap can mount a fresh proc in its PID namespace

volumes:
  cyrus-data:
  cyrus-claude:

📏 Sizing for concurrency. Cyrus has no global concurrency cap. Every assigned issue launches a session in parallel the moment its webhook lands (bounded only by these limits and Claude rate limits). So mem_limit/pids_limit are your concurrency governor. A single build session comfortably fits in a couple of GB and ~100–200 processes, so scale roughly with how many issues you want running at once: a small VPS might stay at 4g/512 (a few at a time), while a large box can go much higher, e.g. 32g / 8192 on a 128 GB host for many concurrent sessions, leaving the rest of the host untouched. Edit the two lines and docker compose up -d to apply (a ~5 s recreate; the volumes persist, so no data loss). Verify with docker inspect cyrus --format '{{.HostConfig.Memory}} {{.HostConfig.PidsLimit}}'.


⚠️ Running the Bash sandbox inside Docker. Cyrus's egress allowlist is enforced by Claude Code's bubblewrap sandbox, which by default cannot run in an unprivileged container. Two security_opt relaxations make it work:

seccomp=unconfined: lets bubblewrap create the user namespace (otherwise: "No permissions to create new namespace").
systempaths=unconfined: unmasks Docker's read-only /proc paths so bubblewrap can mount a fresh /proc in its PID namespace (otherwise: "Can't mount proc on /newroot/proc: Operation not permitted").

The container is still non-root, capability-dropped, memory/pid-limited, and loopback-only. You're trading the container's syscall filter for the egress domain allowlist, which is the more valuable control for an unattended agent.
Don't want to relax seccomp? Set "enabled": false under sandbox in config.json (Step 7) and drop the two security_opt lines. The agent runs with no extra setup but has unfiltered network egress during Bash steps. Fine for throwaway repos, weaker for real ones. (You can't keep egress filtering without bubblewrap; the two are coupled.)


Step 5: First-run setup (one-time)

5a. Build the image

cd ~/cyrus-stack
docker compose build
5b. Seed an empty config.json


⚠️ self-auth-linear refuses to run without an existing config.json ("Config file not found … Run 'cyrus' first"), and nothing auto-creates it. Seed a minimal one into the volume first:

docker run --rm -v cyrus-stack_cyrus-data:/home/cyrus/.cyrus --entrypoint sh cyrus-local \
  -c 'printf "%s" "{\"repositories\": []}" > /home/cyrus/.cyrus/config.json'
5c. Authorize with Linear

Your tunnel route from Step 3 must be live and https://cyrus.yourdomain.com resolving first (you'll get a connection error until the container is up, that's fine).
# --service-ports publishes 127.0.0.1:3456 so cloudflared can route /callback back
# to this one-off container. Keep this running until you've authorized.
docker compose run --rm --service-ports cyrus self-auth-linear
It prints an authorization URL. Open it on your laptop, click Authorize. The redirect flows through your tunnel to the container, and the token is saved into the cyrus-data volume.

⚠️ Don't curl the /callback path to "test" reachability while this is running. A code-less request to /callback is treated as the OAuth callback and terminates the one-shot server. To check the tunnel reaches the container, hit /status instead (returns 404 on the auth server, which still proves reachability).

5d. Connect a repository

docker compose run --rm cyrus self-add-repo \
  https://github.com/yourorg/yourrepo.git "Your Workspace Name"
The second argument is the display name of your Linear workspace. This clones the repo into the volume (using the gh credential helper baked into the image) and wires it to your workspace. Repeat for each repo.
5e. Verify tokens

docker compose run --rm cyrus check-tokens
You want ✅ Valid. If it says Invalid – not authenticated, the most common cause is that the Authorized Application was revoked in Linear, re-run 5c.

Step 6: Start the agent

docker compose up -d
docker compose logs -f cyrus
Healthy startup shows, among other lines:
🛡️  Sandbox egress proxy: starting...
[EgressProxy] Listening — HTTP :9080, SOCKS :9081
✅ Linear event transport registered (direct mode)
[SharedApplicationServer] Shared application server listening on http://0.0.0.0:3456   ← 0.0.0.0, thanks to CYRUS_HOST_EXTERNAL
Edge worker started successfully
📦 Managing 1 repositories

Sanity-check the tunnel reaches the live server (non-destructive paths):
curl -s -o /dev/null -w "%{http_code}\n" https://cyrus.yourdomain.com/status          # 200
curl -s -o /dev/null -w "%{http_code}\n" -X POST https://cyrus.yourdomain.com/linear-webhook -d '{}'   # 403 (signature check working)
A 403 on a forged webhook is correct, it's the signature check rejecting an unsigned payload. restart: unless-stopped keeps it running 24/7 and brings it back after a reboot.

Step 7: Harden config.json for cost and safety

Cyrus stores config at ~/.cyrus/config.json inside the volume and hot-reloads changes (no restart needed). Inspect/edit:
docker compose exec cyrus sh -c 'cat ~/.cyrus/config.json'
self-add-repo already created the repositories[] entry and linearWorkspaces (with your tokens). Merge the following in. Don't overwrite the credentials or the repo entry:
{
  "promptDefaults": {
    "scoper":   { "allowedTools": "readOnly" },
    "debugger": { "allowedTools": "safe" },
    "builder":  { "allowedTools": "safe" }
  },
  "userAccessControl": {
    "allowedUsers": [ { "email": "you@yourdomain.com" } ],
    "blockBehavior": "comment"
  },
  "sandbox": {
    "enabled": true,
    "networkPolicy": { "preset": "trusted" }
  },
  "repositories": [
    {
      "// keep the fields self-add-repo created (id, name, repositoryPath, baseBranch, linearWorkspaceId, …)": "and ADD:",
      "allowedTools": ["Read", "Edit", "Bash(git:*)", "Bash(gh:*)", "Bash(npm:*)", "Task"],
      "labelPrompts": {
        "scoper":   { "labels": ["PRD", "RFC"] },
        "debugger": { "labels": ["Bug"] },
        "builder":  { "labels": ["Feature", "Improvement"] }
      }
    }
  ]
}

⚠️ sandbox goes TOP-LEVEL, not inside repositories[]. Cyrus reads sandbox from the root of the config; nesting it under a repository silently disables it (the egress proxy never starts). You can confirm it's active in the logs (🛡️ Sandbox egress proxy: starting…).

What these levers do:

userAccessControl.allowedUsers. Only you can delegate issues, so nobody else in the workspace can spend your credit. (blockBehavior accepts "silent" or "comment".)
labelPrompts. Routes issues to a prompt mode (scoper/debugger/builder) by Linear label and scopes tools per mode. scoper is read-only, ideal for cheap triage.
allowedTools. Restricts what Claude can run. Narrower = less wandering, less cost. (Cyrus auto-adds Skill.)
sandbox / networkPolicy.preset: "trusted". Routes all Bash subprocess traffic (git, gh, npm, curl) through the local egress proxy with a ~200-domain allowlist (package registries, version control), denying everything else. Add your own internal domains under networkPolicy.allow.


Step 8: Model selection (default + per-ticket)

Cyrus does support per-ticket model selection. The upstream config reference doesn't document it, but it's in the code. Resolution order (highest first):

Issue label opus or sonnet → sets the model for that ticket.
[model=<name>] tag anywhere in the issue description → same effect.
repositories[].model in config.json → per-repo default.
CYRUS_CLAUDE_DEFAULT_MODEL (or CYRUS_DEFAULT_MODEL) env var → global default.
Built-in fallback: claude-opus-4-6 (Opus), which is why an unconfigured agent runs Opus. This is Cyrus's pinned default at this version; current model names shift, so check what your Cyrus and Claude Code version actually resolves to.

So:

Global default → Sonnet: CYRUS_CLAUDE_DEFAULT_MODEL=sonnet in cyrus.env (already in Step 4; requires a docker compose up -d to load). This is the biggest cost lever.
Run one ticket on Opus: add an opus label, or put [model=opus] in the description. The opus/sonnet model label is independent of routing. The issue still needs its routing label (or assignment) to reach the repo.


⚠️ ANTHROPIC_MODEL and Claude Code's settings.json model are both no-ops here. Cyrus resolves the model itself and passes it explicitly to the Agent SDK, overriding both. Use CYRUS_CLAUDE_DEFAULT_MODEL and the per-ticket label/tag. You can confirm the resolved model in the logs: "cqo.model":"sonnet", and Cyrus posts a "Using model: …" thought on the Linear issue.

(CYRUS_CLAUDE_DEFAULT_FALLBACK_MODEL also exists if you want to control the retry-fallback model.)

Step 9: Wire up the Linear trigger

Cyrus activates when an issue is delegated/assigned to the Cyrus agent (that's what the Agent session events deliver). Two ways to feed it:

Manual: assign an issue to the Cyrus agent like you'd assign a teammate.
Automatic from a queue: rather than firing on everything in Todo (which drains credit fast), create an agent label (matching routingLabels), and if your Linear plan supports workflow automations, add a rule that assigns issues to Cyrus when that label is added or when they enter a dedicated "Agent Queue" status. An explicit on-ramp you control beats auto-grabbing the backlog.

Start with manual assignment on a single throwaway issue to confirm the loop end to end (issue → worktree → session → PR), then add the automation. In the logs you'll see webhook_received … AgentSessionEvent → RepositoryRouter → Creating git worktree … → session_started → the PR marker.

Step 10: Routing issues across multiple repos

One Cyrus instance can serve many repos in the same Linear workspace. Add each with self-add-repo (Step 5d), repeat once per repo:
docker compose run --rm cyrus self-add-repo https://github.com/yourorg/another-repo.git "Your Workspace Name"
self-add-repo runs non-interactively, clones into the volume, and creates a bare repo entry: id, name, repositoryPath, baseBranch, linearWorkspaceId, and routingLabels: ["<repo-name>"]. It does not copy the allowedTools / labelPrompts hardening from Step 7. Those are per-repo, so after a bulk add, backfill them onto every entry (the top-level sandbox, userAccessControl, and promptDefaults blocks are global and already apply to all repos). A quick jq backfill, run from inside the container, copies the fields from an already-hardened entry onto any that lack them:
docker compose exec -u cyrus cyrus sh -c '
cd ~/.cyrus && cp config.json config.json.bak
TOOLS=$(jq -c ".repositories[]|select(.name==\"TEMPLATE_REPO\").allowedTools" config.json)
LP=$(jq -c ".repositories[]|select(.name==\"TEMPLATE_REPO\").labelPrompts" config.json)
jq --argjson tools "$TOOLS" --argjson lp "$LP" '\''
  .repositories |= map(
    (if .allowedTools==null then .allowedTools=$tools else . end)
    | (if .labelPrompts==null then .labelPrompts=$lp else . end))'\'' config.json > config.json.new
jq empty config.json.new && mv config.json.new config.json'
Config hot-reloads (🔄 Config file changed, reloading...); confirm with docker compose logs cyrus | grep "Managing" → 📦 Managing N repositories.
How Cyrus picks the repo

When an issue fires, RepositoryRouter selects the target repo by the first rule that matches (higher wins):

Existing active session for that issue.
[repo=<name>] tag in the issue description. Explicit and needs no Linear setup. Supports multiple repos and an optional per-repo branch: [repo=api] [repo=web#feature-x] dispatches to both, with web based off feature-x.
Routing labels. A Linear label whose name matches the repo's routingLabels. self-add-repo sets these to the repo name, so applying the Linear label api routes the issue to the api repo.
Project-based. Set projectKeys on a repo entry to bind a Linear project to it.
Team-based. Set teamKeys, or rely on the issue identifier prefix (API-123 → team API). Best when each repo maps to its own Linear team.
Catch-all. A repo with no routingLabels/teamKeys/projectKeys becomes the default. This only works if exactly one repo has no routing config; with several unconfigured repos it's ambiguous and the first one wins, so don't rely on it once you're multi-repo.
No match → Cyrus asks. It posts a repository picker on the issue rather than guessing. Safe (no misroute), but it means an untagged issue stalls until you choose.

Practical guidance: the two reliable, low-setup ways to target a repo are the [repo=<name>] description tag (nothing to configure) or a Linear label matching the repo name (already wired by self-add-repo). For a workspace where each repo has its own Linear team, set teamKeys per repo and routing becomes automatic from the issue prefix. Edit any of these fields in config.json; they hot-reload.

Security checklist (before pointing it at anything real)


 CLAUDE_CODE_OAUTH_TOKEN is set and ANTHROPIC_API_KEY is absent everywhere (env file, host shell, image).
 Token refresh is calendared. CLAUDE_CODE_OAUTH_TOKEN from claude setup-token is a ~12-month token; when it expires the agent silently stops authenticating. Re-mint (Step 1) and update cyrus.env before then.
 GitHub token is a fine-grained PAT limited to the target repos only.
 No production credentials, SSH keys, or cloud profiles live on this box or in the mounted volumes.
 config.json has top-level sandbox.enabled: true with the trusted preset; the egress proxy shows as started in the logs.
 The ~/.claude/settings.json allowRead exposes only the public cyrus-egress-ca.pem, never the -key.pem.
 userAccessControl.allowedUsers restricts delegation to you.
 Container runs as non-root with memory and pid limits. seccomp/systempaths are relaxed only because the egress sandbox needs bubblewrap. The container boundary, non-root user, and egress allowlist still apply.
 Port 3456 is published only on 127.0.0.1, never 0.0.0.0 on the host; all real ingress goes through the tunnel, and the only public path that matters (/linear-webhook) is signature-verified.
 If you use Cloudflare Access on the domain, the cyrus.yourdomain.com bypass (or /linear-webhook bypass) is in place.


Cost controls recap


Global default model = Sonnet (CYRUS_CLAUDE_DEFAULT_MODEL=sonnet). Biggest single lever. Reserve Opus for hard tickets via an opus label.
Tight, well-scoped Linear issues with file references cost far less than vague ones; the agent skips most exploration.
allowedTools scoping and a readOnly scoper mode keep cheap triage cheap.
Keep each repo's CLAUDE.md lean; it's paid as input on every run before caching kicks in.
Watch your usage at claude.ai/settings/usage. On subscription auth you draw from your plan's limits rather than a metered API bill, so there are no surprise charges as long as no ANTHROPIC_API_KEY is present.


Troubleshooting

Roughly in the order you'll hit them on a fresh build:

EACCES: permission denied, mkdir '/home/cyrus/.cyrus/repos'. The named volume is root-owned. The provided Dockerfile fixes this by mkdir+chown-ing .cyrus and .claude before VOLUME. If you hit it on an existing volume, remove the empty volume (docker volume rm cyrus-stack_cyrus-data) and recreate from the fixed image.
self-auth-linear: "Config file not found … Run 'cyrus' first". Seed config.json first (Step 5b).
Tunnel returns 502 / "connection reset by peer" / "connection refused". Almost always missing CYRUS_HOST_EXTERNAL=true (Cyrus bound container-localhost). Confirm the startup log says listening on http://0.0.0.0:3456. Secondary cause: localhost resolving to IPv6 on the host. Set the tunnel Service to http://127.0.0.1:3456.
Browser hits a Cloudflare Access login page at cyrus.yourdomain.com. A wildcard Access policy is intercepting it; add the Bypass (Step 3).
git clone: "could not read Username for 'https://github.com'". The gh auth git-credential helper isn't configured. The provided Dockerfile sets it system-wide; confirm GH_TOKEN is in cyrus.env.
bwrap: No permissions to create new namespace. Add seccomp=unconfined to security_opt.
bwrap: Can't mount proc on /newroot/proc: Operation not permitted. Add systempaths=unconfined to security_opt.
git: "Read-only file system" on …/.git/worktrees/<ISSUE>/index.lock. The sandbox isn't granting write to the shared worktree .git. Ensure ~/.claude/settings.json has sandbox.filesystem.allowWrite for /home/cyrus/.cyrus/repos and /home/cyrus/.cyrus/worktrees.
git push fails TLS / agent says the egress CA isn't readable. Add the public CA to sandbox.filesystem.allowRead (/home/cyrus/.cyrus/certs/cyrus-egress-ca.pem), as in the provided claude-settings.json. Never expose the -key.pem.
No conversation found with session ID … after a restart. ~/.claude wasn't persisted. Ensure the cyrus-claude volume is mounted (Step 4). Existing poisoned issues won't resume; trigger a new issue.
Agent keeps running Opus despite config. ANTHROPIC_MODEL/settings.json model are no-ops; set CYRUS_CLAUDE_DEFAULT_MODEL=sonnet and docker compose up -d. Verify "cqo.model":"sonnet" in the logs.
Webhooks not arriving. The URL must be CYRUS_BASE_URL/linear-webhook (the bare /webhook is deprecated). Check docker compose logs cyrus for webhook_received. A Rejected … unauthorized IP line is normal for stray probes.
Multi-repo: issue isn't picked up / Cyrus posts a "which repo?" picker. No routing rule matched (Step 10). Add a [repo=<name>] tag to the description or apply the Linear label matching the repo name. Wrong repo gets picked. Usually multiple repos left without routing config, so the catch-all is ambiguous; give each repo a distinct routingLabels/teamKeys. New repos added by self-add-repo lack allowedTools/labelPrompts until you backfill them (Step 10).
Billing went to the API account. An ANTHROPIC_API_KEY leaked into the environment. Remove it and restart.
Agent stopped firing after months of working, logs show an auth failure. The CLAUDE_CODE_OAUTH_TOKEN expired (these are ~1-year tokens). Re-run claude setup-token (Step 1), update cyrus.env, then docker compose up -d.
Port conflict during self-auth-linear. Don't run the one-off auth while the main cyrus service is up on 3456. Do the auth before docker compose up -d.


Reference


Cyrus self-hosting guide: https://github.com/cyrusagents/cyrus/blob/main/docs/SELF_HOSTING.md
Cyrus config reference: https://github.com/cyrusagents/cyrus/blob/main/docs/CONFIG_FILE.md
Cyrus Cloudflare Tunnel notes: https://github.com/cyrusagents/cyrus/blob/main/docs/CLOUDFLARE_TUNNEL.md
Cyrus Git & GitHub setup: https://github.com/cyrusagents/cyrus/blob/main/docs/GIT_GITHUB.md
Claude Code sandboxing: https://code.claude.com/docs/en/sandboxing
Claude Code headless docs: https://code.claude.com/docs/en/headless
Method	Env var	Where it bills
API key (the Cyrus README's default)	`ANTHROPIC_API_KEY`	Your API account, full pay-as-you-go rates, no credit offset
OAuth token (use this one)	`CLAUDE_CODE_OAUTH_TOKEN`	Your Max 20x subscription (normal usage limits)
No results found