opencode-agent-deploy 0.7.0

Install agent tool packages into global or project OpenCode configurations

OpenCode Agent Deploy

opencode-agent-deploy installs existing agent packages from public PyPI into the virtual environment that executes the deploy command and ships native Firstmate orchestration in the same distribution. It generates OpenCode skills, tools, agents, and plugins with absolute paths back to that environment.

Version 0.7.0 supports these published deploy packages and two bundled native components:

• pdf: agent-pdf-workspace==0.1.1
• mapper: agent-codinglanguage-mapper==1.1.1
• memory: opencode-markdown-memory==0.1.0
• folder: agent-folder-workspace==0.1.0
• firstmate: opencode-agent-deploy==0.7.0 (bundled; no pip download)
• guard: opencode-agent-deploy==0.7.0 (bundled; no pip download)

Native guard

Guard is a second native component in this release.

Install it globally:

opencode-agent-deploy install --package guard --scope global --yes

Install it into the selected project:

opencode-agent-deploy install --package guard --scope project --target "$PWD" --yes

Guard installation writes three generated artifacts:

• plugins/opencode-subagent-guard.js
• agents/opencode-guarded-orchestrator.md
• agents/opencode-guarded-worker.md

These are model-neutral Markdown agents plus the installed JavaScript hook. OpenCode auto-loads them from the integration root and does not require any opencode.json edits. Select the orchestrator with --agent opencode-guarded-orchestrator; choose models through normal OpenCode model configuration or CLI selection.

Version 0.7.0 contains no opencode.json mutation path, so it creates no config backup. Any future implementation that needs to change that file is prohibited unless it first satisfies this contract:

• opencode.json is backed up to opencode.json.backup-<UTC timestamp> before mutation;
• writes are applied with atomic replacement;
• failures restore the exact original opencode.json content;
• the backup is retained until the operator explicitly removes it.

The bundled guard copy carries an explicit Apache-2.0 SPDX notice. The earlier standalone NPM repository remains private and separately licensed; the Python distribution is the supported public installation source.

The upstream packages are not copied or republished. The deploy command downloads the selected, pinned distributions directly from https://pypi.org/simple.

Requirements

• Python 3.11 through 3.14
• An OpenCode installation
• Network access to public PyPI when an external package is selected
• Git 2.22 or newer and a named branch when Firstmate is used

Install the deploy command with an isolated application installer. Its application environment becomes the shared default runtime for all selected packages:

uv tool install opencode-agent-deploy

Alternatively, use pipx install opencode-agent-deploy or install it into your own activated virtual environment. The command rejects the default runtime mode when it is executed by a system Python outside a virtual environment.

Interactive installation

Run:

opencode-agent-deploy install

The command shows all six component names and versions. Select 1 through 6, or a comma-separated combination such as 1,2,3,4,5,6, then select global or project scope and confirm the plan. Global scope writes generated artifacts to the OpenCode config directory. Project scope writes them below .opencode/ in the selected project. In both scopes, opencode.json remains user-owned.

Automated installation

Install all external packages and native Firstmate into the current project:

opencode-agent-deploy install \
  --package pdf \
  --package mapper \
  --package memory \
  --package folder \
  --package firstmate \
  --package guard \
  --scope project \
  --target "$PWD" \
  --yes

Install only the PDF workspace globally:

opencode-agent-deploy install \
  --package pdf \
  --scope global \
  --yes

Use an explicit global OpenCode config directory when automatic discovery is not appropriate:

opencode-agent-deploy install \
  --package mapper \
  --scope global \
  --config-dir "$HOME/.config/opencode" \
  --yes

Install only Markdown memory globally:

opencode-agent-deploy install \
  --package memory \
  --scope global \
  --yes

Install only the folder workspace globally:

opencode-agent-deploy install \
  --package folder \
  --scope global \
  --yes

Install only native Firstmate into the current project without creating another Python environment or downloading another distribution:

opencode-agent-deploy install \
  --package firstmate \
  --scope project \
  --target "$PWD" \
  --yes

For automation, every selected package is supplied with a repeated --package flag and the scope is supplied with --scope. --json emits a machine-readable result. The default --runtime current installs into the executing venv and cannot be combined with --dry-run. Use --runtime isolated --dry-run to download and validate packages in temporary environments and collision-check OpenCode files without committing them.

