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⚠️ Whyso 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 documentedCLAUDE_CODE_OAUTH_TOKEN
fromclaude 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 andclaude -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 atclaude.ai/settings/usage
. Whatever the model, the rule below holds: keepANTHROPIC_API_KEY
out of the environment so you stay on subscription auth and off metered API billing.
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.
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.
- 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).
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.
- 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 notificationsand Permission changes**.
- Save, then copy these three values (the secret may only be shown once): Client IDClient SecretWebhook 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
appitself. If you revoke the authorization to retry the flow, the OAuth app and its Client ID/Secret stay valid. You just need to re-runself-auth-linear
to mint a fresh token. You donotneed to recreate the app.
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
- 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 interceptcyrus.yourdomain.com
and redirect Linear's webhook POSTs to a login page. The agent then never fires. Add an Access application forcyrus.yourdomain.com
with aBypasspolicy (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.⚠️
Ifand you see intermittent 502s, set the tunnel Service tolocalhost
resolves to IPv6 (::1
) on your hosthttp://127.0.0.1:3456
instead oflocalhost:3456
to force IPv4 (Docker publishes the port on IPv4 only). Most hosts are fine withlocalhost
; this is a fallback.
Create a working directory, e.g. ~/cyrus-stack/
, with the four files below.
CLAUDE_CODE_OAUTH_TOKEN=paste-token-from-step-1
LINEAR_DIRECT_WEBHOOKS=true
CYRUS_BASE_URL=https://cyrus.yourdomain.com
CYRUS_SERVER_PORT=3456
CYRUS_HOST_EXTERNAL=true
CYRUS_CLAUDE_DEFAULT_MODEL=sonnet
LINEAR_CLIENT_ID=your_client_id
LINEAR_CLIENT_SECRET=your_client_secret
LINEAR_WEBHOOK_SECRET=your_webhook_signing_secret
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
.
⚠️
The Cyrus server bindsCYRUS_HOST_EXTERNAL=true
is the single most important addition.localhost
inside the containerby 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 bind0.0.0.0
inside the container while the host still publishes loopback-only.
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"
]
}
}
}
FROM node:20-bookworm-slim
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/*
RUN npm install -g @anthropic-ai/claude-code cyrus-ai
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"
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
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"]
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 hasno 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). Somem_limit
/pids_limit
areyour 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 at4g
/512
(a few at a time), while a large box can go much higher, e.g.on a 128 GB host for many concurrent sessions, leaving the rest of the host untouched. Edit the two lines and32g
/8192
docker compose up -d
to apply (a ~5 s recreate; the volumes persist, so no data loss). Verify withdocker 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. Twosecurity_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
undersandbox
inconfig.json
(Step 7) and drop the twosecurity_opt
lines. The agent runs with no extra setup but hasunfiltered network egressduring Bash steps. Fine for throwaway repos, weaker for real ones. (You can't keep egress filtering without bubblewrap; the two are coupled.)
cd ~/cyrus-stack
docker compose build
⚠️
self-auth-linear
refuses to run without an existingconfig.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'
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).
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).
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.
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.
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.
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"] }
}
}
]
}
⚠️
Cyrus readssandbox
goes TOP-LEVEL, not insiderepositories[]
.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:
. Only you can delegate issues, so nobody else in the workspace can spend your credit. (userAccessControl.allowedUsers
blockBehavior
accepts"silent"
or"comment"
.). Routes issues to a prompt mode (scoper/debugger/builder) by Linear label and scopes tools per mode.labelPrompts
scoper
is read-only, ideal for cheap triage.. Restricts what Claude can run. Narrower = less wandering, less cost. (Cyrus auto-addsallowedTools
Skill
.). 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 undersandbox
/networkPolicy.preset: "trusted"
networkPolicy.allow
.
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→ sets the model for that ticket.opus
orsonnet
→ same effect.[model=<name>]
tag anywhere in the issue descriptioninrepositories[].model
config.json
→ per-repo default.(orCYRUS_CLAUDE_DEFAULT_MODEL
CYRUS_DEFAULT_MODEL
) env var → global default.- Built-in fallback:
(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.claude-opus-4-6
So:
Global default → Sonnet:CYRUS_CLAUDE_DEFAULT_MODEL=sonnet
incyrus.env
(already in Step 4; requires adocker compose up -d
to load). This is the biggest cost lever.Run one ticket on Opus: add anlabel, or putopus
in the description. The[model=opus]
opus
/sonnet
model label is independent of routing. The issue still needs its routing label (or assignment) to reach the repo.
⚠️
Cyrus resolves the model itself and passes it explicitly to the Agent SDK, overriding both. UseANTHROPIC_MODEL
and Claude Code'ssettings.json
model
are both no-ops here.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.)
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 anagent
label (matchingroutingLabels
), 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.
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, re...
); confirm with docker compose logs cyrus | grep "Managing"
→ 📦 Managing N repositories
.
When an issue fires, RepositoryRouter
selects the target repo by the first rule that matches (higher wins):
Existing active session for that issue.. Explicit and needs no Linear setup. Supports[repo=<name>]
tag in the issue descriptionmultiple repos and an optional per-repo branch:[repo=api] [repo=web#feature-x]
dispatches to both, withweb
based offfeature-x
.Routing labels. A Linear label whose name matches the repo'sroutingLabels
.self-add-repo
sets these to the repo name, so applying the Linear labelapi
routes the issue to theapi
repo.Project-based. SetprojectKeys
on a repo entry to bind a Linear project to it.Team-based. SetteamKeys
, or rely on the issue identifier prefix (API-123
→ teamAPI
). 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 ifexactly 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.-
CLAUDE_CODE_OAUTH_TOKEN
is set andANTHROPIC_API_KEY
is absent everywhere (env file, host shell, image). - Token refresh is calendared.
CLAUDE_CODE_OAUTH_TOKEN
fromclaude setup-token
is a ~12-month token; when it expires the agent silently stops authenticating. Re-mint (Step 1) and updatecyrus.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-levelsandbox.enabled: true
with thetrusted
preset; the egress proxy shows as started in the logs. - The
~/.claude/settings.json
allowRead
exposes only thepubliccyrus-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
, never0.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.
- Global default model =
Sonnet(
CYRUS_CLAUDE_DEFAULT_MODEL=sonnet
). Biggest single lever. Reserve Opus for hard tickets via anopus
label. - Tight, well-scoped Linear issues with file references cost far less than vague ones; the agent skips most exploration.
allowedTools
scoping and areadOnly
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 noANTHROPIC_API_KEY
is present.
Roughly in the order you'll hit them on a fresh build:
. The named volume is root-owned. The provided Dockerfile fixes this byEACCES: permission denied, mkdir '/home/cyrus/.cyrus/repos'
mkdir
+chown
-ing.cyrus
and.claude
beforeVOLUME
. 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.. Seedself-auth-linear
: "Config file not found … Run 'cyrus' first"config.json
first (Step 5b).Tunnel returns 502 / "connection reset by peer" / "connection refused". Almost always missingCYRUS_HOST_EXTERNAL=true
(Cyrus bound container-localhost). Confirm the startup log sayslistening on http://0.0.0.0:3456
. Secondary cause:localhost
resolving to IPv6 on the host. Set the tunnel Service tohttp://127.0.0.1:3456
.Browser hits a Cloudflare Access login page atcyrus.yourdomain.com
. A wildcard Access policy is intercepting it; add the Bypass (Step 3).. Thegit clone
: "could not read Username for 'https://github.com'"gh auth git-credential
helper isn't configured. The provided Dockerfile sets it system-wide; confirmGH_TOKEN
is incyrus.env
.. Addbwrap: No permissions to create new namespace
seccomp=unconfined
tosecurity_opt
.. Addbwrap: Can't mount proc on /newroot/proc: Operation not permitted
systempaths=unconfined
tosecurity_opt
.. The sandbox isn't granting write to the shared worktreegit
: "Read-only file system" on…/.git/worktrees/<ISSUE>/index.lock
.git
. Ensure~/.claude/settings.json
hassandbox.filesystem.allowWrite
for/home/cyrus/.cyrus/repos
and/home/cyrus/.cyrus/worktrees
.. Add the public CA togit push
fails TLS / agent says the egress CA isn't readablesandbox.filesystem.allowRead
(/home/cyrus/.cyrus/certs/cyrus-egress-ca.pem
), as in the providedclaude-settings.json
. Never expose the-key.pem
..No conversation found with session ID …
after a restart~/.claude
wasn't persisted. Ensure thecyrus-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; setCYRUS_CLAUDE_DEFAULT_MODEL=sonnet
anddocker compose up -d
. Verify"cqo.model":"sonnet"
in the logs.Webhooks not arriving. The URL must beCYRUS_BASE_URL/linear-webhook
(the bare/webhook
is deprecated). Checkdocker compose logs cyrus
forwebhook_received
. ARejected … 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 distinctroutingLabels
/teamKeys
. New repos added byself-add-repo
lackallowedTools
/labelPrompts
until you backfill them (Step 10).Billing went to the API account. AnANTHROPIC_API_KEY
leaked into the environment. Remove it and restart.Agent stopped firing after months of working, logs show an auth failure. TheCLAUDE_CODE_OAUTH_TOKEN
expired (these are ~1-year tokens). Re-runclaude setup-token
(Step 1), updatecyrus.env
, thendocker compose up -d
.Port conflict during. Don't run the one-off auth while the mainself-auth-linear
cyrus
service is up on 3456. Do the auth beforedocker compose up -d
.
- 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