The README is the quickstart — the fast path to a running sandbox. This guide is the deeper how-to for acq, the entry point. It provides a pluggable-backend architecture supporting two backends — msb (microsandbox, the default) and sbx (Docker Sandboxes) — sharing one neutral kit vocabulary. Install a backend and acq runs the same commands on either one.

acq runs the same commands on either backend; you only choose the backend once (install one, and it auto-detects). Pick the one that fits your environment:

See docs/BACKEND_GUIDE.md for a full comparison. acq auto-detects an installed backend (msb preferred when both are present); persist a choice with acq backend set <sbx|msb> or acq doctor.

msb is the default backend. The steps below walk the msb path (what acq uses by default). If you specifically want the sbx backend, see Prerequisites (sbx) and Running on the sbx backend. The common commands, secrets, and rotation subsections apply to either backend.

Complete the standard setup in README.md:

• Install the msb CLI: brew install GSA-TTS/tap/microsandbox-acq, or ./scripts/verify-msb-pin --install. Not the upstream one-liner: it always installs the newest release, and acq refuses msb 0.7.0-0.7.2 (ADR-0032)
• Run msb doctor (add --fix to set up KVM/HVF/WHP virtualization)
• Set your network policy

Re-run msb doctor once more after setup — a clean doctor pass is the quickest way to confirm the host is ready before your first acq run (and, if an established setup later starts failing every outbound call at once, a wipe + reinstall then msb doctor is the first thing to try; see Troubleshooting).

You do not need to gather a USAi key or GitHub token in advance — acq prompts you for the USAi key on first run and offers to scope a GitHub token when your workspace has GitHub repos. Set them ahead of time only when pre-seeding a machine or scripting setup (see Secrets below).

To use the sbx backend instead:

• Install the sbx CLI (>= 0.39.0)
• Run sbx login
• Set your network policy

See Running on the sbx backend for the full sbx walkthrough.

./acq run opencode /path/to/your/project

/path/to/your/project is the folder the agent works in — an existing project or a new, empty folder you just created. If it's a software project, run git init . in it first so the agent can track its changes.

That's it. acq run creates the sandbox if it doesn't exist, heals any missing kits, validates your USAi key, and attaches the agent.

Setting secrets up front is optional — acq run validates your USAi key and prompts you to set or rotate it when it's missing or expired, and offers to scope a GitHub token when your workspace has GitHub repos. Set them explicitly when you want to pre-seed a machine, script setup, or run in CI:

# USAi key — global (available to all sandboxes)
./acq secret set -g usai

# USAi key — scoped to one sandbox only (safe for testing)
./acq secret set my-sandbox usai

# GitHub token — global
./acq secret set -g github

# Arbitrary custom endpoint — global
./acq secret set -g myservice --host api.example.com --env MY_API_KEY

acq injects secrets into the sandbox at runtime; the real values never enter the guest.

./acq github-scope <sandbox-name> /path/to/your/project

USAi API keys expire every 7 days, which is the most common cause of authentication errors like:

Unauthorized: {"detail":"Not authenticated"}

Rotate on the host without restarting your sandbox. You do not need to tear down or re-attach a running sandbox to swap in a fresh key — run the rotation command from the host and the new value is stored in acq's secret store, ready for the next request:

1. Open https://gsa.usai.gov/console/key-management.

2. Choose Rotate from the Actions menu for your key.

3. Copy the new key using the console copy button (selecting the displayed text by hand can truncate it).

4. With the key in your paste buffer, run:

   ./acq usai-rotate-api-key

   It prompts for the new key, then validates it in a temporary sandbox. Rotation runs through the active backend (msb or sbx), so it works regardless of which backend you use. Source checkouts also carry scripts/rotate-apikey, a thin compatibility shim that forwards to acq usai-rotate-api-key.

acq also validates your key on attach and offers to rotate it then, but the subcommand above is the direct path — no session restart required.

If a rotated key is still rejected, it was likely truncated on copy — see Known Failure Modes §20.

Most users should use the one-line installer in the README quickstart — it auto-selects the best method already on your Mac or Linux host (Homebrew → npm → self-contained download), puts acq on your PATH, and never needs administrator rights. This section covers the manual, developer, and Windows preview paths.