Runtime selection and managed files

The default current runtime installs all selected, exactly pinned packages with one dependency resolution into sys.prefix, the venv that contains and executes opencode-agent-deploy. It does not create another venv. On Windows this means the packages and commands remain in that environment's Lib\site-packages and Scripts directories; no package venv is created below %LOCALAPPDATA%.

Firstmate is native to opencode-agent-deploy. In either runtime mode it uses the interpreter executing the deploy command; it never invokes pip and never creates a separate Firstmate environment.

The previous per-package behavior remains available with --runtime isolated. It creates separate environments below the platform data directory: global environments use venvs/global/<package>, while project environments use venvs/projects/<project-hash>/<package>.

Generated OpenCode artifacts contain the absolute Python or console-script path from the selected runtime. In the default mode, Python is exactly the interpreter that executes opencode-agent-deploy, and console scripts are taken from the same venv. The PDF skill and TypeScript tool therefore call the selected pdfws executable directly. The package-named mapper skill, plugin, and Markdown agent use that Python interpreter directly. The Markdown memory TypeScript tool calls its opencode-markdown-memory executable directly. No shell activation or ambient PATH modification is required.

The folder workspace skill and project-aware plugin are generated by the upstream package. The plugin calls the selected Python interpreter directly and starts one local stdio MCP server for the normalized active OpenCode project root.

Markdown memory configuration and data are scope-local. Global deployment uses <opencode-config>/opencode-markdown-memory/; project deployment uses <project>/.opencode/opencode-markdown-memory/. The generated config.toml is deploy-owned. The mutable MEMORY.md is initialized atomically on first use and is never placed under deploy ownership, so later deployments cannot overwrite memories.

The installer owns generated files recorded in opencode-agent-deploy-manifest.json. It never reads, writes, deletes, or claims ownership of opencode.json. Upgrading from an older deploy release removes any prior manifest claim on that path without inspecting or changing the file.

This neutrality guarantee applies to opencode-agent-deploy and Firstmate. OpenCode 1.17.18 itself adds its $schema line the first time it loads a schema-less opencode.json; the same normalization occurs in a project without Firstmate. The release E2E therefore checks the original file byte-for-byte immediately after installation, records only that exact OpenCode-owned normalization as the runtime baseline, and then rejects every later configuration change during coordination.

The mapper is installed as skills/agent-codinglanguage-mapper/SKILL.md and agents/agent-codinglanguage-mapper.md within the selected integration root. Markdown memory still needs the user to allow its tools in their own OpenCode configuration, for example:

{
  "permission": {
    "markdown_memory_*": "allow"
  }
}

For other generated artifacts, the installer refuses to overwrite:

• an existing destination it does not own;
• an owned destination changed locally since the previous deployment;
• a symlink in a managed path;
• malformed or unexpected exporter output.

Artifact updates and the ownership manifest are committed atomically. Isolated package environments are restored if preparation or validation fails. Package changes inside the default executing venv are ordinary pip changes and are not rolled back when a later OpenCode artifact step fails.

Native Firstmate

Firstmate is shipped inside the existing opencode-agent-deploy PyPI package. The native install flow is firstmate from this package, no separate deploy package.

Safe installation defaults

• Safe defaults are enabled unless you configure otherwise through profiles.
• Installer behavior remains transactionally bounded and idempotent for generated files.
• opencode.json is never read, written, or ownership-marked by Firstmate installers.
• Firstmate artifacts are generated as:
  • skills/opencode-firstmate/SKILL.md
  • agents/opencode-firstmate.md
  • plugins/opencode-firstmate.ts

Firstmate config, TOML locations, precedence, and profiles

Configuration is written to firstmate.toml outside opencode.json:

• User config: <opencode-config>/firstmate.toml
• Project config: <project>/.opencode/firstmate.toml

Layer precedence is:

1. built-in safe profile
2. user config
3. project config
4. explicit session overrides

Available profiles:

• safe (default): supervisory mode for orchestration/routing, repair and remote CI off by default.
• balanced: deeper review and limited parallelism.
• autonomous: stronger depth, routing breadth, and higher budget ceilings.

Profiles can be written with: opencode-agent-deploy firstmate configure --scope user|project --profile safe|balanced|autonomous.

Trust model and approvals

Protected actions are evaluated as allow, ask, or deny.

