Skip to content
CommandChain CommandChain CommandChain Docs

Proving containment with doctor

doctor answers one question: can this machine contain a coding agent?

The installer runs it before it will finish, and the runner runs the same check every time it starts. You can run it yourself at any time:

Terminal window
commandchain-runner doctor

Exit code 0 means agents on this machine run inside a boundary that was observed to work, seconds ago. Exit code 1 means they will not run here.

What it proves, and what it refuses to accept as proof

Section titled “What it proves, and what it refuses to accept as proof”

doctor will not report success from a kernel version, a feature list, or the presence of a helper program. Those are inputs to a boundary, not a boundary. It does two things instead:

  1. Probe. It builds a real policy, starts a real child process through it, and requires the operating system to deny that child a read the policy never granted, while allowing one it did. A helper that has been replaced with a do-nothing program cannot pass, because the check reads a file it should not be able to read rather than trusting an exit code.
  2. Launch. It then prepares an attempt boundary and runs one harmless process through the same launcher a coding agent goes through. This catches a policy that validates but cannot actually start a process on this machine.

Reading the output

Section titled “Reading the output”

On macOS, where the boundary is Seatbelt:

Terminal window
$ commandchain-runner doctor


commandchain-runner doctor - containment check
  host type   self_hosted
  provider    darwin-seatbelt
  platform    darwin
  tier        seatbelt


  local diagnostics (not sent to the control plane):
    nodePlatform           darwin
    nodeArch               arm64
    kernel                 24.6.0
    sandboxExecPath        /usr/bin/sandbox-exec
    inheritedRestriction   verified: granted read allowed, ungranted read denied after execve
    networkPolicyExpressible true
    launchedChild          ran through the shared launcher and exited 0


OK - every agent process on this machine will run inside this boundary.

On Linux, where it is Landlock:

Terminal window
$ commandchain-runner doctor


commandchain-runner doctor - containment check
  host type   self_hosted
  provider    linux-landlock
  platform    linux
  tier        landlock


  local diagnostics (not sent to the control plane):
    nodePlatform           linux
    kernel                 6.8.0-136-generic
    helperPath             /home/maya/.cache/commandchain-runner/helpers/landlock-exec-0.1.2-x64-3e3c8c90e5bf3e93
    landlockAbi            4
    handledAbi             4
    inheritedRestriction   verified: granted read allowed, ungranted read denied after execve
    launchedChild          ran through the shared launcher and exited 0


OK - every agent process on this machine will run inside this boundary.

Line by line:

LineWhat it tells you
host typeself_hosted for a runner on your own machine
providerWhich containment implementation was selected
platform and tierThe only two fields reported to your workspace. They are what the fleet shows
inheritedRestrictionThe important one. verified means the restriction survived the child becoming another program, which is what makes the boundary cover everything the agent spawns
launchedChildA real process went through the same launcher an agent goes through, and exited cleanly

Everything under local diagnostics stays on your machine. The command says so in its own output, and it is true: kernel versions, helper paths, and profile details are never sent anywhere.

When it fails

Section titled “When it fails”

A failure names the reason, the detail, and what to do about it, then refuses:

Terminal window
FAILED - this machine cannot contain a coding agent, so the runner will not run one here.


  Containment could not be established on this machine, so the agent will not be run here.
  Use the managed (cloud) runner instead - it executes every agent inside a container:
  create the runner from the CommandChain web app and dispatch the run to it.

The common causes:

ReasonWhat it meansWhat to do
Kernel too old, or Landlock not activeThe Linux machine cannot express the policyUse a kernel 5.13 or newer with Landlock enabled, or use a managed runner
sandbox-exec missing or shadowedOn macOS, the system sandbox helper is not the one that ships with the OSCheck PATH, or use a managed runner
Probe failedThe policy was built but the operating system did not enforce itThis machine cannot host a self-hosted runner. Use a managed runner
Unsupported platformWindows, or an architecture with no published runnerUse a managed runner

There is no flag that turns any of these into a warning, and there is no degraded mode. A runner that cannot contain an agent does not run one.

Next steps

Section titled “Next steps”