English | 简体中文

Convax Plugins and Marketplace

The official source registry, authoring kit, and release catalog for Convax Plugins, portable Agent Skills, and standard MCP Servers. Published Skills follow the open SKILL.md format and can be used by compatible agents such as OpenAI Codex; they are not designed exclusively for Convax.

This repository lets people and AI agents start from a template and produce a Plugin, Skill, or MCP Server that can be validated independently and published deterministically, and downloaded safely by Convax. Package source is reviewed in Git, immutable ZIPs are published through GitHub Releases, and GitHub Pages hosts the lightweight Marketplace descriptor at https://microvoid.github.io/convax-plugins/marketplace.json. Current clients use Registry v2; a strict Registry v1 projection remains available for older clients.

Featured Skills can publish a poster and an animation beside their immutable Release ZIP. Convax verifies that media through the separate Showcase index and plays it in the catalog; the media never becomes part of the portable Skill.

Quick start

Requirements: Bun 1.3.14 or newer.

Install the complete workspace graph once. Every Plugin, Skill, and Tool owns its dependencies in its own package.json; the root lockfile keeps the monorepo reproducible without CI-specific package lists.

bun install --frozen-lockfile --ignore-scripts

cp -R templates/plugin-basic packages/plugins/my-plugin
# Replace every __TOKEN__ and implement package/index.html.
bun run validate
bun test
bun run pack -- --kind plugin --id my-plugin

For a Skill, start from the portable Skill template instead:

cp -R templates/skill-basic packages/skills/my-skill
# Replace every __TOKEN__ in convax-package.json, SKILL.md, and agents/openai.yaml.
bun run validate
bun test
bun run pack -- --kind skill --id my-skill

The generated Plugin ZIP has manifest.json at its root. A Skill ZIP has SKILL.md at its root. No dependency install or contributor build script is run while validating or packing a package.

Create a third-party Marketplace

The public scaffold and Kit use the same Plugin, Skill, and MCP Server contracts as this Official Marketplace:

bunx create-convax-marketplace@0.1.0 my-market \
  --owner my-org \
  --repository my-market \
  --starter mcp-server
cd my-market
bun run check
bun run build-index

Add another package with bun run marketplace -- new plugin --id my-plugin. For a reviewed managed-stdio MCP companion, admit one target with bun run marketplace -- add-target packages/mcp-servers/example-mcp --target darwin-arm64 --file /path/to/reviewed-companion; the bare executable is copied into the private authoring input area and the source path is never published.

Executable Tool Plugins may be headless. convax.plugin/3 separates executable tools, model-picker entries, Agent tools, and Canvas selection actions; convax.plugin/4 and later may also own Skills. Local executable contributions declare a separately installed bare mcp-stdio command and never embed that executable, its dependencies, vendor credentials, or provider configuration. See docs/plugin-authoring.md. For reviewed first-party tools, the Registry publishes exact platform/architecture companion artifacts beside the ZIP. Convax verifies their size and SHA-256 into host-owned storage, so users do not install a sidecar through PATH and executables still never enter a Plugin package.

convax.plugin/5 additionally declares an LLM provider as bounded provider/model metadata. It may opt into a fixed, bounded runtime model catalog while keeping model ids opaque. The verified sidecar supplies that display catalog and a random, Main-only loopback gateway at runtime; manifests and service projections never contain upstream URLs, Cookies, headers, or credentials.

Executable Service contributions use the breaking convax.plugin-service-status/2 projection for account, current Plan, Billing/ Checkout availability, credits, and usage. A declared fixed checkout action accepts only an advertised Plan Key; its canonical HTTPS URL remains Main-only and is opened by the host in the system browser. Status v1 plugins must be upgraded before they can load in the current Services surface.

A Plugin may also declare one self-contained OpenCode Hook module with hooks. Convax snapshots and fingerprints its exact JavaScript bytes during an explicit install or update, then lets OpenCode load that private snapshot. Hook events stay native to OpenCode; Convax does not add another Hook API. Because this module is executable Agent code rather than iframe content, default/background provisioning never authorizes new Hook bytes. See docs/plugin-authoring.md.

