Skip to content

Commit 83e202f

Browse files
mogulOpenCode AgentOpenCode Agent
authored
feat(acq-kits): add OpenDesign browser kit (#438)
## Summary Adds an opt-in `opendesign` ACQ kit that runs OpenDesign headlessly inside the sandbox as a browser-accessible design workspace. The kit reuses the existing sandbox OpenCode CLI and keeps model credentials on the ACQ/OpenCode path, especially when composed with `usai-provider`. ## Content Type - [ ] Skill - [ ] Prompt - [ ] Workflow - [ ] Agent instructions - [ ] Lesson learned - [x] Integration / ACQ kit ## What Changed - Added `integrations/isolation/acq-kits/opendesign/` with `hybrid/v1` spec, installer, supervisor, verifier, README, troubleshooting, and design records. - Pins OpenDesign to `open-design-v0.24.0` and verifies commit `0d3a14c1df6dc5017f3cc3ef05b24558250c220b`. - Installs kit-managed Node `24.21.0` with SHA-256 verification and pnpm `10.33.2`. - Runs OpenDesign on guest port `7456` and publishes it via neutral `publishedPorts`. - Adds a `10G` persistent volume for OpenDesign source/state/tooling under `/home/agent/.local/share/opendesign`. - Seeds OpenDesign app config for `agentId: "opencode"`, `onboardingCompleted: true`, and local telemetry disabled. - Does not seed a default model. - Does not copy `USAI_API_KEY` or any provider key into OpenDesign state. - Registers the kit in `kits.yaml` and the ACQ kits README. ## Safety Checklist - [x] No secrets, tokens, credentials, or private keys - [x] No PII, CUI, customer data, or sensitive info - [x] No internal URLs or system details - [x] Examples use placeholders - [x] Credentials remain with ACQ/OpenCode, not persisted by the kit ## Security Impact This adds a local browser daemon to the sandbox attack surface. - OpenDesign binds `0.0.0.0:7456` inside the guest so ACQ/MSB create-time port publishing can reach it. - The host side is expected to be loopback-only through ACQ port publishing. - `OD_DISABLE_API_AUTH=1` is intentional for this trusted, single-user ACQ browser kit posture, matching the approved direction during implementation. - Documentation explicitly warns not to forward the mapped port or use it on an untrusted multi-user host. - Live verification now checks both in-guest daemon/UI health and host-loopback reachability. ## Adversarial Review Follow-Up A sub-agent adversarial review flagged these issues and they were addressed: - Pinned pnpm store to the OpenDesign persistent volume. - Replaced recursive startup `chown -R` with shallow ownership initialization. - Made verifier output explicit about skipped schema validation. - Strengthened live credential check to look for the injected secret value, not just the variable name. - Kept auth-disabled posture as an intentional accepted risk documented in README and ADR. ## Verification Local verification run in this agent sandbox: ```text integrations/isolation/acq-kits/opendesign/scripts/verify Result: 15 passed, 0 failed, 1 skipped Note: schema validator skipped here because this sandbox lacks jsonschema/pyyaml. ``` ```text bash -n integrations/isolation/acq-kits/opendesign/scripts/verify sh -n integrations/isolation/acq-kits/opendesign/files/home/opendesign-install.sh sh -n integrations/isolation/acq-kits/opendesign/files/home/opendesign-start.sh git diff --check Result: passed ``` Host verification performed by maintainer during development: ```text python integrations/isolation/acq-kits/validate-kits.py --strict Result: all 8 acq-kits valid, including opendesign ``` ```text integrations/isolation/acq-kits/opendesign/scripts/verify Result: 13 passed, 0 failed before later verifier hardening ``` ```text KEEP=1 RUN_ACQ=1 READY_TIMEOUT=1200 integrations/isolation/acq-kits/opendesign/scripts/verify Observed: - volume ownership corrected to agent:agent - OpenDesign source install completed - Next/OpenDesign web build completed after increasing Node heap - daemon/UI reachable inside sandbox - OpenCode present on PATH - app-config seeded correctly: {"agentId":"opencode","onboardingCompleted":true,"telemetry":{"metrics":false,"content":false,"artifactManifest":false}} - guest port 7456 reported as mapped by `acq ports` ``` Residual host-side follow-up: ```text A browser attempt against http://127.0.0.1:7456 initially returned ERR_CONNECTION_REFUSED despite `acq ports` reporting a mapping. The verifier was updated to curl the reported host-loopback URL so this cannot be missed in the next live run. ``` ## Rollback Remove `integrations/isolation/acq-kits/opendesign/` and delete the `opendesign` entries from `integrations/isolation/acq-kits/kits.yaml` and `integrations/isolation/acq-kits/README.md`. ## AI Assistance This PR was developed with AI assistance from OpenCode. --------- Co-authored-by: OpenCode Agent <[email protected]> Co-authored-by: OpenCode Agent <[email protected]>
1 parent c3a6dac commit 83e202f

19 files changed

Lines changed: 2137 additions & 31 deletions

‎.github/linters/package-lock.json‎

Lines changed: 3 additions & 3 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎.github/linters/package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@
99
"overrides": {
1010
"js-yaml": "4.3.2",
1111
"katex": "0.18.2",
12+
"markdown-it": "14.3.3",
1213
"smol-toml": "1.9.0"
1314
}
1415
}

