opencode-agent-deploy 0.4.1

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. It generates their OpenCode skills, tools, plugins, and configuration with absolute paths back to that same environment.

Version 0.4.1 supports these already published deploy packages:

• pdf: agent-pdf-workspace==0.1.1
• mapper: agent-codinglanguage-mapper==1.1.0
• memory: opencode-markdown-memory==0.1.0
• folder: agent-folder-workspace==0.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. 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 four package names and pinned versions. Select 1, 2, 3, 4, or a comma-separated combination such as 1,2,3,4, 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 all four packages into the current project:

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

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

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 mapper skill, plugin, and agent configuration 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. opencode.json is treated as shared user configuration: JSONC comments and trailing commas accepted by OpenCode can be read, unrelated properties are preserved, and the merged result is written as strict JSON. Comments and original formatting are therefore normalized during a mapper or memory deployment. A content snapshot prevents replacing the file if another process changes it while deployment is being prepared.

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.

OpenCode verification

Restart OpenCode after a successful deployment so it reloads project or global integrations. Confirm that the installed PDF skills/tools, mapper skill/plugin/agent, five markdown_memory_* CRUD tools, and folder workspace skill/plugin/MCP server 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.