BoxHaven Agent Skill

Install the BoxHaven skill on your development laptop to teach Codex or Claude how to create boxes, run persistent agents, launch tasks in parallel, check progress, open previews, and bring results home. It also explains project sync and .boxhavenignore, and links to the current documentation when your agent needs more detail. The skill and its launcher live in the public BoxHaven repository. They use the bh CLI and your existing login.

Install

Use Vercel's Skills CLI, the installer behind skills.sh. Install Node.js 22.20 or later, then run:

npx skills add finbarr/boxhaven \
  --skill boxhaven -g \
  -a codex claude-code

-g makes the skill available across your projects. -a selects the agents; use just -a codex or -a claude-code if you only use one. The installer puts the skill, its references, and its launcher in the agents' skill folders and records the source for future updates. With its default symlink installation, the shared files live in ~/.agents/skills/boxhaven; Claude's ~/.claude/skills/boxhaven points to that copy.

For a project installation shared with your team, omit -g and run the command from that project's root. Commit the installed skill files, agent links, and skills-lock.json with the project.

To see what will be installed without installing it:

npx skills add finbarr/boxhaven --list

Open a new agent session after installing if the skill is not yet visible. Invoke $boxhaven in Codex or /boxhaven in Claude, followed by your request. For example:

Use BoxHaven to create three boxes for these three prototypes. Give each agent its own task directory, verify that it starts working, and return the preview URLs and reattach commands. Leave the boxes running for the demo.

The skill can also be selected automatically for relevant BoxHaven tasks. It requires bh 0.2.0 or later and your existing BoxHaven login. It does not install or upgrade bh, or authenticate for you; follow getting started for those steps.

Updates And Versions

Update a global installation with:

npx skills update boxhaven -g

For a project installation, run npx skills update boxhaven -p in that project. Updates replace the installed skill files, so keep personal additions outside the installed package. If you previously copied the skill manually, run the installation command above to register its source with the installer.

The unpinned install follows the repository's default branch when you request an update. Publishing a change does not automatically update your local copy. The installer records the Git source/ref and a content hash; its project lock file is skills-lock.json. The metadata.version in SKILL.md identifies the instructions and metadata.minimum-bh-version identifies the required CLI. The installer does not enforce that CLI requirement; the skill tells the agent to check bh version.

To pin skill 1.0.0 to its Git tag:

npx skills add 'finbarr/boxhaven#boxhaven-skill-v1.0.0' \
  --skill boxhaven -g -a codex claude-code

Updates preserve that ref. To move to another version, install from its tag; to follow the default branch again, rerun the unpinned installation command. npx skills@1.5.24 would pin the installer, not the BoxHaven skill. In Skills CLI 1.5.24, skills check is an alias for update, not a read-only check. Use npx skills ls -g to list installed skills.

Skill changes are reviewed alongside CLI and docs changes in the same repository. Skill releases get boxhaven-skill-v<version> tags; future CLI release tags also contain the skill. The older v0.2.0 CLI tag predates the skill and cannot be used to install it.

Project Sync And Documentation

The installed sync reference explains default exclusions, rsync patterns in .boxhavenignore, and how to retrieve work without overwriting remote edits. .gitignore is not a BoxHaven sync filter. See bh sync for the CLI contract.

The skill includes a map of the CLI reference, security model, teams, and other docs, and tells the agent when to fetch them. Agents can discover the pages through llms.txt and fetch Markdown sources such as commands.md. These exports are generated from the same source as the website on every build.

Inside A Remote Box

The laptop skill manages boxes through your local bh login. Separately, the golden VM image installs a Codex skill named boxhaven-web-preview inside the box. That skill explains the box's public preview URL, bind address, port, and TLS setup. Its updates ship with rebuilt VM images, not the laptop skill installer; an existing box keeps its installed runtime skill.

Launch A Batch

Prepare separate project directories with clear TASK.md instructions. Put a manifest outside those directories, for example:

demo/
  tasks.json
  orchard/TASK.md
  observatory/TASK.md

tasks.json:

[
  {
    "name": "demo-orchard",
    "directory": "./orchard",
    "agent": ["codex", "Read TASK.md and build the app. Verify it and keep its preview running."]
  },
  {
    "name": "demo-observatory",
    "directory": "./observatory",
    "agent": ["claude", "Read TASK.md and build the app. Verify it and keep its preview running."]
  }
]

With the default global installation:

python3 ~/.agents/skills/boxhaven/scripts/launch.py \
  /path/to/demo/tasks.json --jobs 2

The launcher requires Python 3 and bh on PATH; --bh /path/to/bh selects a specific binary. Add size, provider, region, image, or team to each manifest entry when needed. Otherwise the CLI's configured defaults apply. The agent array accepts ordinary Codex or Claude arguments, including an explicit model when you want one.

The launcher validates every entry and checks for existing names before creating anything. It starts each agent as its VM becomes ready, writes stage logs and results.json to the printed temporary directory, and leaves boxes running. A failed job does not stop the others. It never automatically retries or destroys a box. VM charges continue until you destroy it.

Inspect And Reattach

bh list
bh status demo-orchard
bh run demo-orchard tmux capture-pane -p -t boxhaven -S -100
bh connect demo-orchard
# Ctrl-b, then d disconnects; the agent keeps running.

Read the session output before reporting that an agent is working. Open and exercise its public preview before reporting that an app is ready. The console provides a Public preview link in each box row and an Open preview button in its details.

Retrieve the result from the matching local task directory:

cd /path/to/demo/orchard
bh sync down demo-orchard --force

This overwrites local files. Keep each box's result in its own directory. When the demo is over, destroy only the boxes you created for it:

bh destroy demo-orchard
bh destroy demo-observatory
bh list