# Changing a device's settings

Source: https://codeherder.com/docs/device-settings/

Change six device settings from the web app, see when each one takes effect, and learn why a device can show a different value.

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](https://codeherder.com/docs/variables/) and [Secrets on a device](https://codeherder.com/docs/device-secrets/).

## 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](https://codeherder.com/docs/devices/#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](https://codeherder.com/docs/agent-isolation/) covers `CH_ALLOW_UNISOLATED_PLANNING`.
- [Self-hosted device isolation](https://codeherder.com/docs/self-host-device-isolation/) covers `CH_ALLOW_UNISOLATED_GIT_CREDENTIALS` and `CH_REQUIRE_ISOLATED_EXECUTION`.
- [Running a stage in your own container image](https://codeherder.com/docs/stage-images/) 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](https://codeherder.com/docs/updating/).

## 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](https://codeherder.com/docs/devices/) — the device page, health checks and who sees what
- [Isolating agent runs on a device](https://codeherder.com/docs/agent-isolation/) — the isolation options these settings affect
- [Self-hosted device isolation](https://codeherder.com/docs/self-host-device-isolation/) — how the strict settings combine on each execution mode
- [Running a stage in your own container image](https://codeherder.com/docs/stage-images/) — the setup script setting
- [Git tokens on a device](https://codeherder.com/docs/git-tokens-on-a-device/) — the tokens that `CH_ALLOW_UNISOLATED_GIT_CREDENTIALS` governs