convax.plugin/5 and /6 use the transport-neutral convax.plugin-capability/1 host contract. v5 adds Project/Canvas grants and generic LLM display metadata. v6 may additionally declare one HTTPS remote Agent MCP endpoint. Convax delegates that endpoint to OpenCode/the native MCP host, including standard OAuth, while the remote service retains its own account and authentication system. The declaration contains no local command, adapter, or secret. Only bounded literal non-credential headers are allowed. Concrete Plugin, Skill, and reviewed companion source remains in this repository rather than moving into the Convax host.

convax.plugin/7 uses convax.plugin-capability/2. It adds a declaration that can materialize the contributing Plugin's own renderer node from one selected video, plus a short-lived canvas.connectedMedia.stream grant for directly connected audio/video preview. Neither declaration can name another Plugin or expose a native Project path.

v6 also supports Canvas sink operations: a Web node can inspect pathless metadata for directly connected media, while a manifest-declared local operation can bind its Agent references to those exact incoming edges and return a bounded text result without creating another Canvas node. Edge changes only refresh pending input metadata; external transfer still requires an explicit user action.

convax.plugin/4 and later support Plugin-owned Skills. The Plugin declares contributes.skills, and the packer injects each referenced standard Skill workspace into the Plugin ZIP. Convax may show that Skill in its catalog, but its install, update, and removal lifecycle belongs to the Plugin. The standalone Skill ZIP remains portable to Codex and other Agent Skills clients. Because the same source changes both archives, an owned Skill release must also bump and publish its owner Plugin. Pages withholds an incomplete owner/Skill update and keeps their previous published pair visible until both new Releases exist.

convax.plugin/5 adds transport-neutral host capabilities, including a sandboxed desktop pet feature. One Pet feature Plugin uses the convax.plugin-capability/1 compatibility pair and contributes static overlay and settings surfaces plus a convax.pet-library/1 packaged collection through contributes.pet. The surfaces use the scoped convax.pet-host/1 protocol; Convax retains only the native window, content-free activity projection, validated navigation, installed asset serving, and bounded persistence. See the working package in packages/plugins/convax-pet.

See the working example in packages/plugins/hello-convax, then read:

• docs/plugin-authoring.md for the sandbox and host protocol;
• docs/panorama-viewer.md for the Panorama Viewer source-ownership and clean-profile release boundary;
• docs/storyai-3d-director-desk.md for the 3D Director Desk source-ownership, upstream, and clean-profile release boundary;
• docs/skill-authoring.md for safe, portable Skills;
• docs/packaging.md for ZIP and release rules;
• docs/registry-spec.md for the client contract;
• CONTRIBUTING.md before opening a pull request.

Portable Skill boundary

For a Skill package, only the contents of package/ are placed in the published ZIP. That directory is a standard Agent Skill root: SKILL.md is required, while scripts/, references/, assets/, and client metadata such as agents/openai.yaml are optional. A compatible client may ignore metadata intended for another client without changing the Skill workflow.

Do not add a README.md, installation guide, changelog, or publishing notes to an individual Skill bundle. SKILL.md is the agent-facing entry point; repository and marketplace documentation belongs outside package/. Likewise, convax-package.json stays beside package/. It describes Convax catalog and release metadata and is deliberately excluded from the portable Skill ZIP.

A Skill may name a host integration, but it must first use capabilities actually available in the current session. Optional tool absence, denial, cancellation, or failure must have an honest fallback: produce a useful handoff when possible, or stop and identify the unavailable operation. Never invent a tool call or claim an artifact, installation, or mutation succeeded when it did not.

Install in Convax

Open Settings → Skills and Plugins in a compatible Convax build. The catalog is loaded from the public Registry above; selecting Install Plugin or Install Skill sends only the package id to Convax main, which downloads and validates the corresponding immutable Release ZIP. If a v2 through v7 Plugin declares Registry companions for a local runtime, the same install transaction selects only the exact local platform/architecture artifact and verifies its immutable URL, byte count, and SHA-256 separately from the static ZIP. For v4 and later, Plugin-owned Skills are admitted and removed in that same Plugin transaction; they are never an independent Convax install action.

The microvoid/convax-plugins repository, Registry, and Release assets are public and require no GitHub account or token. The main microvoid/convax application repository may remain private without affecting package installation.

Repository layout

