Run Agents on boxd

boxd gives you Linux machines that you reach over SSH. A machine keeps running when your computer sleeps, so your agents keep working. You get herdr Panes, agent notifications, Changes and previews on a machine that is always on.

Before You Start

• A boxd account, and the boxd CLI signed in on your computer with boxd auth login.
• Tailscale on your phone, signed in. See Connect with Tailscale.

1. Create the Machine

On your computer, run:

boxd machine new shed --vcpu 1 --auto-hibernate-timeout 0

Change shed to the name you want. --auto-hibernate-timeout 0 keeps the machine awake. See Keep the machine awake. The CLI also adds the machine to your ~/.ssh/config as shed.boxd.

2. Set Up herdr and the pocketty Daemon

The script at pocketty.app/vm.sh installs herdr with its hooks for your agents, runs herdr as a systemd user service, and installs the pocketty daemon, which sends agent notifications. Run it on the machine:

curl -fsSL https://pocketty.app/vm.sh | ssh shed.boxd bash

boxd machines do not have Pi, so the script skips the hooks for Pi.

3. Connect through Tailscale

The script in step 2 does not install Tailscale. On your computer, open a shell on the machine with ssh shed.boxd. Then follow Connect with Tailscale: install Tailscale on the machine, join your tailnet, and add the machine on your phone. The User is boxd, and Sign in with is Tailscale SSH.

4. Start an Agent

When herdr runs, the host screen shows New workspace. Tap it, type a name, and tap Create. The new Pane opens with a shell. Start your agent there. boxd machines come with Claude Code. Install other agents yourself, and sign in to them as you do on any computer.

The machine now works like any other host:

• Agent notifications come from the pocketty daemon on the machine. The phone pairs with it when it connects. On the machine, pocketty devices lists your phone.
• Changes and the file browser show the files on the machine.
• Previews load the dev servers on the machine through SSH.

Keep the Machine Awake

boxd freezes a machine that gets no network traffic from outside. A frozen machine runs nothing. Your herdr Panes stop, the pocketty daemon cannot send notifications, and pocketty cannot reach the machine through Tailscale.

• A machine hibernates after 4 hours with no inbound traffic. The --auto-hibernate-timeout 0 option in step 1 turns this off. For a machine that you already have, run boxd machine config set shed auto-hibernate.timeout 0.
• Auto-suspend is off by default. Keep it off.

The idle timers watch only network traffic that comes in to the machine. Your agent’s own requests go out, so they do not count. A busy agent can still look idle.

If a machine is frozen, wake it from your computer with ssh shed.boxd true. Your Panes then continue where they were.

If It Does Not Connect

• Timeouts: check that Tailscale runs on your phone, and that the machine is awake. On your computer, ssh shed.boxd 'tailscale status' shows the machine’s tailnet state.
• Sign-in refused: check that Sign in with is Tailscale SSH, and that Tailscale SSH is on. To turn it on, run ssh shed.boxd 'sudo tailscale set --ssh'.
• No New workspace: herdr does not run. On the machine, check systemctl --user status herdr.
• No notifications: on the machine, check pocketty status and pocketty devices. Check that the machine is awake. See Keep the machine awake and Agent Notifications.