paddock Get started

Docs

InstallOne script on your VPS, one binary on your laptop.

Run the installer on a VPS you control, then install the CLI on your laptop.

  1. Point a domain at your VPS. Or skip DNS and use <your-ip>.sslip.io, which resolves to the VPS IP.

  2. Run the installer on the VPS. Replace the domain and email with your own.

    curl -fsSL https://raw.githubusercontent.com/tony1908/paddock/main/install/install.sh \
  | sudo bash -s -- \
  --domain paddock.example.com --email you@example.com

  3. Open the one-time owner setup link the installer prints, and create the owner account. The setup token is also in /var/lib/paddock/admin.token.

  4. Install the CLI on your laptop. On macOS or Linux, run the server's installer. On Windows, use PowerShell and run the Windows installer. The CLI goes to ~/.local/bin/paddock.

    curl -fsSL https://paddock.example.com/install/cli.sh | sh
    irm https://paddock.example.com/install/cli.ps1 | iex

    You can also download the CLI binary from GitHub Releases. On Apple silicon, for example:

    curl -fsSL https://github.com/tony1908/paddock/releases/download/v0.2.0/paddock_0.2.0_darwin_arm64.tar.gz | tar xz paddock
sudo mv paddock /usr/local/bin/

    Then log in with the owner account, or with an API key from the dashboard's API keys page.

    paddock login --server https://paddock.example.com --email you@example.com
    paddock login --server https://paddock.example.com --api-key <key>

  5. Install the agent skill so Claude Code, Codex, or OpenCode can drive boxes.

    paddock skill install

    Details, including where the skill is written and how to update it, are in Let your coding agent use boxes.

Requirements

RecipesRecipes for the things agents do most.

Each recipe is a few commands you can copy and run. For every flag, run paddock help <command>.

Create a box and run a command

Create a box, which becomes current, then run a command in it.

paddock new --type small --ttl 3600
paddock exec current -- uname -a

Work on your repo

Copy a local project into the box, then run its tests there.

paddock push current . --to /config/project
paddock exec current -- bash -lc 'cd /config/project && npm test'

Run a long job

Start a command in the background, check its output, and stop it when you need to.

paddock exec current --detach -- npm run build
paddock ps current
paddock logs current <processId> -f
paddock kill current <processId>

Give an agent a task

Send a prompt to a coding agent that runs inside the box.

paddock prompt current "Fix the failing tests in /config/project" --provider opencode

Lock down the network

Allow only the domains a box needs when you create it, or cut its network off on a running box.

paddock new --network allowlist --allow-domain api.github.com
paddock update current --network deny-all

Start from a repo

Clone a Git repository into the box on first boot.

paddock new --git https://github.com/you/repo --revision main

Keep data between boxes

Create a drive, mount it into a box at /mnt/cache, and it keeps its files after the box is deleted.

paddock drive create cache
paddock new --mount cache:/mnt/cache

Undo with snapshots

List a box's snapshots, then roll the box back to one of them.

paddock snapshots current
paddock restore current <snapshotId>

Run a GUI app and see it

Start an app on the box desktop, then save a screenshot of the desktop.

paddock exec current --desktop --detach -- ./my-app
paddock screenshot current -o shot.png

Share a port

Give a port inside the box its own public HTTPS URL. Ports 3000, 3001 and 7070 are taken by the box, so serve your app on another port.

paddock host current 8080

Let your coding agent use boxes

The Paddock agent skill teaches your coding agent how to use boxes through the paddock CLI.

Install it for every supported agent with one command:

paddock skill install

It writes the skill to two places:

  • ~/.claude/skills/paddock/SKILL.md for Claude Code. OpenCode reads this folder too, so it picks up the same skill.
  • ~/.codex/skills/paddock/SKILL.md for Codex.

To install for one agent only, pass --claude or --codex. Pass --force to overwrite a copy you have changed.

paddock skill install --claude
paddock skill install --codex --force

Run paddock skill install again after you upgrade the CLI, so the skill matches the new version.

Without the CLI

For other agents, or a machine without the CLI, download the skill file directly. The source is internal/cli/skill.md on GitHub.

mkdir -p ~/.claude/skills/paddock && curl -fsSL https://raw.githubusercontent.com/tony1908/paddock/main/internal/cli/skill.md -o ~/.claude/skills/paddock/SKILL.md

Then ask your agent for something that needs a box:

Run the tests for this repo in a Paddock box and report the result.

Full reference