Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

OpenCode GSD Devcontainer

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.

Included

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

Quick Start

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/.gitignore

Open the project in VS Code and choose Reopen in Container, then start OpenCode:

opencode

Run /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.

Features

PPQ Models

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.

Quota and Usage Reporting

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.

GSD Model Profiles Removed

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.

Model Council

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.

Upgrading from OpenCode 1

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 Security

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 and Test

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-plugin

Each 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.

Publishing

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.

Daily updates

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.json overrides.

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):

  1. 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.
  2. Set repository variables UPDATE_APP_ID and UPDATE_BOT_LOGIN (the App's exact login, such as my-updater[bot]), and secret UPDATE_APP_PRIVATE_KEY.
  3. Set Actions Repository secret PPQ_API_KEY to a funded PPQ key for the selector (other workflows can reuse the same secret). Optionally set Actions Repository variable UPDATE_MODEL to an exact PPQ catalog ID (without ppq/); it defaults to openai/gpt-6.1-sol. This selects the evaluator, not the council members, and must be updated if PPQ removes that evaluator ID.
  4. 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.
  5. Protect master: require test-maintenance, test-plugins, and image; 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.

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages