Getting Started

This guide installs the bh CLI, logs in to a backend, creates your first box, and resumes an agent session on it.

Install The CLI

Install script

One-liner (macOS and Linux, installs the latest release):

curl -fsSL https://raw.githubusercontent.com/finbarr/boxhaven/master/install.sh | sh

The script downloads the latest bh release for your platform, verifies it against the release's SHA256SUMS, and installs it to /usr/local/bin (sudo when needed) or ~/.local/bin as a fallback. Set BOXHAVEN_VERSION to install a specific release tag and BOXHAVEN_INSTALL_DIR to choose the install directory.

Homebrew

Via the finbarr/tap tap:

brew install finbarr/tap/boxhaven

From a release archive

Tagged releases publish prebuilt bh archives for Linux and macOS (amd64 and arm64) on the GitHub releases page. Download the archive for your platform, extract it, and put bh on your PATH:

tar -xzf bh_<version>_<os>_<arch>.tar.gz
install -m 0755 bh ~/.local/bin/bh
bh version

From source

git clone https://github.com/finbarr/boxhaven.git
cd boxhaven
make build
./bh version

Install it to ~/.local/bin when you want bh on your shell path:

make install

A plain Go build also works:

go build -o bh ./cmd/bh

Normal commands periodically check the public BoxHaven GitHub releases in a background process. The result is cached for 24 hours in ~/.config/boxhaven/version-check.json (or the matching $XDG_CONFIG_HOME path), so an update check never delays a command and is silent when the network is unavailable. If a newer release is cached, bh prints a concise link to that release.

Log In

Use the hosted backend:

bh login

Creating a hosted account requires accepting the Terms of Service and acknowledging the Privacy Policy. These policies do not govern self-hosted deployments operated by someone else.

Use a local or self-hosted backend:

bh login --backend-url http://127.0.0.1:8787

The CLI prints a browser URL, tries to open it, and waits for the web app to grant access. The resulting session token is stored in ~/.config/boxhaven/config.toml. BOXHAVEN_BACKEND_URL and BOXHAVEN_TOKEN override the stored config when set.

Enable Direct SSH

Install managed OpenSSH aliases once after logging in:

bh ssh-config install

This adds an Include line to ~/.ssh/config, creates a device key under ~/.boxhaven/ssh, and manages an alias named bh-<name> for each ready box. Aliases update after normal box lifecycle commands; run bh ssh-config refresh to force an update or bh ssh-config uninstall to remove the managed include.

Create A Box

Run this from the project you want to work on remotely:

bh create work

bh create asks the backend to provision a VM, waits until the BoxHaven agent and SSH certificate trust are ready, then syncs the current directory to:

/opt/boxhaven/project

Use one of the larger built-in sizes when needed:

bh create work --size medium

Team owners and admins can also name any plan exposed by a configured provider:

bh size plans --provider digitalocean
bh size create gpu --provider digitalocean --plan gpu-4000adax1-20gb
bh create work --size gpu

Pick a specific provider, region, or image when the backend has more than one provider configured:

bh create work --provider hetzner --region fsn1

Without --provider, the backend default applies. Set a sticky default with the provider key under [remote] in .boxhaven.toml or the global config. See Cloud Providers for the full provider configuration.

Skip the initial sync only when you intentionally want an empty project path:

bh create work --no-sync

Every account automatically gets a default team, and your first box lands there: new boxes go to your session's active team, which bh login pins to that default team until you switch to another one. See Teams for sharing boxes with teammates.

Use the box through normal OpenSSH clients:

ssh bh-work
scp ./notes.txt bh-work:/opt/boxhaven/project/
rsync -az ./fixtures/ bh-work:/opt/boxhaven/project/fixtures/

The same alias works with tools that read OpenSSH configuration, including VS Code Remote SSH. Each invocation transparently obtains a new short-lived certificate from the backend; the SSH connection itself goes directly to the box.

Run Commands

Run a noninteractive command:

bh run work bash -lc 'go test ./...'

Start or attach to the managed tmux session:

bh run work codex
bh connect work

Interactive commands such as codex, claude, gemini, opencode, copilot, pi, and a bare bash or shell use the managed tmux session. Shells with arguments (bash -lc '...') and other commands run directly over SSH.

bh run never touches the project files on the box: the project syncs when the box is created and when you run bh sync up (which mirrors deletions). Work done by agents on the box stays put until you pull it back with bh sync down. Pass --sync to a run to mirror local files first. Sync excludes common dependency/cache directories such as node_modules/, .next/, and .venv/ by default; add .boxhavenignore at the project root for additional rsync-style exclude patterns.

Resume Your Local Agent Session

Starting claude or codex forwards your newest local sessions for this project, so you can resume the conversation you were having on your laptop:

bh run work claude --continue

Disconnect whenever you like — the agent keeps running in the box's tmux session. Press Ctrl-b, then d to detach. bh connect work reattaches, and bh list shows which boxes are online.

Install The Agent Skill

Let Codex or Claude on your laptop operate the CLI for you. With Node.js 22.20 or later, use Vercel's Skills CLI, the installer behind skills.sh:

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

Invoke $boxhaven in Codex or /boxhaven in Claude. The skill teaches box creation, persistent agents, .boxhavenignore, sync, previews, and retrieving results. It includes a launcher for independent tasks in parallel and links to current docs when your agent needs more detail.

Update it with npx skills update boxhaven -g. See the agent skill guide for project installation, version pins, and batch examples. The skill requires bh 0.2.0 or later and the login you set up above.

Open A Web Preview

In the console, click a box's Public preview link, or open its details and click Open preview. The app opens in a new tab. Each box gets its own small character inspired by the BoxHaven logo, which stays the same when you rename the box or move it to another team.

bh status work also shows the public URL. Inside the box, use BOXHAVEN_PREVIEW_URL for the shareable address and serve HTTP on $BOXHAVEN_WEB_BIND:$BOXHAVEN_WEB_PORT (normally 0.0.0.0:80). Keep the server running in its own tmux session. A preview URL is assigned before your app is running; open it and verify the app before calling it ready. Serve only the intended public directory, not a checkout containing credentials or private files.

Sync Files

Push local changes to the box:

bh sync up work

Pull remote changes back to the local checkout:

bh sync down work --force

Excluded paths are not deleted by sync, so dependency directories installed on the box can stay warm across later bh sync up runs. Sync completion reports elapsed time, network bytes, changed bytes, and file counts.

sync down overwrites local files by design, so it requires --force.

Push To GitHub From The Box

For agent workflows that commit and push from the remote box, use an HTTPS GitHub origin and make local GitHub auth available before creating or connecting:

gh auth login
git remote set-url origin https://github.com/<org>/<repo>.git
bh run work codex

When the project origin, or an immediate child repository's origin in a multi-repository workspace, points at GitHub, the CLI forwards GH_TOKEN or GITHUB_TOKEN when set, otherwise it falls back to gh auth token from the local GitHub CLI. The token is written to /run/boxhaven/session.env on the VM. The remote image includes a Git credential helper that uses those variables for HTTPS GitHub operations.

The same remote commands also forward selected agent login/config files (Claude, Codex, Gemini, Copilot, opencode) from your local home directory, so a newly created box reuses your local agent logins. Recent claude/codex sessions for the current project are forwarded when you start those agents; broader histories, caches, and databases are never copied. See the Security Model for exactly what is forwarded.

Inspect And Clean Up

bh list
bh status work
bh destroy work

Destroy boxes when the work is done so the cloud provider does not keep billing for idle machines. The CLI prompts before destroying; pass --force only for noninteractive cleanup scripts.