> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boxd.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Sheprd

> Create boxd machines from Sheprd and use them as devices for your coding agents, with no SSH keys to set up.

![The boxd and Sheprd logos side by side.](https://mintcdn.com/azin/7IWa9uzq2xw7Urj2/images/boxd-x-sheprd.png?fit=max\&auto=format\&n=7IWa9uzq2xw7Urj2\&q=85\&s=e023a8272e94691eb24b21e07b51c271)

[Sheprd](https://sheprd.org) is an open-source native client for [herdr](https://docs.boxd.sh/use-cases/oss-integrations/herdr.md) 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](https://github.com/sheprd-labs/sheprd/pull/1129) 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:

```bash theme={"theme":"github-dark"}
brew install sheprd-labs/tap/sheprd
```

On Linux:

```bash theme={"theme":"github-dark"}
curl -fsSL https://sheprd.org/install.sh | sh
```

Cloud devices are not available on Windows.

**2. Create an API key**

```bash theme={"theme":"github-dark"}
boxd auth keys create sheprd --org <your-org>
```

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`:

```bash theme={"theme":"github-dark"}
sheprd config set boxd.api_url '"https://boxd.sh:9443"'
export HERDR_BOXD_API_KEY=bxd_...
sheprd
```

**4. Create a machine**

Click **Create machine** in the same tab. Or ask for one from a terminal and confirm in the Sheprd window:

```bash theme={"theme":"github-dark"}
sheprd cloud create boxd --json
sheprd cloud wait 1 --timeout 600 --json
```

`cloud create` prints the batch ID that `cloud wait` takes. Once the machine is `ready`, it shows up in the sidebar next to Local:

```json theme={"theme":"github-dark"}
{"id":1,"kind":"create","phase":"done","devices":[{"provider":"boxd","id":"73fbb8ea-…","endpoint":"boxd:73fbb8ea-…","label":"sheprd-sunny-badger-16","state":"ready"}]}
```

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:

```bash theme={"theme":"github-dark"}
sheprd cloud exec sheprd-sunny-badger-16 -- bash -lc 'herdr --version'
```

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](https://docs.boxd.sh/guides/suspend-resume.md) 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:

```bash theme={"theme":"github-dark"}
sheprd cloud destroy sheprd-sunny-badger-16 --json
sheprd cloud wait 2 --timeout 300 --json
```

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>`:

| Setting | What it does |
| - | - |
| `api_url` | boxd's API. `https://boxd.sh:9443`, or a region such as `https://nyc.boxd.sh:9443`. |
| `labels` | Labels added to every machine Sheprd creates, such as `{ team = "web" }`. |
| `allow_plaintext_credentials` | Save the key in a `0600` file when no credential store is available. Default `false`. |

`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](https://sheprd.org/docs/cloud/) cover the rest, including the `[cloud]` setup script, Smart Dispatch, and the other providers.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.