Skip to content

spec.md

Latest commit

 

History

History
157 lines (122 loc) · 4.86 KB

spec.md

File metadata and controls

157 lines (122 loc) · 4.86 KB
Raw

Trybox Spec

Read this when changing Trybox's product scope, command surface, docs, or package structure.

Trybox warms a clean local macOS VM, syncs the dirty checkout, runs exactly the command the user passed, and keeps durable evidence.

Product Contract

  • Target: a local OS/version/architecture shape, such as macos15-arm64.
  • Target image: a reusable SSH-ready local template image for a target.
  • VM: one checkout-bound clone of the target image.
  • Run: one command execution inside the guest checkout, with logs and events.

The main user workflow is:

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

Trybox owns VM lifecycle, source sync, command execution, and retained evidence. The source repository owns its build system, runtimes, services, fixtures, secrets, and the command being run.

Current Scope

  • Go CLI entrypoint at cmd/trybox.
  • Local state under ~/.trybox.
  • Tart-backed macOS targets on Apple Silicon hosts.
  • Built-in target names for macOS families that Trybox can map to local template images.
  • Checkout-bound VMs keyed by current checkout path and target.
  • Manifest-based sync for tracked files, repository metadata, and nonignored local files.
  • Automatic sync before every run, with fingerprint skip when nothing changed.
  • Durable run metadata, stdout/stderr/combined logs, and event streams.
  • Human output by default and JSON output for agent workflows.
  • Desktop access through trybox view and explicit Tart VNC mode through trybox view --vnc.
  • trybox view --vnc persists Tart VNC as the checkout VM's preferred display for later runs until trybox view or trybox destroy changes the VM state.
  • Local template build script at ci/build-local-macos-image.sh for maintainer-owned macOS images.

Product Alignment

Trybox should keep the small, direct shape that makes the tool easy to reason about:

  • one-line promise;
  • short install and quickstart;
  • one command for the normal run path;
  • dirty-checkout sync rather than clean-checkout ceremony;
  • stable run IDs, logs, and events;
  • source-backed docs through a source map;
  • agent skill focused on operating the tool, not implementing it.

Trybox should not grow into a cloud control plane. There is no hosted broker, provider matrix, auth flow, cost model, warm lease fleet, portal, or remote secrets story in the current Trybox scope.

Supported Local Setup

Quick smoke path:

brew install jwmossmoz/tap/trybox
trybox bootstrap
trybox doctor
cd ~/src/project
trybox run -- ./build-or-test-command

The tap install provides the released trybox binary, cirruslabs/cli/tart, and hashicorp/tap/packer. It does not install Go; source builds need Go separately.

Development tap path:

brew install --HEAD jwmossmoz/tap/trybox

The HEAD formula builds from the public main branch and adds Go as a build-only dependency for that path.

Maintainer template path:

cd /path/to/trybox
brew install go hashicorp/tap/packer cirruslabs/cli/tart
go install ./cmd/trybox
ci/build-local-macos-image.sh --target macos15-arm64 --replace

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

trybox bootstrap remains the explicit seed-image prefetch/repair path. The local Packer template build is the path for validating Trybox-owned macOS target images before relying on them.

CLI Surface

Keep the command surface small until a real workflow needs more:

trybox run -- <command>
trybox logs [run-id]
trybox events <run-id>
trybox history
trybox status
trybox view [--vnc]
trybox destroy
trybox doctor
trybox target list
trybox bootstrap [--replace]

trybox run must continue to run exactly the argv after --. It must not infer project setup, launch apps implicitly, forward host secrets, or mutate the source checkout outside the guest sync target.

Go Structure

  • cmd/trybox: binary entrypoint only.
  • internal/cli: command routing, flags, output formats, run coordination, and user-facing behavior.
  • internal/targets: target catalog and defaults.
  • internal/backend: VM backend interface and Tart implementation.
  • internal/workspace: source manifest construction.
  • internal/state: ~/.trybox config, workspace records, run logs, events, and locks.
  • internal/sshx: SSH helpers.

Add packages only when they create a real boundary. Prefer keeping command behavior close to the file that owns the command.

Deferred

These are not part of the tightened first product loop:

  • cloud providers or a broker;
  • Windows or Linux backends;
  • command sandboxing as a main execution mode;
  • automatic project runtime setup;
  • repo-local job files;
  • artifact publishing, screenshots, or recordings;
  • secret forwarding;
  • remote portals or cost accounting.

Future work should graduate from this list only after the macOS local VM loop, template build, quickstart, docs, and agent workflow stay boring.