‎integrations/isolation/acq-kits/README.md‎

Lines changed: 9 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ not agent behavior. (Behavioral patterns live in `skills/`, `prompts/`, etc.)
2525
| [`openchamber/`](openchamber/) | Run OpenChamber, a browser UI for OpenCode, inside the sandbox alongside the terminal TUI. Opt-in (see its parity note). |
2626
| [`opencode/`](opencode/) | Install the OpenCode v2 terminal AI coding agent from pinned, SHA-256-verified npm platform tarballs. Agent-harness kit; no ports. |
2727
| [`paseo/`](paseo/) | Self-host the [Paseo](https://github.com/getpaseo/paseo) daemon + browser web UI (for coding agents) inside the sandbox on one port. Opt-in; agent-generic wrapper, no shared TUI session. |
28+
| [`opendesign/`](opendesign/) | Run [OpenDesign](https://github.com/nexu-io/open-design) headlessly inside the sandbox as a browser design workspace, reusing the existing OpenCode CLI and ACQ-injected USAi credentials. Opt-in. |
2829
| [`prime-agent/`](prime-agent/) | Install [PrimeIntellect-ai/prime-agent](https://github.com/PrimeIntellect-ai/prime-agent), a terminal AI coding assistant with an embedded IPython tool. Opt-in; TUI, no ports. |
2930
| [`pi-coding-agent/`](pi-coding-agent/) | Install [earendil-works/pi](https://github.com/earendil-works/pi) (`@earendil-works/pi-coding-agent`), a plain terminal AI coding agent (read/write/edit/bash tools only). Opt-in; TUI, no ports. |
3031

@@ -124,13 +125,14 @@ degrades the verdict to `3`; `skip` is *not applicable in this configuration*
124125
it; `warn` is advisory.
125126

126127
**Unconverted kits** — `agentic-coding-playbook`, `oci-engine`, `opencode`,
127-
`openchamber`, `paseo`, `pi-coding-agent`, `zscaler-ca-certificate`. These still
128-
use the older two-state verdict, so nothing above applies to them. A non-zero
129-
exit means a check failed *or* a precondition could not be met — the two are not
130-
distinguished — and a `0` does **not** establish that every check ran: these
131-
scripts report an unmet precondition with a bare message that increments no
132-
counter, then exit `0` on the strength of the checks that did run. Treat a `0`
133-
here as "nothing that ran failed", never as full coverage.
128+
`openchamber`, `opendesign`, `paseo`, `pi-coding-agent`,
129+
`zscaler-ca-certificate`. These still use the older two-state verdict, so nothing
130+
above applies to them. A non-zero exit means a check failed *or* a precondition
131+
could not be met — the two are not distinguished — and a `0` does **not**
132+
establish that every check ran: these scripts report an unmet precondition with a
133+
bare message that increments no counter, then exit `0` on the strength of the
134+
checks that did run. Treat a `0` here as "nothing that ran failed", never as full
135+
coverage.
134136

135137
The authoritative classification is `scripts/tests/test_verify_contract.py`. It
136138
executes the verdict contract for converted kits, asserts each unconverted kit

‎integrations/isolation/acq-kits/kits.yaml‎

Lines changed: 22 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -98,6 +98,26 @@ kits:
9898
ONE port. The daemon runs unsecured (no PASEO_PASSWORD); the sandbox is the
9999
security boundary and the port is host loopback only.
100100
101+
opendesign:
102+
backends: [sbx, msb]
103+
parity: |
104+
Opt-in headless browser design workspace for OpenDesign. Written entirely
105+
in the neutral vocabulary with no backend shortcut or extras: the single
106+
published container port (7456, serving the OpenDesign daemon/API + web UI)
107+
is expressed with the neutral top-level `publishedPorts` list; the 10G
108+
persistent OpenDesign data/source volume is expressed with the neutral
109+
`volumes` list; and the never-exiting startup supervisor is marked with the
110+
neutral `background: true` flag. acq's kit translation maps publishedPorts,
111+
volumes, files, environment, and background startup to the active backend's
112+
native primitives. The kit installs a pinned OpenDesign source checkout with
113+
a kit-managed Node 24 runtime, runs the daemon unsecured
114+
(OD_DISABLE_API_AUTH=1), seeds OpenDesign to use the existing `opencode`
115+
CLI, and leaves model credentials to acq + the usai-provider kit. The
116+
daemon binds guest loopback only and a kit-managed Node relay publishes it
117+
on the guest network address, because OpenDesign gates some routes on a
118+
loopback peer address; that relay is a plain byte forwarder with no
119+
backend-specific assumptions.
120+
101121
oci-engine:
102122
backends: [sbx, msb]
103123
parity: |
@@ -133,8 +153,8 @@ kits:
133153
(prime-agent is a TUI, not a web UI) — unlike openchamber/paseo. SKELETON
134154
only: the three scripts are placeholders; the real install/CA-bundle/
135155
kernel logic and the generated model catalog
136-
(files/home/prime-agent-config/models.json) land in follow-up work tracked
137-
in the patterns repo's prime-agent epic. Model-provider egress is the
156+
(files/home/prime-agent-config/models.json) are intentionally deferred to
157+
follow-up work for the prime-agent kit. Model-provider egress is the
138158
usai-provider kit's job, not this one.
139159
140160
pi-coding-agent:
Lines changed: 230 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,230 @@
1+
# opendesign (acq mixin kit, `hybrid/v1`)
2+
3+
Runs [OpenDesign](https://github.com/nexu-io/open-design) headlessly inside an
4+
`acq` sandbox and publishes its browser UI / daemon to the host. OpenDesign is a
5+
local-first design workspace that launches existing agent CLIs. This kit uses the
6+
existing sandbox `opencode`; it does not install OpenCode and does not own model
7+
credentials.
8+
9+
OpenDesign is exposed on container port **7456**. Internally, the daemon listens
10+
on guest loopback port `17456`, and a small relay publishes it on guest port
11+
`7456` for ACQ port mapping.
12+
13+
This kit is **opt-in** and is designed to compose with the default GSA kits,
14+
especially `usai-provider`.
15+
16+
## Quick start
17+
18+
1. **Set the kit reference** to a full commit SHA of this repo:
19+
20+
```bash
21+
export ACQ_EXTRA_KITS="git+https://github.com/GSA-TTS/agentic-coding-patterns.git#ref=<sha>&dir=integrations/isolation/acq-kits/opendesign"
22+
```
23+
24+
2. **Ensure the USAi key is available through acq** if you want the default GSA
25+
OpenCode provider path:
26+
27+
```bash
28+
acq secret set-custom -g --host api.gsa.usai.gov --env USAI_API_KEY
29+
```
30+
31+
`usai-provider` configures OpenCode to read `{env:USAI_API_KEY}`. This kit
32+
does not copy that key into OpenDesign storage.
33+
34+
3. **Start the sandbox with OpenCode:**
35+
36+
```bash
37+
acq run opencode /path/to/your/project
38+
```
39+
40+
Leave the terminal open. The OpenDesign daemon starts in the background.
41+
42+
4. **Open the browser UI.** Find the mapped host port and open it:
43+
44+
```bash
45+
acq ports <sandbox> # look up the host port mapped to container 7456
46+
```
47+
48+
Open `http://localhost:<host-port-for-7456>`. On first boot, wait for the
49+
source install and build, then reload.
50+
51+
## What the kit provisions
52+
53+
- A pinned OpenDesign source checkout at `open-design-v0.24.0`, verified against
54+
commit `0d3a14c1df6dc5017f3cc3ef05b24558250c220b`.
55+
- A kit-managed Node `24.21.0` runtime under the kit volume, verified by
56+
SHA-256.
57+
- pnpm `10.33.2` through Corepack.
58+
- OpenDesign daemon startup on internal `127.0.0.1:17456` with `--no-open`,
59+
plus a supervised relay that publishes it on guest port `7456` (see
60+
[Security](#security)).
61+
- Root startup initialization that makes the root of the persistent OpenDesign
62+
volume writable by the `agent` user before the daemon supervisor runs.
63+
- OpenDesign state, source checkout, kit-managed Node runtime, Corepack state,
64+
pnpm executables, and pnpm store under `/home/agent/.local/share/opendesign`.
65+
- OpenDesign app-config seeding for `agentId: "opencode"`,
66+
`onboardingCompleted: true`, and local telemetry disabled when no user choice
67+
exists.
68+
- `OPENCODE_CONFIG` pointing at the `usai-provider` OpenCode config, so
69+
OpenDesign-launched runs actually reach USAi (see [Credential
70+
model](#credential-model)).
71+
72+
The kit deliberately does **not** seed a default model. OpenCode/OpenDesign use
73+
their existing configured defaults.
74+
75+
This kit builds OpenDesign from source during first boot. That means it runs
76+
OpenDesign's pinned `pnpm install --frozen-lockfile`, package lifecycle scripts,
77+
bootstrap build, and Next.js production build inside the sandbox as the `agent`
78+
user. The source commit, Node archive, pnpm version, and lockfile are pinned, but
79+
this is still a larger first-boot build surface than sibling kits that install a
80+
single published artifact.
81+
82+
## Credential model
83+
84+
The intended GSA credential path is:
85+
86+
```text
87+
acq secret store
88+
-> sandbox env: USAI_API_KEY
89+
-> usai-provider OpenCode config
90+
-> OpenDesign launches opencode
91+
-> opencode reads USAi from its own config/env
92+
```
93+
94+
Do not paste model-provider keys into chat. For the core OpenCode/USAi flow,
95+
OpenDesign never needs a copy of the provider key in its `OD_DATA_DIR`.
96+
97+
One wrinkle makes an extra step necessary. OpenDesign launches agent children
98+
with `OD_SANDBOX_MODE=1`, which rewrites `HOME` and `XDG_CONFIG_HOME` to a
99+
private agent home under `OD_DATA_DIR`. OpenCode resolves its global config from
100+
those variables, so it would look inside
101+
`$OD_DATA_DIR/sandbox/config/opencode/` — where it auto-creates an empty stub —
102+
and never read the `usai-provider` config. With no `usai` provider defined,
103+
OpenCode falls back to its own hosted gateway (`opencode.ai/zen`), which is not
104+
in this kit's egress allowlist, and every run fails with `Cannot connect to API`
105+
after burning its retry budget.
106+
107+
Startup therefore exports `OPENCODE_CONFIG` (OpenCode's documented absolute-path
108+
override, which survives that rewrite):
109+
110+
```text
111+
OPENCODE_CONFIG=/home/agent/.config/opencode/opencode.jsonc
112+
```
113+
114+
That names a config **path** only. `USAI_API_KEY` stays in the environment and is
115+
resolved by the config's own `{env:USAI_API_KEY}` substitution at run time, so no
116+
key material moves into OpenDesign state. Startup logs which config it selected,
117+
and warns when it finds none.
118+
119+
If you configure extra OpenDesign media providers in the UI, OpenDesign stores
120+
those settings in its own local data directory. Treat that directory as sensitive
121+
local state.
122+
123+
## Reaching it from the host
124+
125+
The kit exposes container port `7456`, declared via neutral `publishedPorts` in
126+
`spec.yaml`. `acq` publishes it to a host loopback port per sandbox. Look up the
127+
mapping:
128+
129+
```bash
130+
acq ports <sandbox>
131+
# OpenDesign UI: open http://localhost:<host-port-for-7456>
132+
```
133+
134+
The automatic create-time mapping is the supported host-browser path. Avoid
135+
adding an extra post-hoc fixed-port publish for this kit: depending on backend
136+
implementation, that may dial guest loopback port `7456` and bypass the relay
137+
split (`7456` -> `17456`) that keeps OpenDesign's peer-loopback-gated routes
138+
working.
139+
140+
## Security
141+
142+
The daemon runs with `OD_DISABLE_API_AUTH=1` and binds guest `127.0.0.1` only.
143+
This is safe only because the sandbox is the security boundary and the host-side
144+
published port is loopback-only.
145+
146+
Run this only on a trusted, single-user host. Do not forward the mapped port to a
147+
wider interface. Anyone who can reach the host loopback port can drive the
148+
OpenDesign daemon and the agents it launches.
149+
150+
`acq` create-time port publishing on msb-style backends dials the sandbox guest
151+
network IP, not guest `127.0.0.1`, so something in the guest must listen there.
152+
The kit does that with a small supervised relay (`~/opendesign-relay.mjs`) that
153+
listens on published guest port `7456` and forwards to the loopback daemon on
154+
internal port `17456` — rather than binding the daemon to `0.0.0.0`. The relay
155+
accepts loopback, the default gateway peer, and optional backend-specific
156+
`OPENDESIGN_RELAY_ALLOWED_PEERS` entries; other guest-network peers are denied
157+
before forwarding. That peer filter is defense-in-depth against accidental guest
158+
network reachability, not the primary security boundary: code running inside the
159+
sandbox is already trusted for this local development posture. Do not rely on the
160+
relay to contain a hostile in-sandbox process, especially on backends where the
161+
guest network is shared across sandboxes.
162+
163+
That distinction matters functionally, not just cosmetically. OpenDesign gates
164+
several routes on the request **peer** address being loopback
165+
(`requireLocalDaemonRequest`). With the daemon on `0.0.0.0`, every request
166+
arriving from the host carries a guest-network peer, and those routes return
167+
`403 Forbidden` while the rest of the UI works — most visibly Settings → About →
168+
**Export diagnostics**, and `POST /api/strategies/od-next/rollout`. The relay
169+
keeps the peer loopback, so they work. Details and the rejected alternatives are
170+
in
171+
[`docs/decisions/disable-api-auth-loopback-boundary.md`](docs/decisions/disable-api-auth-loopback-boundary.md).
172+
173+
## HTTPS-inspected networks
174+
175+
OpenDesign is installed from GitHub, Node.js, and npm. Behind an inspecting
176+
proxy, pair this kit with the `zscaler-ca-certificate` kit so Node/pnpm trust
177+
the inspection CA. The install script appends `PROXY_CA_CERT_B64` only when it
178+
can decode it successfully, then appends the system CA bundle to
179+
`NODE_EXTRA_CA_CERTS` when available.
180+
181+
## Backend support
182+
183+
`acq` selects and abstracts the isolation backend. This kit is written entirely
184+
in neutral `hybrid/v1` vocabulary (`caps`, `files`, `commands`, `publishedPorts`,
185+
`volumes`, and `environment`) and uses no backend-specific shortcuts. See
186+
[`kits.yaml`](../kits.yaml) for the parity summary.
187+
188+
## Validating
189+
190+
```bash
191+
# Offline gate: schema + file paths + registry + kit-specific invariants.
192+
# Needs python3 + jsonschema + pyyaml; run from this kit directory.
193+
./scripts/verify
194+
195+
# Lightweight smoke-only mode if Python deps are unavailable. This is not enough
196+
# for review completion because it skips validate-kits.py --strict.
197+
ALLOW_PARTIAL_VERIFY=1 ./scripts/verify
198+
199+
# Live end-to-end via acq, from a sandbox-capable host.
200+
RUN_ACQ=1 ./scripts/verify
201+
202+
# Keep the sandbox afterward to inspect it.
203+
KEEP=1 RUN_ACQ=1 ./scripts/verify
204+
```
205+
206+
CI for this repo cannot create nested sandboxes, so live verification is a
207+
host-side step before PR review/merge. Treat skipped schema validation as
208+
incomplete unless `ALLOW_PARTIAL_VERIFY=1` was intentionally used for a local
209+
smoke check.
210+
211+
## Layout
212+
213+
```text
214+
opendesign/
215+
├── spec.yaml # kit declaration
216+
├── files/home/
217+
│ ├── opendesign-install.sh # Node 24 + OpenDesign source install/build
218+
│ ├── opendesign-relay.mjs # guest-network -> loopback publish relay
219+
│ └── opendesign-start.sh # app-config seed + daemon/relay supervisors
220+
├── README.md
221+
├── TROUBLESHOOTING.md
222+
├── scripts/verify # offline + optional live verification
223+
└── docs/decisions/ # design records
224+
```
225+
226+
## Design records
227+
228+
Rationale lives in [`docs/decisions/`](docs/decisions/): source install instead
229+
of Docker, OpenDesign auth disabled behind the ACQ loopback boundary, and
230+
ACQ/OpenCode-owned BYOK credential flow.

0 commit comments

Comments
 (0)