# 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…

> Source: <https://gist.github.com/devondragon/28fcf0077ff6f225f347da8f28093977>
> Published: 2026-06-15 19:55:47+00:00

A step-by-step guide to running [Cyrus](https://github.com/cyrusagents/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 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.

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

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-run`self-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
  # ... 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 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 to`localhost`

resolves to IPv6 (`::1`

) on your host`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.

Create a working directory, e.g. `~/cyrus-stack/`

, with the four files below.

```
# --- 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`

.

⚠️

The Cyrus server binds`CYRUS_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 bind`0.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

# 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"]
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). So`mem_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 at`4g`

/`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 and`32g`

/`8192`

`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 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 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'
```

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

```
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 reads`sandbox`

goes TOP-LEVEL, not inside`repositories[]`

.`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-adds`allowedTools`

`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 under`sandbox`

/`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`

or`sonnet`

→ same effect.`[model=<name>]`

tag anywhere in the issue descriptionin`repositories[].model`

`config.json`

→ per-repo default.(or`CYRUS_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`

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 anlabel, or put`opus`

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. Use`ANTHROPIC_MODEL`

and Claude Code's`settings.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 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.

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`

.

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 description**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.-
`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.

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

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

. The named volume is root-owned. The provided Dockerfile fixes this by`EACCES: permission denied, mkdir '/home/cyrus/.cyrus/repos'`

`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.. Seed`self-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 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).. The`git clone`

: "could not read Username for '[https://github.com](https://github.com)'"`gh auth git-credential`

helper isn't configured. The provided Dockerfile sets it system-wide; confirm`GH_TOKEN`

is in`cyrus.env`

.. Add`bwrap: No permissions to create new namespace`

`seccomp=unconfined`

to`security_opt`

.. Add`bwrap: Can't mount proc on /newroot/proc: Operation not permitted`

`systempaths=unconfined`

to`security_opt`

.. The sandbox isn't granting write to the shared worktree`git`

: "Read-only file system" on`…/.git/worktrees/<ISSUE>/index.lock`

`.git`

. Ensure`~/.claude/settings.json`

has`sandbox.filesystem.allowWrite`

for`/home/cyrus/.cyrus/repos`

and`/home/cyrus/.cyrus/worktrees`

.. Add the public CA to`git push`

fails TLS / agent says the egress CA isn't readable`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**. Don't run the one-off auth while the main`self-auth-linear`

`cyrus`

service is up on 3456. Do the auth before`docker compose up -d`

.

- Cyrus self-hosting guide:
[https://github.com/cyrusagents/cyrus/blob/main/docs/SELF_HOSTING.md](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](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](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](https://github.com/cyrusagents/cyrus/blob/main/docs/GIT_GITHUB.md) - Claude Code sandboxing:
[https://code.claude.com/docs/en/sandboxing](https://code.claude.com/docs/en/sandboxing) - Claude Code headless docs:
[https://code.claude.com/docs/en/headless](https://code.claude.com/docs/en/headless)