Self-hosted device isolation
What each isolation level isolates, how to narrow an unisolated host, and what workspaces on one device share.
An agent runs on a device you own. The isolation level of the device decides what the agent can reach. This page states the boundary of each level. It also states what workspaces on one device share.
Defaults and your choice
An unisolated host is the default. CH_REQUIRE_ISOLATED_EXECUTION and CH_TRUSTED_EXECUTION are both off by default. CodeHerder ships no deployment value for them. You choose the isolation level and the strict setting. An upgrade does not change them.
Pick an isolation level
A device has one of two isolation levels. A level has one or more backends. The backend names the mechanism. The device reports its level and backend. Check which levels your organization runs.
| Level | Backend | How to start it | What it protects | When to use it |
|---|---|---|---|---|
isolated |
container |
ch device-server --isolation isolated |
Each stage runs in its own container. Egress is filtered. Credentials are scoped. The host stays out of reach of a hostile agent. | Shared devices, cloud hosts, and any device that holds credentials for more than one person. |
isolated |
microvm |
A microVM runner that runs the same container executor inside the VM | The same checks as container, plus a VM boundary for each runner. |
A Lambda MicroVM pool launches these runners. A runner reports isolated/microvm when every check passes. See MicroVM runners. |
unisolated |
host |
ch device-server (the default), with or without CH_AGENT_USER |
Nothing contains a hostile agent. An agent user hides the operator’s home directory and the credential pools. | A laptop that you trust the agent on. Your organization must accept the risk in writing. |
unisolated |
container or microvm |
--isolation isolated with a weakening setting, or a missing check |
The device names each unmet check. | Fix the unmet checks, or accept the risk with CH_TRUSTED_EXECUTION=1. |
A device claims isolated only when it meets every check in the posture contract. When it misses one, it reports unisolated and lists the unmet checks. Only isolated is a hostile-agent boundary.
On a cloud VM, set IMDSv2 hop limit 1 and drop metadata traffic from container networks yourself. A deployment may set CH_REQUIRE_ISOLATED_EXECUTION=1. That setting refuses every task stage on an unisolated device unless CH_TRUSTED_EXECUTION is set.
See Isolating agent runs on a device for the isolated setup.
What each choice satisfies
The first column is the repository credential gate. The second column is the strict setting CH_REQUIRE_ISOLATED_EXECUTION=1, for a spawn with harness approvals bypassed.
| Choice | Repository credentials | Unattended spawns under the strict setting |
|---|---|---|
unisolated/host |
Refused | Refused, unless CH_TRUSTED_EXECUTION=1 |
unisolated/host with CH_AGENT_USER |
Allowed | Refused, unless CH_TRUSTED_EXECUTION=1. All sessions share one agent user. |
isolated/container, egress on, non-root image |
Allowed | Allowed |
unisolated/container: --stage-egress=false or CH_STAGE_ALLOW_ROOT_IMAGE=1 |
Refused | Refused, unless CH_TRUSTED_EXECUTION=1 |
unisolated/microvm |
Allowed | Refused, unless CH_TRUSTED_EXECUTION=1. The runner does not meet every check yet. |
CH_ALLOW_UNISOLATED_GIT_CREDENTIALS=1 waives the repository gate. CH_TRUSTED_EXECUTION=1 never serves git credentials.
The engineering table, with code citations, is in docs/security.md under “Isolation backends”.
See each device’s level
Each device reports an Execution mode check. The check key stays execution_mode. Run ch device show <device> or open the Health snapshot of the device. The summary starts with the isolation level and the backend, for example unisolated (host), isolated (container) or unisolated (microvm). Only isolated is a hostile-agent boundary. When a requirement is not met, the detail lists it after unmet:. The check never blocks work. It warns in two cases. Both apply only when the device sets CH_REQUIRE_ISOLATED_EXECUTION:
- The level is
unisolatedand the device does not setCH_TRUSTED_EXECUTION. The device refuses every stage that bypasses harness approvals. This covers ahostdevice and an agent user alone. - Only
CH_TRUSTED_EXECUTIONadmits the spawns. The device runs the stages, but no boundary separates the agents.
Repository work needs agent isolation
An unisolated host device warns on its Agent isolation check. It refuses a spawn for a sandbox with listed repos (agent_isolation_required). To fix this, use one of these:
- Run
ch device setup-agent-user | sudo sh, setCH_AGENT_USER, and restart the device server. - Start the device server with
--isolation isolated.
The gate covers only a sandbox with listed repos. Repo-less work runs on an unisolated device, and the helper serves it no git credential.
An agent user satisfies this gate. It is not hostile-agent confinement. All sessions share one agent user and the ch-agents group.
You can accept the risk with CH_ALLOW_UNISOLATED_GIT_CREDENTIALS=1. The agent then reads the git-token pool. The check stays at warn.
Narrow an unisolated host with an agent user
Set CH_AGENT_USER to run each agent as a separate OS user. The steps:
- Run
ch device setup-agent-user | sudo sh. - Set
CH_AGENT_USERto the new user. - Restart the device server.
The setting closes the operator’s home directory, the credential pools, and the credential commands on the device-local socket. It leaves two things open. All worktrees share one ch-agents group. The agent keeps the bearer of its own session. See Isolating agent runs on a device for the full steps.
Docker inside a stage (testcontainers)
An --isolation isolated device lets a stage run Docker. Tools such as testcontainers, the docker CLI and the Docker Go SDK work with no setup in the repo. This is on by default.
Each stage gets its own Docker endpoint. The stage never sees the Docker socket. It sees and changes only the containers, networks and volumes that it made in that run. CodeHerder removes them when the stage ends, or after a crash or restart.
A stage cannot start a privileged container, mount a host path, use host namespaces, or publish a host port. Each container joins the stage’s own internal network. A limit applies to each stage:
CH_STAGE_DOCKER_MAX_CONTAINERS: containers at one time (default 8).CH_STAGE_DOCKER_MEMORY: total memory (default4g).CH_STAGE_DOCKER_CPUS: total CPU (default2).
Know these risks before you leave it on:
- A container in a stage may run as root. A kernel flaw could let it reach the host. Run the Docker daemon with
userns-remapto reduce this. - The Docker daemon pulls images, not the stage. The stage egress filter does not apply to a pull. Pulled images use host disk.
- The limits cap memory, CPU and container count. They do not cap disk.
- The limits apply to each stage. A device that runs many stages at once can use more in total.
To turn it off, set CH_STAGE_DOCKER=false on the device and restart the device server. The device needs stage egress on, a local Docker socket (or CH_STAGE_DOCKER_RUN_SOCKET behind a socket proxy) and a current stage image.
Run ch device show <device>. A ready device lists stage-docker in its capabilities and shows a Stage Docker check. To send a task only to such devices, run ch task edit <task-id> --device-cap stage-docker, or pass --device-cap stage-docker when you create it. On a device without it, a Docker call in a stage fails with a message that names the capability.
Read-only stages on a laptop
CH_ALLOW_UNISOLATED_PLANNING stays on. A read-only stage on a laptop with no agent user can push with the developer’s own key. The stage removes only its environment. It does not hide ~/.ssh. This risk needs your organization’s written acceptance.
To refuse these stages instead, set CH_ALLOW_UNISOLATED_PLANNING=0 or set CH_AGENT_USER. A workspace admin can change CH_ALLOW_UNISOLATED_PLANNING in the device’s Settings section. See Changing a device’s settings.
The AI bearer
Every agent holds the bearer of its own session. This is needed to work.
On a host device with no agent user, an agent can also read every pooled AI credential on the device. That includes the subscription bearer, and credentials the owner added for another workspace. With CH_AGENT_USER or --isolation isolated, the agent cannot read the pool. The tests TestAgentUser_CannotReadPooledCredentials and TestAgentUser_RefusedByCredentialVerbs pin this for the agent user.
One device, several workspaces
The device owner decides whether a device serves more than one workspace. CodeHerder does not decide it. To keep workspaces apart, run one device for each workspace. Or use CH_AGENT_USER and link a single workspace.
What a shared device shares
A device with several workspaces shares these components:
| Component | Shared between workspaces? | What another workspace’s session can reach |
|---|---|---|
OS user and home directory (~/.claude, ~/.ssh) |
Yes | On host, a session reads everything the device user reads. That includes other workspaces’ sandboxes. By default, the AWS, Docker, kube, gh and glab config variables point at empty session paths (internal/agentpty/isolated_config_env.go#isolatedConfigEnv). An agent can still read the files by absolute path. |
| Sandboxes and worktrees | One session root for all (--session-root) |
With CH_AGENT_USER, every worktree gets the one ch-agents group, so an agent can still reach another workspace’s worktree. Only --isolation isolated mounts just the task’s own worktree. |
| Git mirrors | No | Each workspace and repository URL has its own mirror. On a host device, the device user can still read them on disk. |
| Credential pools | Yes | One pool for each harness on the device. See the list below. |
Device token and CH_SECRET_* values |
One token for each device | The session environment never carries the device token. The device-server moves its own token and CH_SECRET_* values out of its environment block at start (internal/envseal/envseal_unix.go#SealSelf), so an agent cannot read them from /proc/<pid>/environ. |
| Device-local socket | Yes | CH_AGENT_USER refuses the agent on credential commands. |
| Cost and usage collectors | Yes | One sweeper for each device scans the device’s session logs. It attributes each session by its marker file (workspace, task, agent). A session with no marker counts as a human session. |
| Docker socket proxy | Yes | One proxy for each launch, with one per-launch token and one owner. It does not split by workspace. Stage containers cannot reach it. A stage with stage Docker reaches only its own run-scoped endpoint. See Protect the Docker socket proxy. |
Tool cache (/opt/ch-tools) |
No | Used by --isolation isolated only. Each task worktree has its own volume. |
| Docker daemon and images | Yes | The whole device. Stage Docker scopes containers, networks and volumes to each run, but images are shared. |
The credential pool works like this:
- A session in workspace B can use a credential that the device owner added for workspace A. Its spend lands in workspace B.
- The server keeps no list of which credentials exist on which device.
Related guides
Last updated