The one-line installer detects Homebrew and npm automatically. To run the direct command yourself:

npm install -g github:GSA-TTS/agentic-coding-quickstart   # if you use Node/npm
brew install GSA-TTS/tap/acq                              # if you use Homebrew

Package-manager installs give you upgrade/uninstall for free.

Windows support is a preview path for Windows 11 hosts using the msb backend. It is installed from the GitHub release zip with PowerShell; npm remains scoped to macOS/Linux until Windows path and secret-storage behavior are fully validated. The preview runs the existing Bash acq implementation through Git Bash. The installer probes Windows Hypervisor Platform and stops when it is not usable, but it does not try to enable Windows features, elevate PowerShell, or reboot the machine.

irm https://github.com/GSA-TTS/agentic-coding-quickstart/releases/download/v4.2.0/install.ps1 | iex

For an inspect-first install:

$AcqVersion = "4.2.0" # x-release-please-version
$BaseUrl = "https://github.com/GSA-TTS/agentic-coding-quickstart/releases/download/v$AcqVersion"
Invoke-WebRequest "$BaseUrl/install.ps1" -OutFile install.ps1
Get-Content .\install.ps1
.\install.ps1 -DryRun
.\install.ps1

Running .\install.ps1 (and the installed acq, via acq.cmd) requires a PowerShell execution policy that permits local scripts. Windows 11 client defaults to Restricted, so those steps fail with PSSecurityException on an otherwise default host; allow local scripts for your user with Set-ExecutionPolicy -Scope CurrentUser RemoteSigned (or use the irm ... | iex one-liner, which is not affected because piped text is not a script file). On a managed device the policy may be set by Group Policy.

If WHP is disabled, stop: enable it from an elevated PowerShell (Enable-WindowsOptionalFeature -Online -FeatureName HypervisorPlatform -All), restart, and re-run the installer. On a managed device, ask your IT administrator to enable "Windows Hypervisor Platform" out of band.

Run these checks from PowerShell on a Windows 11 host with WHP already enabled. The PowerShell path is the supported Windows preview shell; acq.cmd is only a convenience shim. These checks are intentionally manual until the project has a reliable Windows runner with local virtualization available. The first step runs install.ps1 directly, so the shell needs an execution policy that allows local scripts (see the note above) — a default Restricted client fails with PSSecurityException.

# Installer dry run; should print planned actions and make no changes.
.\install.ps1 -DryRun

# After install, acq should resolve from PATH and delegate through Git Bash.
Get-Command acq
acq version

# Confirm msb is installed and the host is ready.
msb --version
msb doctor

# Smoke-test a shell sandbox against a path with spaces.
New-Item -ItemType Directory -Force "$env:TEMP\acq windows smoke" | Out-Null
acq --backend msb run shell "$env:TEMP\acq windows smoke"

If any command fails, capture the full command, output, Windows version, msb --version, and whether the machine is managed by enterprise policy.

This checklist was validated on a Windows 11 host (build 26200): the installer dry-run/help, a real release-zip install (with SHA-256 verification) on a host with no sandbox runtime preinstalled — the installer detected the missing msb, prompted, and installed it via the upstream Windows installer — acq version through acq.cmd, msb --version / msb doctor, and sandbox provisioning all worked. Notes from that validation:

• The launcher and installer resolve Git Bash from Git for Windows' standard install locations and deliberately ignore the WSL interop shim (C:\Windows\System32\bash.exe) that a bare bash.exe PATH lookup often returns. If acq still lands in WSL, run it from a Git Bash terminal or add Git for Windows' bin directory to your PATH.
• The installer checks WHP by probing the WHP API (WHvCreatePartition), the same signal msb uses, rather than the DISM feature flag — the flag can report Disabled on hosts where WHP genuinely works (WSL2/VirtualMachine Platform, VBS, or a virtualized guest). Treat msb doctor as the authoritative readiness check.
• acq run gates on a stored USAi key and validates it against the USAi API before creating a sandbox, so the smoke test's last command and the full first run require GSA network reachability (e.g. the GSA VPN) plus a key (acq secret set -g usai). Off the GSA network, acq run stops at the key gate with a clear message.

