CodeHerderSearch⌘KRequest access →

Guardrails

Ship an enforced check to every stage session on any harness. Learn what to upload, which events exist and how to read the evidence.

A guardrail is a small script that an admin writes. It checks what an agent does in a stage. A guardrail can block a command, bounce a hand-off, or add a reminder.

A guardrail works the same on every harness. Claude Code, Codex, Cursor, OpenCode, Pi and mini-swe-agent all meet the same rules. Changing a stage from one harness to another does not change what is allowed.

A skill only asks an agent to behave. A guardrail enforces the rule.

Who can write a guardrail

Only a human workspace admin can create, change, disable or delete a guardrail. A group admin can do the same for a group, and every workspace below it inherits the guardrail.

  • An agent session that tries to change a guardrail gets a 403.
  • A human who is not an admin gets a 403.
  • Every member and agent can read guardrails.

What you can upload

A guardrail is a folder. It holds a GUARDRAIL.md manifest and the executable scripts that the manifest names. Each script starts with a #! line.

  • A folder holds up to 64 files.
  • A file is at most 256 KiB. A folder is at most 512 KiB.
  • A workspace owns at most 32 guardrails.

Open Settings > Guardrails, or use the CLI:

ch workspace guardrails create --from-dir ./go-test-count-guardrail

This manifest blocks go test with no -count=1.

---
name: go-test-count-guardrail
description: Block go test without -count=1
event: command
commands: [go]
entry: go-test-count-guardrail.sh
timeout: 30s
on_error: block
stages: [code, verify]
---

The script gets the command’s own arguments.

#!/usr/bin/env bash
[ "$1" = test ] || exit 0
for arg in "$@"; do
  [ "$arg" = "-count=1" ] && exit 0
done
echo "Run go test with -count=1." >&2
exit 2

Manifest keys

Key Rule
name 1 to 80 characters.
description Up to 500 characters. Optional.
event One of the events below.
commands Required for command and after_command. Not allowed for report. Up to 16 plain command names, such as go. A path is refused. ch, sh, bash and env are refused.
entry A script in the guardrail. It needs a script extension and a #! line.
timeout 1 to 120 seconds. The default is 30 seconds. A report guardrail gets at most 30 seconds.
on_error block or allow. The default is block.
stages Up to 32 stage keys. Empty means every agent stage.
workflows Up to 32 workflow keys. Empty means every workflow.

Events

Event When it runs Can it stop the agent?
command Before the agent runs a guarded command. Yes. Exit 2 blocks the command.
after_command After a guarded command ends. No. It adds a reminder. The exit code stays the same.
report When the agent moves its task forward with a hand-off. Yes. Exit 2 bounces the hand-off.

A command guardrail works through a shim. CodeHerder puts a small program with the command’s name first on the PATH of the stage. The shim runs your script with the real arguments. Then it runs the real command. Any harness that runs the command meets the shim.

A report guardrail runs on the server side of the advance. The agent calls ch task status. CodeHerder asks the device to run your script in the stage, as the stage user. The agent cannot skip it or forge the result. A bounce is a 409 guardrail_blocked with your message. The task’s advance preview does not show a report guardrail: the result depends on the hand-off, which exists only at the advance.

Some harnesses run each command in a login shell, and a login profile can change PATH. CodeHerder puts the shim back in front after the profile runs, for bash and zsh. The rest of the agent’s PATH stays the same.

A command that the agent runs by its absolute path, such as /usr/local/go/bin/go, skips the shim. A report guardrail has no such gap.

What a script receives and returns

A script gets the guarded command’s arguments as its own arguments. A report script gets none.

Every script also gets one JSON object on standard input:

Field Meaning
event command, after_command or report.
command, argv The guarded command and its arguments. Not set for report.
cwd The working directory.
taskId, stage The task and the stage.
exitCode The command’s exit code. Only for after_command.
targetStage, report The stage the agent moves to and the hand-off text. Only for report.

The script also gets CH_GUARDRAIL_* environment variables and a short allowlist of others. It gets no CodeHerder token and no harness credential.

The runner reads the script exit code.

Result What happens
Exit 0 The action goes on.
Exit 2 The action is blocked. The agent sees the script’s standard error, clipped to 2 KB.
Any other exit, a signal, or a timeout The guardrail failed. The on_error value decides: block blocks, allow lets the action go.

Standard output is dropped. A script cannot talk to the agent through it. A blocked command prints guardrail <slug> blocked <command>: <message> and exits with 126.

Scope and inheritance

A guardrail applies to task stage sessions on agent stages. Dev sessions and optimization runs load no guardrails.

The stages and workflows keys narrow a guardrail. Empty lists mean no narrowing.

A descendant workspace can add its own guardrails. It cannot change an inherited guardrail. Such a write gets guardrail_inherited. Guardrail slugs are unique along the chain of workspaces.

Versions and audit

Each edit writes a new version. You can list versions, diff two of them, and revert. A revert writes a new version. It does not rewrite history. Each create, update, enable, disable, delete and revert is an audit event.

Device opt-out

A device owner can turn guardrails off with the CH_GUARDRAILS setting. See Changing a device’s settings. The device then stops taking guarded stages.

If no capable device runs guardrails, the task shows guardrails_unplaceable. Turn guardrails on with CH_GUARDRAILS, or update ch on a device.

Harnesses

Guardrails run at points CodeHerder owns, so every harness meets the same guardrails. A harness change never changes what a guardrail allows. A native harness hook can add early feedback in the future. It never replaces these points.

No stage is refused because of its harness. A task shows guardrails_unplaceable only when no capable device runs guardrails.

Posture

The device reports how safe the guardrail is from the agent. The session records one posture:

  • enforced: the agent cannot write the guardrail files or the settings layer. A container stage, a dedicated agent user and a microVM that serves one root workspace give this.
  • tamperable: the agent shares the device user. It could rewrite the guardrail files.
  • unknown: the device has not reported yet.

See Isolating agent runs on a device for the isolation options.

Evidence

Each session records the evidence:

  • The session page lists the guardrail set hash, the posture and each loaded guardrail. ch session show prints the same block.
  • Each block records the guardrail, the event, the command and its arguments, and the message the agent saw.
  • Each block adds a guardrail.blocked event to the task activity.
  • ch workspace guardrails stats <guardrail> counts blocks and errors over a window.

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