opencode-agent-deploy 0.1.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 isolated Python environments and generates their OpenCode skills, tools, plugins, and configuration with absolute runtime paths.

Version 0.1.0 supports these already published deploy packages:

• pdf: agent-pdf-workspace==0.1.1
• mapper: agent-codinglanguage-mapper==1.1.0

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 during deployment

Install the deploy command with an isolated application installer:

uv tool install opencode-agent-deploy

Alternatively, use pipx install opencode-agent-deploy or install it into your own virtual environment.

Interactive installation

Run:

opencode-agent-deploy install

The command shows both package names and pinned versions. Select 1, 2, or 1,2, then select global or project scope and confirm the plan. Global scope writes to the OpenCode config directory. Project scope writes to opencode.json and .opencode/ below the selected project.

Automated installation

Install both packages into the current project:

opencode-agent-deploy install \
  --package pdf \
  --package mapper \
  --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

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. --dry-run downloads and validates the packages in temporary environments and performs collision checks without writing OpenCode files or managed environments.

Managed files and environments

Each deploy package gets a separate virtual environment under the platform data directory for opencode-agent-deploy. Global environments use venvs/global/<package>. Project environments use venvs/projects/<project-hash>/<package>, so project dependencies cannot collide.

Generated OpenCode artifacts contain the absolute Python or console-script path from their managed environment. The PDF skill and TypeScript tool therefore call the selected pdfws executable directly. The mapper skill, plugin, and agent configuration use the selected mapper environment's Python interpreter directly. No shell activation or ambient PATH modification is required.

The installer owns only files recorded in opencode-agent-deploy-manifest.json. It preserves unrelated OpenCode configuration and 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. Existing package environments are restored if preparation or validation fails.

OpenCode verification

Restart OpenCode after a successful deployment so it reloads project or global integrations. Confirm that the installed PDF skills/tools and mapper skill/plugin/agent 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.