If you're comfortable in a terminal and prefer to run acq from a clone:

git clone https://github.com/GSA-TTS/agentic-coding-quickstart.git
cd agentic-coding-quickstart
./acq run opencode ~/my-project

You'll also need the msb sandbox runtime — install it without admin via brew install GSA-TTS/tap/microsandbox-acq, or ./scripts/verify-msb-pin --install if you have no Homebrew. Avoid curl -fsSL https://install.microsandbox.dev | sh: it always installs the newest release, and acq refuses msb 0.7.0-0.7.2 (see §43 of KNOWN_FAILURE_MODES.md).

Running ./acq from the clone? It only works from inside the agentic-coding-quickstart folder (that's where the acq file lives). If you get "no such file ./acq", cd back into that folder first. The one-line installer avoids this entirely by putting acq on your PATH.

After cloning, check out the tag:

git checkout v3.0.0-rc2

Git prints a message about a "detached HEAD" state — that's normal, not an error. It just means you're on a specific snapshot. Run acq as usual; to go back to the latest, run git switch main.

acq resolves the active backend in this priority order:

1. --backend <name> flag (per-invocation override)
2. ACQ_BACKEND environment variable
3. backend: in ~/.config/acq/config.yaml
4. Auto-detect: first installed backend found (msb preferred, then sbx)

Today (1.2.x), two backends ship: msb (default) and sbx. See docs/BACKEND_GUIDE.md for per-backend details. A third backend (ppp — Podman-Plus-Proxy) is deferred.

# Write `backend: msb` (or sbx) to ~/.config/acq/config.yaml
./acq backend set msb
./acq backend set sbx

# Or run doctor and answer the prompt
./acq doctor

./acq --backend sbx run opencode /proj
./acq --backend msb run opencode /proj

# 1. Install msb (microsandbox) and confirm the host is ready.
#    A version-pinned channel, because acq refuses msb 0.7.0-0.7.2 and the
#    upstream one-liner always resolves to the newest release.
brew install GSA-TTS/tap/microsandbox-acq   # or: ./scripts/verify-msb-pin --install
msb doctor          # checks KVM/HVF/WHP; msb doctor --fix to set up

# 2. Provide the USAi key.
#    INTERACTIVE (recommended): skip this line — `acq run` prompts you for the
#    key on first run, or set it once with:  ./acq secret set -g usai
#    (prompts for the value; it never lands in argv or your shell history).
#
#    NON-INTERACTIVE / scripting / CI only: msb binds the key from a host env var
#    at create (the real value never enters the guest). Read it WITHOUT echoing
#    so it does not leak into shell history:
read -rs -p 'USAi API key: ' USAI_API_KEY; export USAI_API_KEY; echo

# 3. Run — acq auto-detects msb, or force it with --backend msb
./acq --backend msb run opencode /path/to/your/project

msb takes native shortcuts where it has a strictly-better primitive — e.g. the Zscaler CA kit uses --trust-host-cas instead of the file-drop mechanism. Kit behavior is otherwise identical across backends.

# 1. Install the sbx CLI (>= 0.39.0) and authenticate
#    (see https://docs.docker.com/ai/sandboxes/ — the standalone sbx CLI,
#     NOT the deprecated `docker sandbox`)
sbx login
sbx policy set <your-network-policy>

# 2. Run — acq uses sbx when it is your only backend or you have existing sbx
#    sandboxes, or force it with --backend sbx
./acq --backend sbx run opencode /path/to/your/project

For sbx-specific detail (proxy secrets, network policy), see the full sbx guide. For the backend-neutral way to mount multiple directories, see Multiple Workspaces.

msb runs each sandbox as a lightweight microVM, so the host must provide hardware virtualization. msb doctor is the authoritative check (and msb doctor --fix attempts supported setup changes); the per-platform requirements below mirror the microsandbox docs:

Linux — a glibc-based distribution with KVM enabled.

# KVM device present?
test -e /dev/kvm && echo ok

# CPU virtualization exposed? (non-zero = vmx/svm present)
grep -Ec '(vmx|svm)' /proc/cpuinfo

A missing /dev/kvm (or a 0 from the second command) means virtualization is disabled in firmware, unavailable on the machine, or hidden by an outer VM. If your user lacks access to the device, add yourself to the kvm group once:

sudo usermod -aG kvm "$USER" && newgrp kvm

macOS — Apple Silicon (M-series). Intel Macs are not supported for the local runtime, and Rosetta does not change that. Nothing to enable ahead of time: Apple Silicon Macs include the hypervisor support msb uses.

Windows 11 — Windows support is in preview. Local sandboxes need the Windows Hypervisor Platform feature (this is separate from the VirtualMachinePlatform feature that WSL2 and Docker Desktop enable). The Windows preview installer probes WHP and stops when it is not usable; it does not elevate PowerShell, enable the feature, or reboot the machine.

Enable WHP yourself from an elevated PowerShell (Enable-WindowsOptionalFeature -Online -FeatureName HypervisorPlatform -All), then restart (see the README box). On a managed device, ask your IT administrator; then re-run the installer or msb doctor.

Inside a cloud VM, CI runner, or another hypervisor — the outer environment must expose nested virtualization before /dev/kvm (or the equivalent) is available to msb. Many hosted CI runners and cloud VMs do not enable it by default.

Kits are authored once in the neutral hybrid/v1 vocabulary and translated to the active backend automatically. Inspect and manage them with:

./acq kit list                    # show the pinned kits + patterns ref
./acq kit validate ./my-kit/      # validate a neutral kit dir or spec.yaml
./acq kit apply my-sandbox KITREF # apply a kit to an existing sandbox

acq pins the built-in kit bundle to one commit of the patterns repo. New sandboxes get the pinned bundle automatically; for an existing sandbox, acq can tell you if it is behind and refresh it in place:

./acq kit check my-sandbox        # is this sandbox on the pinned bundle?
./acq kit update my-sandbox       # refresh the bundle in place (asks first)

acq run also offers a refresh when a sandbox is behind; it defaults to No and never blocks a launch. Refreshes are in place (sessions, secrets, and project files are kept). Skip the automatic check with ACQ_UPDATE_CHECK=0 or ./acq run --no-update-check.

See ADR-0016 for the full design and trust model.

acq configure is a colorful, dependency-free interactive picker for choosing which opt-in kits to enable and the default answer for per-sandbox GitHub token scoping. Choices persist to ~/.config/acq/config.yaml.

acq configure

• The four built-in kits are always applied; the picker only manages opt-in extras (e.g. openchamber, paseo).
• acq offers to run this on your first run; run it again anytime.
• acq create re-shows the picker pre-filled with your saved defaults, so one sandbox can deviate without changing the global default (the deviation is remembered per-sandbox and re-applied on resume).
• The token preference only pre-answers the scoping prompt — the fine-grained PAT is still minted per-sandbox (acq github-scope).
• Non-interactive/CI runs make no changes and just print the current config; set ACQ_NO_PROMPT=1 to force that. See ADR-0031.

# Apply an extra kit on every invocation
export ACQ_EXTRA_KITS="./my-local-kit git+https://github.com/acme/kits.git#ref=<sha>&dir=some-kit"

# Allow a new kit source prefix
export ACQ_EXTRA_KIT_SOURCES="github.com/acme/"

An exported ACQ_EXTRA_KITS takes precedence over the kits saved by acq configure (env wins): the create-time picker is skipped and your env value is used verbatim.

You can also apply an extra kit for a single run/create with --kit (repeatable), instead of the env var:

# One-off: apply a local kit dir (or a git+https ref)
acq run opencode --kit ./my-local-kit .
acq create opencode --kit ./kit-a --kit git+https://github.com/acme/kits.git#ref=<sha>&dir=some-kit /proj

--kit refs are translated by acq exactly like ACQ_EXTRA_KITS entries (a neutral hybrid/v1 kit is converted to the active backend's format), so they work with any backend — they are not forwarded raw to the backend CLI.

New sandboxes include the USAi provider kit by default, unchanged from earlier releases. To create one without any provider kit, pass --no-provider-kits to run or create before --. This is authoritative, so acq does not require or bind a USAi credential and projects an empty provider generation for the guest. The choice is recorded with the sandbox and remains in effect when its kits are healed or it is resumed.

acq run opencode --no-provider-kits /path/to/project
acq create shell --no-provider-kits /path/to/project

For scripted selection, ACQ_PROVIDER_KITS accepts a whitespace-separated list of kit refs, following the same format as ACQ_EXTRA_KITS. ACQ_PROVIDER_KITS='' also selects the empty set, but --no-provider-kits is the portable form when configuration layers cannot preserve an empty environment value.

A provider kit is data. Once the pinned validation pipeline accepts it, its facts.json names everything acq needs: providerId, keyEnv, host, modelsUrl, and apiProtocol. That means a provider kit from your own repository works without touching the pinned Patterns release:

acq create opencode --kit 'git+https://github.com/acme/kits.git#ref=<sha>&dir=acme-ai' /path/to/project

acq owns the provider → credential registry that the validator checks the kit against, so declare where the key comes from and acq does the rest. The registry is merged in this order (highest precedence last):

1. the pinned Patterns provider-credential-bindings.json — the trust anchor;
2. provider_credential_bindings: in ~/.config/acq/config.yaml — durable;
3. ACQ_PROVIDER_CREDENTIAL_BINDINGS — one invocation only.

A layer entry is providerId=KEY_ENV or providerId=KEY_ENV@host[,host].

# Durable: pin a provider to a credential env var AND the host it may use
acq provider-credential set opencode-go OPENCODE_GO_API_KEY \
  --host models.opencode-go.example
acq provider-credential ls
acq provider-credential rm opencode-go

# Per-invocation override (whitespace-separated entries)
ACQ_PROVIDER_CREDENTIAL_BINDINGS='opencode-go=OPENCODE_GO_API_KEY@models.opencode-go.example' \
  acq run opencode /path/to/project

The host is the trust decision, and it is required. A kit can claim any providerId and allow-list any host, so acq sends your stored credential only to hosts you pinned. --host is therefore mandatory for set, and an unpinned provider — or a kit whose facts.host is not the pinned (or previously recorded) host for that providerId — fails closed rather than quietly moving your credential to a new destination. Changing hosts is an explicit re-pin, never a silent overwrite.

providerId must match ^[a-z0-9]([a-z0-9-]{0,30}[a-z0-9])?$, KEY_ENV must be an upper-case env var name (^[A-Z][A-Z0-9_]*$), and hosts must be bare DNS names. Built-in credential names (USAI_API_KEY, GITHUB_TOKEN, GH_TOKEN, GITLAB_TOKEN) and process-critical names (PATH, IFS, HOME, LD_PRELOAD, …) are refused. A malformed entry fails closed before the validator runs.

The key itself never goes in the registry; it lives in the acq secret store:

acq secret set -g opencode-go     # prompts for the value (never on argv)

From there the injection is generic — no provider-specific acq code:

• at create, the selected generation's facts.json is the facts source (the same data usai gets from provider-facts/usai.env), the registry decides the ENV var, and the credential is bound as KEY_ENV@host by both backends (sbx custom secret; msb --secret ENV@HOST). A value exported by CI is bindable on msb; on sbx, which snapshots its own proxy table, acq fails closed and tells you to store it;
• the binding (providerId, keyEnv, host, modelsUrl) is recorded in the sandbox's host config, so resume/heal re-injects it without re-prompting, and a later host change is caught and refused;
• on attach, acq probes facts.modelsUrl with Authorization: Bearer $KEY_ENV (check_provider_key) and fails closed on a rejected key (401/403) or a redirect; 429/5xx are treated as transient and do not block the attach. USAi is not special-cased: it is the default provider kit (provider_kit: agentic-coding-patterns/usai-provider) and its (USAI_API_KEY, api.gsa.usai.gov) pair is the shipped trust anchor, so it is gated, bound, and validated like any other provider. A rejected USAi key points at acq usai-rotate-api-key, the one remaining provider-specific verb (it needs the USAi key-management console); there is no interactive rotation prompt.

If a provider kit is selected but no credential is available, the create fails closed (non-interactive) or offers to store one (interactive), showing the destination host in the prompt.

acq fetches kits only from trusted sources, recorded as data in ~/.config/acq/config.yaml:

acq kit-source add github.com/acme/kits --ref <sha>   # trust a repo at a pinned commit
acq kit-source ls                                    # sources + the provider kits they publish
acq kit-source rm github.com/acme/kits

The shipped default is github.com/GSA-TTS/agentic-coding-patterns pinned to the release acq was built against, so a fresh install needs no configuration. ACQ_KIT_SOURCES overrides the list for one invocation (whitespace-separated host/owner/repo[@ref][|dir] entries); ACQ_EXTRA_KIT_SOURCES still adds owner-wide allowlist prefixes for backward compatibility.

Trust granularity. Trust is recorded and checked per repository (host/owner/repo): trusting github.com/acme/trusted does not authorize github.com/acme/other. The one place a coarser unit appears is a backend that can only allowlist by prefix: sbx kit.allowedSources is owner-granular (host/owner/), so the prefix handed to sbx is derived from the registry. acq therefore re-checks the repository itself before it acts on a durable provider_kit: ref. ACQ_EXTRA_KIT_SOURCES is the only owner-wide grant, and it is explicit.

Trust is narrow: a trusted source may be fetched from, and may contribute provider kits. It does not extend to the validation control plane — the provider-input validator and its schemas stay pinned to the Patterns release, so a new source can ship kits but cannot redefine what a valid kit is. Because the pinned release is the control plane, it stays resolvable even when the registry is overridden for a run.

acq kit-source ls also auto-lists the provider kits each source publishes (by scanning for */provider-input.json). Discovery is best-effort: an unreachable source simply lists nothing.

What the registry does and does not gate. The registry governs the sources acq resolves on your behalf — the trusted-source allowlist handed to the backend (sbx kit.allowedSources, updated on add and revoked on rm) and provider_kit: entries written in config.yaml, which must name a trusted repository exactly (or an already-trusted remote ref to one). A literal ref you supply on this invocation (--kit git+https://…, ACQ_PROVIDER_KITS, ACQ_EXTRA_KITS) is trusted by you, not by the registry: acq fetches it as given. Local paths are always used verbatim. In short: the registry is the durable-trust boundary, not a sandbox for refs you type.

Removing a source (kit-source rm) fails closed. acq first recomputes what the backend allowlist should be from the sources that remain (plus any explicit ACQ_EXTRA_KIT_SOURCES), so removing one repository never revokes an owner prefix another trusted repository still needs. If the backend allowlist cannot be read, written, or verified (for example jq or sbx is missing, or sbx settings set fails), the command exits non-zero, leaves the source registered, and prints the exact sbx settings set kit.allowedSources … recovery command. Fix the cause (or apply the printed command) and re-run acq kit-source rm; it is safe to repeat.

The provider kit acq uses by default is likewise data:

provider_kit: agentic-coding-patterns/usai-provider   # default
# or: agentic-coding-kits/opencode-go-provider
# or: opencode-go-provider@github.com/mogul/agentic-coding-kits

acq configure offers the discovered kits in a picker, so you can select one without hand-writing a git+https ref. Per-run selection is still ACQ_PROVIDER_KITS / --no-provider-kits.

During the long, quiet phases of acq run (booting the microVM, installing the agent, fetching/applying kits), acq prints status lines and — on an interactive terminal — an animated spinner, so you can tell work is happening.

• Interactive terminal: spinner + status lines.
• Piped / redirected / CI: plain status lines only (no animation), so logs stay clean.
• ACQ_NO_PROGRESS=1 — never animate; still print the plain status lines.
• ACQ_DEBUG=1 — disables the spinner in favor of a timestamped trace.

Progress output goes to stderr, so a piped stdout stays uncluttered.

The default timeout for waiting for the backend's exec (sbx exec / msb exec, via acq exec) to become ready after a sandbox starts is 60 seconds. Override:

export ACQ_EXEC_READY_TIMEOUT=120

• docs/BACKEND_GUIDE.md — per-backend strengths and tradeoffs
• docs/howto/msb.md — detailed msb (microsandbox) reference (the default backend)
• docs/howto/sbx.md — detailed sbx CLI reference
• docs/adr/0010-acq-pluggable-backends.md — architecture decision
• docs/KNOWN_FAILURE_MODES.md — troubleshooting