CodeHerderSearch⌘KRequest access →

Isolating agent runs on a device

What an agent running on your device can reach, and the shipped ways to tighten it.

Every task gets its own sandbox — an isolated git worktree and branch, so parallel tasks never collide with each other (see Core concepts). That isolates tasks from each other. It says nothing about what an agent can reach on the device itself — your home directory, SSH keys, other checkouts on the same machine. This page covers that boundary: what’s exposed by default, and the two ways to shrink it. Each way maps to an isolation level and backend: unisolated/host (Option 1 narrows it) and isolated/container (Option 2).

The default posture

Unless you set up one of the options below, an agent stage runs on an unisolated/host device, as a plain host process — the same OS user that started ch device-server — with its sandbox’s worktree as its working directory. It can read and write anything that user can: your home directory, credentials, other repositories checked out on the same box, all of it. Nothing about the sandbox model restricts this; the worktree isolates tasks from each other, not the agent from the device.

What an agent can reach on the device

This section lists what an agent can reach at each level and backend. Pooled AI credentials are the sensitive part.

Every level: the agent holds its own session’s Claude credential in its environment. It needs that credential to call Claude.

No agent user and no per-stage container. The agent runs as the same user as ch device-server. It can read every pooled AI credential and the default Claude token under ~/.codeherder/credentials. It can also call ch device credential ..., ch device claude-token set and ch device git-token ... through the device-local socket. Those calls add, disable and remove credentials.

CH_AGENT_USER (Option 1). The agent cannot read those files, even when it shares the ch-agents group. The credential directories are mode 0700 and the files are 0600. The device-local socket also refuses the agent: it accepts only the device server’s own user.

--isolation isolated (Option 2). The stage container mounts only the files that the stage needs. The credential pool and the device-local socket are outside the container. The mounts are:

  • The task’s worktree, read-write, at /workspace.
  • The workspace git mirror (the git common directory), read-write. It is shared with every sibling sandbox of the same workspace and repository. The mirror’s config and hooks mount read-only.
  • The harness transcript directory for the session, read-write. The device reads the transcript from it.
  • The session’s own bearer and a few read-only helper files, such as the toolchain layers, harness settings and the trust file.

The container omits the other workspaces’ mirrors, the other sandboxes’ worktrees and the operator’s home directory. The mirror and the transcript mounts are the two writable paths outside the worktree. A hostile stage can change the shared mirror of its own workspace.

One credential pool serves every workspace on a device. See What a shared device shares.

A device with no isolation also refuses a session whose sandbox lists repositories. A CH_AGENT_USER agent user, --isolation isolated or a microVM image satisfies the gate. See Repository work needs agent isolation and Git credentials on a device.

What you get with no setup: push isolation on non-writable stages

One protection applies out of the box, on every device, at every isolation level: the push credential leaves the stage’s environment. It does not hide the token pool or the gh/glab login files. Without a dedicated agent user, a stage can still read those. A stage whose Writable switch is off — typically planning and review stages — has the push credential stripped from its own environment: it can commit locally, but the stage process itself isn’t handed a way to push to your shared remote. Writable stages, the ones that actually ship code, get the credential. See Per-stage settings under Customising workflows for where that switch lives — the shared library stage for a composed workflow, the type’s own schema for a hand-written one — and what it otherwise controls.

Know the default here, because it’s the permissive one: if a device has no dedicated agent user configured (Option 1 below) and a push credential is still readable by whichever account runs the stage, a non-writable stage runs anyway — with the credential stripped from its own environment, but without refusing to start. To make this fail closed instead — refuse to run a non-writable stage at all while a push credential is reachable and no dedicated agent user is configured — set CH_ALLOW_UNISOLATED_PLANNING=0 in the device server’s environment, or in the device’s Settings section (see Changing a device’s settings). It accepts the same values as other CodeHerder boolean settings: 1/true/yes/on and 0/false/no/off.

Option 1: a dedicated agent OS user

The lightest way to separate agents from your own account. Run:

ch device setup-agent-user | sudo sh

setup-agent-user only prints a shell script — it never runs anything itself; piping it to sudo sh is what applies it. It supports Linux and macOS (any other OS refuses with an unsupported-OS error).

Flags:

  • --user <name> — the agent account to create (default ch-agent).
  • --group <name> — a shared group used to grant the setup (default ch-agents).
  • --ch-path <path> — path to the ch binary the sudoers rule may run (defaults to the one you’re currently running).

The generated script creates a low-privilege, no-login system user and the shared group, adds your own account to that group, and installs a passwordless sudo rule that lets the device server start agent processes as that user — nothing broader.

Finish the setup (the script prints these same steps when you run it):

  1. Log out and back in — or restart ch device-server — so your new group membership takes effect.
  2. Set CH_AGENT_USER=ch-agent (or whatever you passed to --user) in the device server’s environment. If you also passed a non-default --group, set CH_AGENT_GROUP to match.
  3. Restart ch device-server.