ask actions require a digest-bound approval flow. Approval is checked against:

• task id
• action
• commit
• immutable target
• config digest
• repository digest

firstmate_approve requires the exact pending action digest. In the default profile, firstmate_integrate first creates that pending subject and remains blocked until the matching approval has been recorded; OpenCode also marks both tools as ask.

Trusted projects, remote workers, and status

Cross-project execution is opt-in through a private registry at ~/.config/opencode/firstmate-projects.json. Registering a project binds its canonical path, normalized Git remote, effective configuration, repository identity, and any authority approval to one digest:

opencode-agent-deploy firstmate projects register \
  --project /absolute/path/to/project --alias build --yes --json
opencode-agent-deploy firstmate projects list --json
opencode-agent-deploy firstmate projects disable --alias build --yes --json

The registry is independent of opencode.json, is written atomically with private permissions, and rejects symlinked storage paths. Remote SSH execution additionally requires an enabled exact registry identity and a policy decision for remote_runner. The fixed opencode-firstmate-worker endpoint accepts only timestamped HMAC-signed JSON, binds task operations to its configured project, and records request IDs in a private SQLite replay ledger shared across worker processes. Signing material belongs in the worker's secret process environment and is never a TOML or OpenCode configuration value.

opencode-agent-deploy firstmate dashboard --project /absolute/path --json returns a bounded local snapshot. Notification destinations appear only as short SHA-256 identifiers; raw endpoints and message bodies are not exposed by the dashboard.

Firstmate tools (10 native tools)

The plugin exposes exactly ten firstmate_* tools:

• firstmate_config
• firstmate_plan
• firstmate_dispatch
• firstmate_status
• firstmate_wait
• firstmate_review
• firstmate_cancel
• firstmate_inspect
• firstmate_approve
• firstmate_integrate

Start the coordinator directly in the native OpenCode CLI:

opencode . --agent opencode-firstmate --model openrouter/google/gemma-4-31b-it

For independent work, instruct it to dispatch every task before the first wait. Each dispatch receives a separate branch, worktree, background runner, worker session, and reviewer session. The reproducible command and parallel screenshots are documented in the native CLI walkthrough.

Operational scope in 0.7.0

• parallel coordination via detached dispatch/status/wait and bounded task queues
• orchestration/routing modes, strategy, and bounded model selection
• repair loop with bounded attempts
• budgets (max_cost_per_task) and unknown usage pause behavior
• remote lifecycle actions for cross-project and CI runners behind trust rules
• runner lifecycle tracking with kernel birth identities and crash recovery
• kernel-lock liveness, at-most-once dispatch claims, renewable/fenced scheduler leases, and cooperative cancellation that stops OpenCode only through the runner-owned child handle
• notifications and dashboard visibility through the bounded dashboard and approvals views
• immutable task snapshots used during inspect/review integration checks

Boundaries and limitations

• plugin invocation is shell-free: fixed argument arrays, no sh -c.
• child commands execute with the runtime account; Firstmate is not a sandbox.
• cancellation is immediate while an owned OpenCode child is running; validation and CI commands observe the durable cancelled state at the next pipeline checkpoint.
• credentials are actively excluded from command environment and redacted from evidence.
• review/pipeline controls are explicit and reproducible; Firstmate does not auto-approve.
• all Firstmate work and policy files are opt-in; no automatic cross-project changes.

The coordinator is designed for trusted projects and trusted models. Review, clean-tree checks, and digest-bound approvals bound what is integrated; they do not prevent the user-supplied commands from following their own command semantics.

OpenCode verification

Restart OpenCode after a successful deployment so it reloads project or global integrations. Confirm that the installed PDF skills/tools, package-named mapper skill/plugin/Markdown agent, five markdown_memory_* CRUD tools, folder workspace skill/plugin/MCP server, and the Firstmate coordinator/skill/ten native tools appear in the intended scope. The command output identifies the config file, manifest, environments, and generated artifacts; --json is useful for scripted verification.

Trust boundary

Deployment installs and executes the pinned upstream exporters. Only use releases you trust. Subprocesses are invoked as argument arrays without a shell, and package downloads are restricted to the public PyPI simple index. The deploy command does not read or print credential files and does not manage PyPI credentials.

Security reporting and supported-version policy are in SECURITY.md. The reproducible maintainer procedure is in docs/release.md.