Changing a device's settings

Some device behavior depends on settings that an operator normally sets as environment variables on the machine. Six of them you can also change from the web app. You do not need a shell on the device.

CodeHerder stores the values and sends them to the running device. A replacement machine for the same device picks them up the first time it starts.

This page covers those six settings. Other device options still come from the device’s own environment or its start-up flags. Values that agents read in their sessions are different. See Variables and Secrets on a device.

Where to find them

Open the device’s detail page (Set up → Devices → [the device]) and scroll to the Settings section. Each setting shows:

• Its name.
• A Restart required badge, if a change waits for a restart.
• A Weakens isolation badge, if a value of this setting can lower a safety guard. Saving a new value asks you to confirm.
• The value the device uses now, and where that value came from: host, server or default.
• A short description.

Who can see and change them

The Settings section follows the same rule as host details. The device’s owner, and admins and owners of a workspace the device is linked to, can see it. Everyone else does not see it. See Who sees host details.

An owner or admin of the device’s workspace can change the settings. They must use the web app as a person. An admin of a linked workspace can see the settings but cannot save them. An archived device cannot be changed. An agent token or a session credential cannot change them. A person without that rank sees “Set by an admin” and the value, with no controls.

The six settings

Setting	What it controls	When a change applies
CH_ALLOW_UNISOLATED_PLANNING	Whether a non-writable stage may run when a push credential is readable and the device has no dedicated agent user. On by default. Turn it off to refuse those stages. Weakens isolation.	At once
CH_ALLOW_UNISOLATED_GIT_CREDENTIALS	Whether agents on a device with no isolation can read the device’s git tokens. Off by default. Weakens isolation.	After a restart
CH_HOST_BEFORE_SCRIPT	Whether a stage’s setup script may run directly on a device that has no container. Off by default. Weakens isolation.	At once
CH_REQUIRE_ISOLATED_EXECUTION	Whether the device refuses work that runs with approvals bypassed unless it has a hostile-agent boundary. Off by default. Weakens isolation.	After a restart
CH_TRUST_REPO_HARNESS_CONFIG	Whether the device trusts hooks, helper commands, plugins and MCP servers that a repository commits. Off by default. Weakens isolation.	After a restart
CH_INPUT_SUBMIT_DELAY_MS	The pause, in milliseconds, between pasted text and the submit keystroke. The default is 200.	At once

Each setting links to a page that explains it:

• Isolating agent runs on a device covers CH_ALLOW_UNISOLATED_PLANNING.
• Self-hosted device isolation covers CH_ALLOW_UNISOLATED_GIT_CREDENTIALS and CH_REQUIRE_ISOLATED_EXECUTION.
• Running a stage in your own container image covers CH_HOST_BEFORE_SCRIPT.

CH_TRUSTED_EXECUTION is not on this list. You cannot set it from the web app. It stays an environment variable on the device.

Saving a change

Each on/off setting is a menu with three choices:

• Unset (default: …) removes the stored value. The device uses its default.
• On and Off store that value.

The other setting, CH_INPUT_SUBMIT_DELAY_MS, is a text field. Enter a number of milliseconds, zero or more. Clear the field to unset it.

Select Save settings to save every row you changed in one step.

If you give a Weakens isolation setting a new value, CodeHerder asks you to confirm first. The prompt names the settings and says the audit log records the change. Clearing a setting never asks. CodeHerder records each changed setting.

When a change takes effect

• At once. A connected device applies the value right away.
• After a restart. The device keeps its current value until an operator restarts it. The device never restarts itself, and CodeHerder does not restart it for you.
• Device offline. The device gets the values when it reconnects.

When a device starts, it asks CodeHerder for its settings. If CodeHerder is not reachable, it uses the last copy it received.

The device must run a current release to take part. An older release ignores pushed settings. See Updating the CLI.

When the device shows a different value

Each row can carry a short notice. The value in use and the value you saved can differ for these reasons:

• The host environment wins. An environment variable set on the device itself beats the web-app value. The row says “The host environment sets this knob and wins over the server value.” Remove the variable on the device, and restart it if the setting needs a restart.
• The device has not applied it yet. The row says “The device has not applied this value yet.” This is normal for a moment after you save. If it stays, check that the device is online.
• A restart is pending. The row says “Takes effect when the operator restarts the device. The device never restarts itself.”
• The device has not reported. The row says “The device has not reported this setting yet.” A device that has just connected can show this.

The order of precedence is the host environment, then the saved server value, then the default.

Read the settings from the CLI

ch device show <device>

Below the device details, a SETTINGS table lists one row per setting with these columns:

Column	Meaning
NAME	The setting.
EFFECTIVE	The value the device uses.
SOURCE	Where that value comes from: host, server or default.
DESIRED	The value saved in CodeHerder.
APPLY	Whether a change applies live or needs a restart.
DRIFT	none, pending_apply, pending_restart, host_override or not_reported.

Add --json to get the same data under a top-level settings key.

The CLI has no command to change these settings. Use the web app. The table does not appear if you cannot see host details.

Related guides

• Managing your devices — the device page, health checks and who sees what
• Isolating agent runs on a device — the isolation options these settings affect
• Self-hosted device isolation — how the strict settings combine on each execution mode
• Running a stage in your own container image — the setup script setting
• Git tokens on a device — the tokens that CH_ALLOW_UNISOLATED_GIT_CREDENTIALS governs