Once configured, every agent stage runs as that dedicated user instead of your own account — it cannot read your home directory, your SSH keys, or anything else scoped to you. See Running the device server as a service for where to add an environment variable under systemd or launchd.

This option satisfies the repository credential gate. Every session shares the one agent user, so it is not a boundary between sessions. CH_REQUIRE_ISOLATED_EXECUTION refuses it.

Option 2: a fresh container per stage

ch device-server --isolation isolated

Environment equivalent: CH_ISOLATION=isolated. The default is unisolated: a device runs stages as host processes unless you opt in. The two level names are isolated and unisolated. A bad value stops the device server at start.

The container backend requires Docker installed and running on the device; the stage image is fetched automatically using the device’s own CodeHerder credential, so there’s nothing to build or configure yourself.

With this on, every stage runs in its own container, created fresh and destroyed the moment the stage ends. Only the task’s sandbox — its worktree and the git data it needs — is mounted in; your home directory, SSH keys, and the rest of the machine are not reachable from inside.

Hardening applied to every stage’s container:

  • Runs as a non-root user.
  • Every extra Linux capability is dropped, and privilege escalation is disabled (no-new-privileges).
  • CPU (2 cores) and process count (512) capped by default; memory is uncapped by default (the container may use the whole host) — set CH_STAGE_MEMORY (e.g. 12g) to cap it, or CH_STAGE_CPUS to change the CPU cap.
  • The container’s own filesystem is writable — that’s separate from the Writable switch above, which governs whether the stage can push, not what it can write to disk.

Outbound network is filtered on by default. Each stage gets its own proxy on its own internal Docker network. A writable stage runs in strict mode by default: the proxy allows only a list of hosts on approved ports (443 and 80). The list covers the GitHub and GitLab hosts, Anthropic, npm and Node, the Go module proxy, PyPI, crates.io, Packagist and your CodeHerder server. Set EGRESS_WRITABLE_MODE to change this. A read-only stage keeps EGRESS_MODE, which is open by default: the public internet is reachable over HTTP and HTTPS. In both modes, requests to private network ranges, loopback and link-local addresses, and cloud-metadata endpoints are refused, which is what stops a stage reaching your internal network. Package and browser downloads in these stages go through a device cache; see Package and browser downloads in container stages. A blocked destination can become a request that a person approves; see Network access approvals. --stage-egress=false turns the filtering off entirely, including those refusals — the stage container isn’t placed on the internal network at all, so private ranges, loopback, and cloud metadata are reachable again. There is no environment-variable equivalent for this flag. Without filtering, the stage container is not a boundary against a hostile agent, so the device server refuses to start with --stage-egress=false unless you also set CH_TRUSTED_EXECUTION=1. The same consent is required for CH_STAGE_ALLOW_ROOT_IMAGE=1, which lets a stage run as root.

Once enabled, the device’s Health snapshot grows a Docker ready check that confirms Docker is reachable and the stage image is available — it blocks new work on that device if it fails. See Device health and readiness checks in Managing your devices. Live terminals and dropping into a running session work the same way in this mode — see Following a live agent session.

A stage doesn’t have to run the device’s default image, either — see Running a stage in your own container image for naming your own image per stage. That page’s setup script (environment.before_stage) isn’t specific to this option. It runs by default under --isolation isolated. In direct mode (the device server runs on the machine with no container), the device refuses it unless the operator sets CH_HOST_BEFORE_SCRIPT. See Running a stage in your own container image for detail.

Searching issues from a stage

A stage can search GitHub issues, but only over repos on its repo list. List the repos in the query. For example: gh search issues --repo o/a --repo o/b --label code-herder. Each repo: must be on the list. The relay refuses --owner, org: and user: with a 403. It also refuses a query with no repo:. GitLab issue search is not relayed. Use glab issue list -l code-herder inside the repo.

Known limits of the container option

Option 2 has a socket proxy. The proxy checks its caller and manages only its own containers. It refuses published ports and unsafe create fields, and it gates writable binds. It does not limit image registries or an empty container user. A stage cannot reach the proxy. This matters only if the device server itself is compromised.

This limit is accepted.

Choosing between the options

  • Nothing configured: you already have push isolation on non-writable stages (see above) — consider CH_ALLOW_UNISOLATED_PLANNING=0 if that’s your only protection and you want it to fail closed.
  • Want agents separated from your own account with the least setup: Option 1.
  • Want each stage to run in its own disposable environment: Option 2.

Option 1 addresses a different layer (which OS account an agent runs as) than Option 2 (containment via container).

Guardrail posture

A guardrail is only enforced when the agent cannot rewrite it. A container stage, or a dedicated agent user, gives the posture enforced. An unisolated host device with no agent user gives tamperable.

Last updated

Try it on one repository for two weeks.

File a task. An agent builds it. A person reads every request. You see the cost of each task.

Try "pricing", "connect a device", or "who reviews the code"

↑↓ move · ↵ open · esc close