Skip to main content
The boxd and Sheprd logos side by side. Sheprd is an open-source native client for herdr on macOS, Linux, and Windows. It shows terminal sessions, workspaces, Git worktrees, and agent activity from your laptop and from cloud devices in one window. The boxd provider makes boxd machines into Sheprd cloud devices. Sheprd creates the machine, installs Herdr in it, and connects through boxd’s API with your API key, so there is no SSH key to set up. It ships as an experimental provider in Sheprd 20261108.1 and later.

Set up

1

Install Sheprd

On macOS:
On Linux:
Cloud devices are not available on Windows.
2

Create an API key

Machines are created and billed in the key’s organization.
3

Add the key to Sheprd

Open Settings > Cloud devices > boxd. Keep the API URL https://boxd.sh:9443, paste the key, and save. Sheprd keeps the key in your system’s credential store, and it sends it only to the API URL.To set it from a shell instead, save the URL and start Sheprd with the key in HERDR_BOXD_API_KEY:
4

Create a machine

Click Create machine in the same tab. Or ask for one from a terminal and confirm in the Sheprd window:
cloud create prints the batch ID that cloud wait takes. Once the machine is ready, it shows up in the sidebar next to Local:
Open a workspace on it and start Claude Code, Codex, or another agent there.

Run commands from an agent

An agent on your laptop can run one command on a device with cloud exec, through the same connection Sheprd uses:
The command runs as the machine’s boxd user. Its output, error output, and exit code come back as if it ran locally. Use bash -lc for tools installed in ~/.local/bin, such as herdr.

Sleeping machines

boxd suspends or hibernates a machine that sits idle. A connected device counts as traffic, so it stays awake while Sheprd is connected to it. When Sheprd connects to a machine that went to standby, hibernated, or was stopped, it resumes, wakes, or starts it first. In our test, cloud exec on a hibernated machine returned in under 2 seconds. Sheprd doesn’t change a machine’s idle timeouts. Set them in boxd if a machine should never sleep.

Remove a machine

Use Remove device… in the device’s sidebar menu. Sheprd first checks the machine for work that isn’t pushed, then deletes it at boxd with its disk. From a terminal:
Confirm in the Sheprd window. Remove in Settings only forgets the device and leaves the machine at boxd.

Settings

The [boxd] table in Sheprd’s config, set with sheprd config set boxd.<key>: HERDR_BOXD_API_KEY takes precedence over the saved key, and HERDR_BOXD_API_URL replaces api_url.

What each machine gets

  • A generated name: sheprd-<words>, such as sheprd-sunny-badger-16. Sheprd tracks the machine by its ID, so renaming it in boxd doesn’t break the device.
  • Labels: sheprd=device, plus any [boxd] labels. Settings counts the machines with sheprd=device that the key can see.
  • The default image: boxd’s Ubuntu 24.04, with Herdr and herdr-core installed by Sheprd when Install Herdr is on, which is the default. The [cloud] setup script runs next, before the machine is ready.
  • No SSH keys: Sheprd runs itself as a relay over boxd’s exec API. The API key stays on your computer.
  • A clean failure: if creating the machine or installing Herdr fails, Sheprd deletes the machine again. If only the [cloud] setup script fails, the machine stays saved, and you remove it like any other.
Sheprd’s cloud devices docs cover the rest, including the [cloud] setup script, Smart Dispatch, and the other providers.