# Guardrails

Source: https://codeherder.com/docs/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](https://codeherder.com/docs/skills/) 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](https://codeherder.com/docs/device-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](https://codeherder.com/docs/agent-isolation/) 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.

## Related guides

- [Skills](https://codeherder.com/docs/skills/): the catalog route for instructions an agent follows.
- [Plugin sources](https://codeherder.com/docs/plugin-sources/): why a plugin never creates a guardrail.
- [When a task says “Repo config not trusted”](https://codeherder.com/docs/repo-harness-config/): why repo hooks stay refused.
- [Changing a device’s settings](https://codeherder.com/docs/device-settings/): `CH_GUARDRAILS`.
- [Harnesses](https://codeherder.com/docs/harnesses/): the harnesses a launch config can run.
