Skip to content

CONCEPTS.md

Latest commit

 

History

History
206 lines (159 loc) · 8.46 KB

CONCEPTS.md

File metadata and controls

206 lines (159 loc) · 8.46 KB
Raw
title acq Concepts
description Backend-neutral concepts for working with acq sandboxes (workspaces, mounts)
status canonical
tier 2
last_updated 2026-08-21
audience developers
keywords
acq
concepts
workspace
mount
backend-neutral
sbx
msb
related_files
docs/howto/acq.md
docs/BACKEND_GUIDE.md
docs/adr/0010-acq-pluggable-backends.md
docs/adr/0011-msb-backend-and-neutral-kits.md
load_priority on-demand
review_cycle quarterly

acq Concepts

Cross-cutting concepts for working with acq sandboxes. These apply to both backends (sbx and msb) because acq presents one neutral interface over both. For per-backend strengths, tradeoffs, and caveats, see the Backend Guide.

Multiple Workspaces

You can mount additional directories alongside the primary workspace when creating a sandbox. This is useful when you need to reference multiple repos or folders from one sandbox session — for example, editing an app while reading a reference library or the playbook.

acq supports the multi-workspace positional list on both backends with identical syntax, so this is the canonical, backend-neutral way to mount extra directories.

Syntax

acq run <agent> <primary-workspace> [extra-workspace][:ro] ...
# e.g.
acq run opencode ~/projects/app ~/projects/lib:ro
  • Primary workspace — the first path. The agent starts here, and it is mounted read/write.
  • Extra workspaces — additional paths the agent can access. Each mounts at its absolute host path inside the sandbox (e.g. ~/projects/lib appears at /Users/you/projects/lib), matching across backends.
  • :ro suffix — mounts that extra workspace read-only. Recommended for reference repos so the agent cannot modify them.
  • Mounts are fixed at creation — you cannot add or remove workspaces from an existing sandbox. To change mounts, remove the sandbox (acq rm <name>) and recreate it with the new paths.

The same positional list works with acq create when you want to name a sandbox without attaching immediately:

acq create <agent> <primary-workspace> [extra-workspace][:ro] ...

Example: app repo + read-only reference

# Primary: your app (read/write)
# Secondary: the playbook, read-only reference
acq run opencode ~/projects/my-app ~/projects/agentic-coding-playbook:ro

The agent can edit ~/projects/my-app and read from ~/projects/agentic-coding-playbook without risk of modifying the reference content.

Security recommendation

Prefer read-only (:ro) mounts for secondary workspaces unless the agent genuinely needs write access. This limits accidental modification and reduces the blast radius of agent errors.

Warning

Mounted directories expose all content to the agent, including .env files, .git/config (which may contain tokens), and any secrets in the mounted path. Mount only what the agent needs. Prefer selective, targeted mounts over mounting parent or home directories.

Backend caveats

The syntax and semantics above are identical across backends, but each backend has a few mechanics worth knowing. Rather than duplicate them here, see the Backend Guide for:

  • msb — each host workspace path must already exist (msb does not create the host mount path), and symlinked host paths (notably macOS $TMPDIR) are canonicalized to their real path before mounting.
  • sbx — the --clone remote-clone lifecycle interacts with multi-workspace mounts; see the sbx how-to guide for the sbx-specific clone story.

How It Works

This explains the mechanics behind the README quickstart — read it when you want to customize or troubleshoot.

What happened when you ran the acq command?

acq run created the sandbox for that path (if it didn't exist yet) and mounted your project into it. Then it configured the coding agent (opencode) to pick up configuration for using the USAi provider and made sure the agent was provisioned with custom guidance and relevant skills for working in the federal context — all delivered by kits fetched from the pinned patterns release, not from the quickstart clone.

What acq applies

acq applies its built-in mixin kits (by pinned remote reference from the community agentic-coding-patterns repo) when it creates a sandbox:

  • usai-provider — stages the USAi config at ~/usai-config/opencode.jsonc and, at startup, merges it into OpenCode's global config at ~/.config/opencode/opencode.jsonc (allow-listing USAi egress). It composes with, rather than clobbers, any existing global config.
  • agentic-coding-playbook — installs the playbook at startup into ~/.agentic-coding-playbook (a pinned REST tarball on patterns v1.8.0+; older bundles cloned it) and symlinks its AGENTS.md into each agent's rules path and its skills into ~/.agents/skills (+ per-agent roots).
  • zscaler-ca-certificate — installs the public Zscaler Root CA into the sandbox trust store (harmless if Zscaler isn't in use).
  • git-ssh-sign — signs git commits and tags with the SSH key forwarded from your host's SSH agent; the private key never enters the sandbox. Load a key on the host first (ssh-add ~/.ssh/id_ed25519) — without one, commits fail with a clear error, and acq warns you before attaching. Signing alone does not make a commit GitHub-Verified; see Commits show "Unverified" on GitHub.

How the USAi key is injected

acq stores the USAi API key in its own secret store (./acq secret set -g usai) with an explicit associated endpoint (api.gsa.usai.gov) and injects it into requests at runtime — the real value stays out of the guest.

Key pre-validation

Before attaching, acq checks that the sandbox's USAi key works. If none is set yet, or it has expired, acq prompts you to paste a key (or rotate it — see Rotate your USAi key) and re-validates before launching the agent.

How default USAi models are chosen

The usai-provider kit ships an opencode.jsonc with a generated USAi model catalog, kept in sync with the USAi /models API so new projects start from a current baseline. See the kit definition in the agentic-coding-patterns repository for details.

Customizing your setup

acq applies a fixed set of built-in kits, pinned to a commit of the patterns repo. To customize:

  • Add your own kits on every run: see Advanced: extra kits.
  • Change USAi models / provider config, rules, or skills: contribute to the kits in the agentic-coding-patterns repo (integrations/isolation/acq-kits/), where each kit and its design notes live.
  • Adopt newer kit versions: bump PATTERNS_KIT_REF near the top of acq.backends/common.sh.

Advanced: extra kits

acq always applies its built-in kits. To apply additional kits on every invocation without repeating --kit flags, set ACQ_EXTRA_KITS to a whitespace-separated list of kit references (local paths or remote refs):

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

Extras are applied after the built-in kits (so they win on any overlapping config). They also work when re-running against an existing sandbox: adding a new entry and re-running acq run <existing-sandbox> injects just the new kit.

If an extra kit is hosted somewhere other than github.com/GSA-TTS/, add its scheme-less prefix so acq allowlists it:

export ACQ_EXTRA_KIT_SOURCES="github.com/acme/"

Optional Integrations

  • Web UI — The OpenCode text UI is functional but constraining. By running the Paseo kit, you can interact with sandboxed agents via a feature-rich web UI that includes clipboard support and richer markdown rendering. Use the paseo acq kit, then open http://localhost:6767 in your browser.
  • Editor integrations — Editor task configs and setup guides live in the community agentic-coding-patterns repo under integrations/. (For example, the Zed editor integration is at integrations/editors/zed/.)