Trybox

Warning

Early beta. Expect rough edges around VM state, source sync, and long runs.

Fresh VM. Dirty checkout. Exact command.

Trybox gives each source checkout a clean local VM: sync your working tree, run the command you pass, stream output, and keep durable logs under ~/.trybox.

The first target is macOS on Apple Silicon through Tart, hidden behind Trybox's target/run workflow.

Quick Start

brew install jwmossmoz/tap/trybox
trybox bootstrap
trybox doctor

cd ~/src/project
trybox run -- ./build-or-test-command test
trybox logs

The Homebrew formula installs the trybox binary and its runtime host tools: cirruslabs/cli/tart and hashicorp/tap/packer. It does not install Go; Go is only needed when building Trybox from source.

To install the current main build instead of the latest release:

brew install --HEAD jwmossmoz/tap/trybox

--HEAD builds from source, so Homebrew also installs Go for that path.

That is the normal workflow. trybox run -- <command> uses the current checkout and target, ensures the local target image exists, starts the VM if needed, syncs the checkout, runs the command in the guest, streams output, and records logs/events.

Local Template Setup

For a quick smoke test, trybox run will create the missing local target image through trybox bootstrap, which currently clones the configured public Tart seed image into Trybox's local target image name.

For maintainer validation, build the Trybox-owned local template from a macOS IPSW before running source commands:

git clone https://github.com/jwmossmoz/trybox.git
cd trybox
brew install go hashicorp/tap/packer cirruslabs/cli/tart
go install ./cmd/trybox

# Requires packer, tart, and curl on PATH.
ci/build-local-macos-image.sh --target macos15-arm64 --replace

cd ~/src/project
TRYBOX_TARGET=macos15-arm64 trybox run -- sw_vers

The image build creates trybox-macos15-arm64-image, verifies the Packer template phases, and leaves an SSH-ready image that future trybox run commands clone into checkout-bound VMs.

When working inside this repository, reinstall local code changes with:

go install ./cmd/trybox

Use Homebrew's HEAD install when you want to track the public main branch instead of your local checkout:

brew uninstall jwmossmoz/tap/trybox
brew install --HEAD jwmossmoz/tap/trybox

Use trybox bootstrap when you want to prefetch or refresh the seed-based target image explicitly:

trybox bootstrap
trybox bootstrap --replace

After A Run

Useful follow-ups:

trybox logs                 # reprint the latest run log
trybox history              # list recent runs
trybox events <run-id>      # inspect run events
trybox status               # show the selected VM
trybox destroy              # delete the selected VM and start fresh next time

Desktop Access

Open the VM with Tart's native window:

trybox view

Launch Tart's experimental VNC display and print the reconnect URL:

trybox view --vnc
trybox view --vnc --json

trybox view --vnc starts Tart with its experimental VNC display, lets Tart open the viewer, and prints the localhost vnc:// endpoint for reconnects. Trybox keeps that VNC display preference for the checkout VM across later trybox run calls until trybox view switches back to Tart native display or trybox destroy removes the VM.

Defaults

Trybox chooses defaults so the normal command stays short:

Setting	Resolution order
Target	--target, then TRYBOX_TARGET, then saved config, then macos15-arm64.
Checkout	Current git checkout.
Resources	--cpu, --memory-mb, --disk-gb, then TRYBOX_CPU, TRYBOX_MEMORY_MB, TRYBOX_DISK_GB, then target defaults.

Passing --target to a VM-backed command records it as the next default target.

Agents

When handing Trybox work to an agent, paste a single quoted prompt like this and replace <command>:

'Use Trybox from the current checkout: verify `trybox doctor`, set `TRYBOX_TARGET=macos15-arm64` if needed, then run `trybox run -- <command>`; Trybox syncs the dirty checkout and records a run ID; report `trybox logs` and `trybox events <run-id> --json`; open `trybox view` or `trybox view --vnc` only if asked.'

Commands

trybox bootstrap [--target name] [--replace] [--json]
trybox destroy [--target name] [--json]
trybox doctor [--target name] [--json]
trybox events <run-id> [--json]
trybox history [--limit n] [--json]
trybox logs [run-id] [--json]
trybox run [--target name] [--destroy-vm] [--cpu n] [--memory-mb n] [--disk-gb n] [--json] -- <command>
trybox status [--target name] [--json]
trybox target list [--json]
trybox version
trybox view [--target name] [--vnc] [--json]

More Detail

• Overview
• Spec
• Source map
• CLI guide
• Architecture
• Image model
• Security model
• Agent instructions
• Trybox agent skill