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

Log In

Use the hosted backend:

bh login

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.

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 a larger tier when needed:

bh create work --tier medium

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 personal team, and your first box lands there: new boxes go to your session's active team, which bh login pins to your personal team until you join or switch to another one. See Teams for sharing boxes with teammates.

Run Commands

Run a noninteractive command:

bh run work run 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.

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. bh connect work reattaches, and bh list shows which boxes are online.

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

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 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.