CodeHerderSearch⌘KRequest access →

Who can run code on your device

What a compromised server or a workspace admin can run on a linked device, what is recorded, and how to limit it.

A device runs the work that its server sends. This page says who can make a device run code, what CodeHerder records, and how you limit the risk.

What the server can do on a linked device

The device dials out to the server. The server then sends spawn instructions: the command, the arguments and the environment of an agent. The device checks each instruction against a copy of the agent settings. The same server filled that copy. So the check does not stop a server that an attacker controls.

Assume this rule: a compromised server can run code on every device that is linked to it. The launch settings that CodeHerder creates for an agent skip the harness approval prompts, so no one on the device approves each step. By default, the code runs as the OS user that started ch device-server. If the device runs agents as a dedicated user, in a container or in a microVM, the code runs there instead. See Isolating agent runs on a device.

CodeHerder accepts this risk for the first release. A device-side allowlist or signing key is not part of it.

Who can make a linked device run code

Several people in a workspace can make a device run code, if the device is linked to that workspace:

  • Any workspace member can file work. An agent runs the work on a device that is linked to the workspace. The member does not need to own the device.
  • An admin can edit an agent’s launch configuration: the command, the arguments and the environment. The agent’s operator can do the same while they hold admin rank.
  • The session’s own person, or a workspace admin, can attach to an agent’s session or send text to it. A session with no agent is different: only its owner can do this.
  • An admin can change a device’s remote settings, including settings that weaken isolation. See Device settings.

What is recorded

CodeHerder writes these events to the activity feed. Each event names the person or member that acted.

  • session.attached and session.detached, with the attach grant.
  • session.input, each time input is sent to a session. It records how many bytes were sent and whether the input was submitted. It does not record the text.
  • agent.config_updated, which says if the command, the arguments or the environment changed. It does not show the old or new values.
  • device.workspace_linked and device.workspace_unlinked.
  • device.workspace_excluded and device.workspace_included, when a device is turned off or on for one workspace.
  • device.enabled, device.disabled, device.archived and device.restored.
  • device.setting_changed, one for each remote setting that changes. It says if the change weakens isolation.
  • device.secrets_acknowledged, when the list of secrets that a spawn may read changes.
  • device.token_minted and device.token_revoked.
  • device.operator_capabilities_changed, when the capability labels of a device change.

The keystrokes that a person types during an attach are not recorded. This protects secrets and personal data. The attach event also does not say if the person typed anything. Use the session.input events and the session transcript to see when input was sent and what the agent did.

How to limit it

Each control below has an owner. Not every device owner holds every control.

  • Pause or archive a device. An admin or owner of the device’s main workspace can do this. So can the device’s owner, while they hold admin rank there. A device owner who is a plain member cannot. CodeHerder refuses to archive a device while it has live sessions. Stop the sessions first. See Managing your devices.

  • Unlink a device from a workspace. An admin of that workspace can do this. The device stays linked to its other workspaces.

  • Enable a paused device again. The same people who can pause it can enable it. A personal device is the exception; see below.

  • Stop the device server. Anyone who runs ch device-server can stop it. The device then runs no work.

  • Cut off a device token. Deleting the token file on the device does not revoke the token. The server still accepts it, and a live link stays open. Use these commands instead:

    • ch device rotate-token <device> revokes every token of the device, closes its link and prints one new token. Only the device’s owner can run it, while they hold admin rank in the main workspace.
    • ch device revoke-token <device> <tokenId> revokes one token and closes the link. The device’s owner can run it, or an admin or owner of the main workspace.
    • ch device archive <device> revokes every token and takes the device out of the fleet.

    Rotate and revoke refuse a microVM pool, because a pool holds no token. Disable or archive the pool instead. See Device tokens.

    A person runs each of these from their own login. An agent cannot. See Device tokens.

  • Keep a personal device personal. A personal device is registered as disabled. Only its owner can enable it, link it to a workspace, approve a settings change that weakens isolation, or approve its secrets. A workspace admin cannot. See Personal devices.

  • Approve secrets yourself. Only the device’s owner or a workspace owner can say which secrets a spawn may read. A workspace admin cannot. See Device secrets.

  • Lock a setting on the device. A value that you set in the device’s own environment wins over the value that the server sends. See Device settings.

  • Limit what an agent reaches. Run agents under a dedicated OS user or in a container. See Isolating agent runs on a device.

  • Leave repo-committed config untrusted. A device refuses a session when its repo commits hooks, helper commands or plugins, unless an operator trusts that repo. See When a task says “Repo config not trusted”.

  • Keep one workspace on each device. A device that serves one workspace exposes only that workspace’s admins. See what a shared device shares.

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