packages/plugins/<id>/
  package.json             # workspace dependencies and contributor scripts
  convax-package.json      # Convax publishing metadata; excluded from the ZIP
  package/                 # ZIP root; manifest.json must be here
packages/skills/<id>/
  package.json             # workspace dependencies and contributor scripts
  convax-package.json      # Convax publishing metadata; excluded from the ZIP
  package/                 # portable Skill root; SKILL.md must be here
  showcase/                # optional catalog poster/animation; excluded from ZIP
packages/mcp-servers/<id>/
  server.json              # standard MCP identity/version and fixed HTTPS profile
  convax-mcp.json          # managed-stdio only
packages/tools/<id>/       # reviewed Tool workspace; separately distributed
templates/                 # copy-only author starters
tooling/                   # validation and deterministic ZIP
schemas/                   # package, Registry, and Plugin JSON Schemas
dist/                      # generated; never committed

Commands

bun run validate            # validate all source packages
bun run workspaces:build:packages # build self-contained Skill/Plugin package trees
bun run workspaces:typecheck # type-check workspaces that declare the script
bun run workspaces:test     # test workspaces that declare the script
bun test                    # validator, ZIP, Registry, and protocol tests
bun run render:showcases -- --id ad-idea # render one poster and animation
bun run build:companions    # compile explicitly reviewed platform targets
bun run marketplace:check  # validate authoring source through the packed Kit
bun run marketplace:build  # build v2/v1, Releases, Builtin, and lock input
bun run check               # complete local CI sequence

Marketplace publication dogfoods the packed @convax/marketplace-kit. The repository pins the Kit to exact version 0.1.0; local source links are not a valid publication dependency. The matching Kit package must therefore be published before a clean frozen install of this repository.

Authors change a Plugin, Skill, or MCP Server version and merge through protected main; they do not create release tags. The default-branch workflow rejects changed bytes without a version change, builds deterministic artifacts in a low-privilege job, then lets a minimal privileged job tag and publish only those verified bytes. Registry v2, its strict v1 projection, Showcase v2, and the immutable Builtin bundle are generated rather than hand-edited.

bun run pack and bun run build:index remain legacy v1 compatibility diagnostics. They do not provide bytes, URLs, or metadata to the v2 release workflow.

Troubleshooting installation

• Redirect was cancelled indicates an older Convax host that did not adapt Electron's manual redirect behavior for GitHub Release downloads. Update to a build containing the Electron Release redirect adapter.
• Unable to connect usually indicates a proxy, DNS, firewall, or offline problem. Verify that both the Registry URL and the package's artifact.url are reachable from the same machine.
• HTTP 404 or 403 should be checked against the public URLs in the Registry. No request should depend on access to the private Convax application repository.
• A size, SHA-256, schema, compatibility, or ZIP validation failure is intentional fail-closed behavior. Do not bypass it; inspect the published Registry entry and Release asset instead.

Trust boundary

Third-party Plugin ZIPs are inert during validation and packing. Web surfaces are static HTML/CSS/JavaScript rendered by Convax in an iframe with exactly sandbox="allow-scripts"; they cannot contain native executables, Node/Electron code, network permissions, or a generic host bridge. A v2 through v7 Tool Plugin may name a separately installed external command. Convax resolves and fingerprints it during explicit Plugin install/update; that transaction is consent to the exact binding, so later calls do not show a separate command prompt. It never becomes part of the ZIP. A Registry companion is an independent immutable Release asset, admitted only after exact target, size, and digest verification. Every host call is scoped to the mounted Plugin node and checked against the manifest capability allowlist. Skills are instructions, not executable capability grants.

The explicit exception is a manifest-declared hooks module: one bundled JavaScript ESM file executed as a native OpenCode Plugin. Installation consent is bound to its normalized manifest and exact bytes; OpenCode loads only a private host snapshot. It is not sandboxed, so silent default installation or background updates cannot authorize it.

A v6 remote Agent MCP contribution is different: it names only an HTTPS endpoint that the native Agent host connects through its standard MCP/OAuth support. It does not authorize iframe networking, ship a local command, or carry credentials.

License

Repository tooling, templates, and hello-convax are MIT licensed. Each submitted package must declare its license and include notices its dependencies require.