A VS Code development container for running OpenCode 2 with GSD, multi-provider model routing, a read-only model council, usage reporting, and browser automation.
ghcr.io/ibobik/opencode-gsd-devcontainer:latest
The image tracks the latest upstream releases. Use an image digest when you need reproducible builds.
| Component | Purpose |
|---|---|
| OpenCode | Provider-agnostic coding-agent runtime |
| PPQ provider plugin | Adds the live PPQ model catalog and authentication |
| OpenCode Quota | Quota sidebar, token/cost reports, and retry after quota resets |
| Council plugin | Asks multiple model families to analyze the same request and synthesizes their responses |
| GSD | Autonomous planning, implementation, and verification |
| Browser tooling | Chromium, Playwright, agent-browser, and gsd-browser |
| Tinfoil Proxy | Preinstalled proxy for accessing private models in trusted execution environments (TEEs) |
| Terminal tooling | GitHub CLI, tmux, the Skills CLI, and the agent-browser dogfood skill |
You need Docker and VS Code with the Dev Containers extension.
From your project root, download the dev container template:
curl -fsSL --create-dirs -o .devcontainer/devcontainer.json https://raw.githubusercontent.com/ibobik/opencode-gsd-devcontainer/master/template/.devcontainer/devcontainer.json -o .devcontainer/.gitignore https://raw.githubusercontent.com/ibobik/opencode-gsd-devcontainer/master/template/.devcontainer/.gitignoreOpen the project in VS Code and choose Reopen in Container, then start OpenCode:
opencodeRun /connect to add a model provider. For PPQ, select PPQ and paste an API
key.
The template persists OpenCode authentication and sessions under
.devcontainer/data/. Its local .gitignore excludes that directory.
The PPQ plugin loads the current PPQ catalog after authentication and caches it for startup resilience. See the PPQ plugin guide for installation, credential precedence, and failure behavior.
The included @slkiser/opencode-quota
provides a quota sidebar and /quota, /quota_status, /tokens_session, and
other token/cost reports. Provider detection is automatic. When a provider hits
a limit and its quota window is exhausted, wait-for-reset is enabled so
OpenCode can retry after the reset. PPQ-specific balance reporting is not configured.
Settings are baked into
~/.config/opencode/opencode-quota/quota-toast.json. The sidebar is enabled;
automatic popup toasts and the compact status line are disabled.
The opencode-gsd-models-plugin has been removed and is no longer bundled.
GSD_MODELS_PROFILE and /gsd-models-profile are no longer supported by this
image. GSD uses its built-in profiles with OpenAI sol, terra, and luna
tier mappings from gsd-defaults.json. The OpenCode default follows the sol tier.
See the GSD Core model profiles documentation
for GSD's built-in profile configuration.
Use /council <prompt> to ask the configured council members for independent
analysis and receive a synthesis of their agreement, disagreements, and
uncertainty.
The default council uses seven PPQ models. Each member call can add latency and incur model cost. See the council guide to change its members, quorum, or web access.
Rebuild the devcontainer to install @opencode/cli (OpenCode 2) and the migrated
plugins. The development environment's setup installs the v2 CLI on rebuild.
GSD-Core's upstream v2 adapter is included;
the removed GSD-models plugin is not restored.
Back up .devcontainer/data/ before first opening existing v1 data with v2.
Both generations share data locations, and v1 cannot necessarily reopen a v2-used
database. V2 owns provider connections; reconnect with /connect if an old login
is not available. The PPQ plugin uses v2 integration APIs rather than reading
auth.json directly.
After changing configuration, plugins, or environment variables, quit OpenCode,
run opencode service stop, then start opencode again. A running background
service retains its loaded configuration and environment.
Browser tools use the system Chromium binary with --no-sandbox,
--disable-gpu, and --disable-dev-shm-usage for container compatibility.
Treat browser sessions as untrusted and do not expose credentials or sensitive
sites that the agent should not access.
Build the image locally:
docker build -t opencode-gsd-devcontainer:local .Set the template image to opencode-gsd-devcontainer:local to use that build.
Run the plugin test suites from the repository root:
docker build -f opencode-ppq-plugin/test/Dockerfile opencode-ppq-plugin
docker build -f opencode-council-plugin/test/Dockerfile opencode-council-pluginEach plugin build runs behavioral tests, typechecks its implementation, and loads it in the official OpenCode 2 image. The full-image build checks CLI installation and GSD assets, but does not exercise the combined plugin configuration.
For an authenticated check after rebuilding: connect PPQ, confirm its live models
in /models, run /council and /council-last in the same conversation, open
/gsd-help, and inspect /quota_status and /tokens_session after a model request.
GitHub Actions tests all plugins on pull requests. Pushes to master and tags
matching v* publish linux/amd64 and linux/arm64 images to GHCR. Use an
image digest for an immutable deployment.
GitHub Actions checks npm stable releases, the public models.dev catalog, and PPQ's live model catalog daily at 05:23 UTC (or manually through Daily runtime and model updates). It opens or refreshes one maintenance PR:
- GSD tiers and both OpenCode default-model settings stay synchronized using the highest numeric released, active OpenAI Sol/Terra/Luna version within each family.
- OpenCode evaluates council members using
maintenance/council-policy.json. Missing IDs and quality upgrades use the same selection process. It can keep current models, repair changed IDs, or recommend stronger same-vendor models. The PR explains each decision, sources, current availability, prices, and context. - Code validates exact IDs from a fresh PPQ response, text/tool support, at least
32K context, and prices at most $15/$75 per million input/output tokens. It writes
packaged council defaults, not plugin code or user
council.jsonoverrides.
The selector has 12 model steps and a 10-minute timeout; the job has a 20-minute timeout. It runs outside the checkout with isolated configuration and only web research tools: no shell, file access, editing, or delegation. Invalid, incomplete, or unavailable selections fail before files are written. Catalog presence does not guarantee account access or inference success; the LLM's quality assessment and cited evidence remain recommendations, not independently verified benchmarks.
Component installations remain floating, not pinned. maintenance/releases.json
records observed releases for OpenCode CLI, GSD Core, GSD Pi, and GSD Browser.
A changed observation refreshes the installation layer. CI verifies actual installed
versions; if another release appears during the build, refresh the PR by rerunning
the daily workflow. Major component upgrades are highlighted and require manual
review. Model generation changes are not component SemVer major upgrades.
The initial manifest is an observation baseline; subsequent PR checks validate it.
Non-major maintenance PRs are approved and queued for squash auto-merge only after validation succeeds. Arbitrary PRs and changes outside the six updater-owned JSON files are never auto-approved. The approval workflow runs trusted default-branch code, recomputes runtime/GSD changes, and validates the actual council proposal against the fresh PPQ catalog and trusted policy. It does not rerun the LLM or require identical recommendations across runs. Council identities, ordering, and non-model settings cannot change through this workflow.
Repository setup (one time):
- Install a dedicated GitHub App on this repository with Contents: read/write and Pull requests: read/write. Do not grant it a branch-protection bypass.
- Set repository variables
UPDATE_APP_IDandUPDATE_BOT_LOGIN(the App's exact login, such asmy-updater[bot]), and secretUPDATE_APP_PRIVATE_KEY. - Set Actions Repository secret
PPQ_API_KEYto a funded PPQ key for the selector (other workflows can reuse the same secret). Optionally set Actions Repository variableUPDATE_MODELto an exact PPQ catalog ID (withoutppq/); it defaults toopenai/gpt-6.1-sol. This selects the evaluator, not the council members, and must be updated if PPQ removes that evaluator ID. - Enable Allow auto-merge, squash merging, and Allow GitHub Actions to create
and approve pull requests. The App authors PRs;
github-actions[bot]approves, providing distinct identities. Organization policies must permit this. - Protect
master: requiretest-maintenance,test-plugins, andimage; require an approval, dismiss stale approvals, and require branches to be up to date. Do not allow the updater to bypass these checks. After a base-branch change, update the PR branch and rerun its validation.
The App token ensures PR checks and post-merge publication are triggered. Ordinary
GITHUB_TOKEN-authored changes generally do not trigger new workflow runs.
To run the same update locally, install OpenCode, export PPQ_API_KEY, and run
node maintenance/update.mjs from the repository root. It writes the same files
and a PR-description preview (UPDATE_BODY_PATH, default /tmp/update-body.md),
but does not commit, push, or create a PR. This makes a paid selector request.
Both image architectures are built on PRs. Trusted same-repository PRs export
BuildKit layers to GHCR buildcache-<head-sha> tags; master imports the merged
PR's cache and exports buildcache-master. Fork PRs cannot write registry caches.
The merge build still evaluates changed inputs; it is cache reuse, not an exact
image promotion. Retain GHCR cache tags long enough for review, and periodically
remove old buildcache-<sha> tags while keeping buildcache-master.
To validate maintenance automation locally, use
docker build -f maintenance/test/Dockerfile .. To also enforce observed component
versions in a local image build, use
docker build --build-arg CHECK_RELEASES=true -t opencode-gsd-devcontainer:local ..
Normal local builds keep floating installations without this version comparison.