Workspace file tools can inspect and change project files through XCB’s broker. Tests and builds use a separate, explicitly provisioned Linux VM. Commands run against a staged copy of the project, without host mounts, provider credentials, or network access.
Set up the command runner
On macOS ARM64, install Lima 2.2 or later at /opt/homebrew/bin/limactl and Python 3. Use the source checkout matching your installed native CLI. The dedicated VM uses an 8 GiB sparse disk, 3 GiB memory, and two CPUs. Setup also enforces an 8 GiB host free-space floor plus provisioning capacity.
Run from that XCB checkout. Where the HRA host scheduler is installed, use the scheduler-wrapped setup command in the command-runner contract.
/usr/bin/python3 scripts/setup-command-runner.py \
--root "$HOME/.local/share/xcb-command" --source "$PWD"Setup installs the fixed Linux toolchains and runs the required boundary suite before admitting the backend. It includes Rust 1.97.1, Node 24.18.1, and Bun 1.3.14. When setup succeeds, ask XCB to run your project’s checks.
Prepare public dependencies
Ordinary commands are offline. Host node_modules, Cargo outputs, and package-manager credentials are not copied into the VM. For a cold project, first inspect a dependency plan from the same checkout:
/usr/bin/python3 -I scripts/prepare-command-dependencies.py \
--root "$HOME/.local/share/xcb-command" \
--workspace /absolute/path/to/project --dry-runAfter reviewing the plan, replace --dry-run with --prepare. Use the installed host scheduler where available, as shown in the full preparation guide.
Preparation accepts root Cargo.toml + Cargo.lock, package.json + bun.lock, or both. It fetches checksum-bound public dependencies into an immutable cache. Private registries and install scripts are not supported. Changed manifests or lockfiles require a new preparation; a nested project with its own lockfile needs its own workspace.
Know the boundary
- Commands run on Linux, offline. Native macOS, Xcode, Simulator, and arbitrary network commands are unavailable.
- Each command has up to 10 minutes, 2 GiB scratch space, and 1.5 GiB worker memory.
- Input snapshots are limited to 64 MiB and 8,192 visited entries. Conventional secret paths and dependency/build directories are excluded; this is not a general secret scanner.
- Git supports filtered, read-only status and diffs. Original history, remotes, hooks, commits, and pushes are unavailable.
- Successful changes are revision-checked before publication. Each file replacement is atomic; the entire batch is not a transaction.
Read the full command-runner contract for snapshot, output, publication, and cache limits.
Cancel and recover
Cancel in the terminal that owns the turn. For a headless run, Ctrl-C or SIGTERM requests cleanup. XCB must prove the owned processes have stopped before releasing the account; another terminal can view a session without owning its cancellation.
xcb recover
xcb recover <run-id> --yesInspect the retained run before using --yes. Recovery requires the original host owner to be gone and independently checks pending command receipts. It never publishes staged edits. Do not delete lock files or infer recovery from an elapsed timeout or missing PID.
For an interrupted dependency preparation, inspect its exact cache key:
/usr/bin/python3 -I scripts/prepare-command-dependencies.py \
--root "$HOME/.local/share/xcb-command" \
--status --cache-key CACHE_KEY_FROM_PLANReplace --status with --recover to stop, join, and reconcile that attempt without starting another download.
After a backend change or VM restart
Admission binds the VM’s boot identity and exact tool bytes. Stop active commands and repeat setup with --refresh when fresh admission is required. Keep the backend and installed CLI matched, and restart open terminals after replacing XCB. Refresh does not clear an unsettled job; resolve that job through recovery first.