Install Extensions

Extensions are installable packages that add static resources or runtime behavior to CompozyOS. An extension can ship skills, agent definitions with authored-context sidecars, automation, layouts, hooks, loops, MCP servers, memory backends, model sources, and subprocess tools.

CompozyOS stores installed extensions in the global registry and copies managed installs into <COMPOZY_HOME>/extensions/<name>.

Install sources

compozy extension install <source> takes one closed source union. The CLI infers the source from the argument:

compozy extension install ./hello
compozy extension install github:acme/hello@v0.1.0
compozy extension install git:https://github.com/acme/hello@v0.1.0
compozy extension install acme/linear-bridge

A path that does not exist fails naming that path instead of degrading into a slug lookup, and a git URL carrying embedded credentials is rejected before any request. HTTP, UDS, and native-tool callers submit the structured union directly; the shorthand is a CLI convenience.

--version and --asset select a specific registry version or archive for published sources.

Detected package layouts

CompozyOS detects the package layout after acquiring the source. You do not select a format flag.

An Agent Plugins package may provide immediate child directories under skills/ and MCP servers in mcp.json. CompozyOS maps stdio and streamable-http servers, records unsupported components as skipped diagnostics, and keeps the rest of the package usable. Client-specific layouts are rejected instead of being guessed.

compozy extension install ./acme-tools --allow-unverified --yes
compozy extension install git:https://github.com/acme/acme-tools@v1.2.0 \
  --allow-unverified --yes

Both managed and dev instances receive absolute PLUGIN_ROOT and PLUGIN_DATA paths. Managed data is stable across updates at <COMPOZY_HOME>/extension-data/<name>/; a dev instance is isolated at <COMPOZY_HOME>/extension-data/<name>@ws-<workspace-id>/. See Agent Plugins interoperability for the full mapping.

Trust and consent

Two things gate a published install: an operator policy and a per-request consent.

Human output prompts on --allow-unverified unless you pass --yes. Structured output requires --yes, so an agent cannot hide an interactive trust decision.

Deterministic failures:

Both consent failures are 422.

Curated installs download the feed-owned artifact, verify the catalog-pinned SHA-256 before extraction, and persist the catalog entry, archive digest, and extracted-tree checksum separately. Any digest failure aborts before the registry write, so no partial install survives.

A GitHub release may carry an <asset>.sha256 sidecar. When one exists the daemon verifies the archive against it and records digest_matched. That is an integrity fact only: it never raises registry_tier above unverified, never sets checksum_verified, and never removes the consent requirement.

Registry tier and digest verification are provenance signals, not safety guarantees.

Permission ceilings

Published installs (curated, github, git) run under the marketplace tier, whose Host API grants are limited to logs.read, memory.read, observe.read, session.read, skills.read, and tool.read. A published extension may declare more; anything outside the ceiling is dropped at grant time with a recorded diagnostic instead of silently succeeding.

Local-path installs and dev links carry no ceiling. Full detail: Extension Permissions.

Managed installs do not allow runtime dependency symlinks to escape the extracted extension root. If a packaged node_modules or runtime dependency symlink resolves outside that root, installation fails instead of copying content from the host filesystem.

Configure sources and trust policy

[extensions.trust]
# Operator policy for non-curated installs. Per-install consent still applies.
allow_unverified = true

[extensions.sources.github]
enabled = true
base_url = "https://api.github.com"

[extensions.sources.git]
enabled = true

[marketplace.catalog]
base_url = "https://raw.githubusercontent.com/compozy/compozy/main/catalog"
ttl = "1h"
timeout = "10s"

base_url accepts https or http; http logs an insecure-scheme warning. The GitHub client reads GITHUB_TOKEN from the daemon environment for authenticated release access and higher rate limits.

After changing policy, reconcile and inspect the daemon's apply record:

compozy config reload -o json
compozy config apply-history --limit 5 -o json

Full key reference: config.toml.

Search across sources

compozy extension search notes --sources curated,github --limit 20
compozy extension search notes --cursor <cursor>

Search fans out across the curated catalog and GitHub. A rate-limited or unreachable source degrades to cached-or-omitted results with a sources_degraded marker rather than failing the whole query. compozy marketplace search <query> --kind extension -o json returns the same catalog projection with installed state and trust fields.

List, inspect, and update

compozy extension list
compozy extension status hello
compozy extension provenance hello

list uses the daemon when it is running and falls back to the local registry when it is offline. It carries an Update column driven by the update_available projection, so a pending update is visible without asking for it. status and provenance require the daemon.

Both read the global installed set. A workspace-scoped dev instance is not part of it — read those through GET /api/extensions?workspace=<id>, through an agent caller whose session binds the workspace, or through compozy extension logs <name>. See Develop Extensions.

status returns registry and runtime truth together:

Apply updates:

compozy extension update hello
compozy extension update --all

Update targets extensions installed from a source with remote version metadata; local installs and dev links are not update targets. A successful update replaces the managed directory, updates the registry row and provenance, reloads runtime resources, and writes an extension.updated event.

A batch update stops at the first failing target without discarding earlier progress: the response is 200 and carries every completed item plus the failed one, whose status is failed with extension_update_failed. Targets after the failure are not attempted.

The runtime activation is the commit point. If the new version is active but CompozyOS cannot remove a staging directory or backup, the result is still status: "updated" with an extension_update_cleanup_failed warning naming the residual path.

Inspect and preview the kit

Use inventory to compare every resource shipped by the global installed extension with the records currently live in the daemon:

compozy extension inventory hello -o json

Portable inventory preserves the detected format and ingest diagnostics even when every MCP component was skipped. An empty live resource set is therefore distinguishable from a native empty extension.

Use preview before enable to calculate the same desired state without writing records, starting automation, launching a subprocess, or recording Network consent:

compozy extension preview hello -o json

Preview reports the publish set, agent-name conflicts, unbound environment names, automation that would start, and the current Network requirement digest. Resolve conflicts and bindings before the enable mutation.

Enable, disable, remove

compozy extension disable hello
compozy extension enable hello
compozy extension remove hello
compozy extension remove hello --global

Enable and disable require the daemon. Enable publishes the complete static kit, starts effectively enabled package automation, loads runtime behavior, and writes an extension.enabled event. Its result lists the automation definitions that became runnable. Disable removes the extension-owned live resources, stops runtime behavior, and writes extension.disabled.

When the manifest requires Live Network participation, an unconfirmed enable returns extension_network_confirmation_required with the current digest. Review it, then retry with --confirm-network-requirement <digest>. An update that changes the digest refuses before replacing the installed package and uses the same exact-digest confirmation flag.

Inside a workspace, remove unlinks a dev overlay and lets the published installation resume; --global removes the published installation. Removal deletes the managed install directory and registry row with rollback handling. Post-commit cleanup failure leaves status: "removed" with an extension_remove_cleanup_failed warning and a residual path — treat that path as cleanup debt, not as a live extension.

For an Agent Plugins installation, removal also deletes PLUGIN_DATA. If direct deletion fails, CompozyOS first renames the directory into the extension-data quarantine and reports the cleanup warning. If the quarantine rename also fails, removal fails and the extension remains installed.

Validate an Agent Plugins package

Validation detects the same format and component mapping as install without writing registry state or starting code:

compozy extension validate ./acme-tools -o json

The result includes format: "agent-plugin", would_ingest, and positioned issues. Use it before a local or git install to catch an unsupported schema or client-specific layout. Unsupported portable components appear as skipped issues rather than hiding the resources that can still be ingested.

For a valid package with two skills, two usable servers, and three skipped components, the shipped CLI reports:

Extension bundle validation
===========================
Status:   valid
Format:   agent plugin
Package:  acme.tools 1.2.0
Issues:   3

Would ingest
============
Kind        Name     Transport
----        ----     ---------
skill       release
skill       review
mcp_server  local    stdio
mcp_server  remote   streamable-http

WARN mcp:legacy-events:  sse transport is not supported
WARN mcp:malformed:  invalid mcp server entry
WARN skill:skipped:  name must match the directory "skipped"

Declare required environment

Extensions declare the environment variable names they need:

[extension]
name = "daytona"
version = "1.2.3"
min_compozy_version = "0.3.0-beta.1"
requires_env = ["DAYTONA_API_KEY", "DAYTONA_ORGANIZATION_ID"]

CompozyOS validates requires_env at install and status load. Diagnostics report names, never values. An unset or empty variable surfaces through missing_env in list, status, the API, and the settings page.

Bind required values through the instance-scoped Vault flow described in Extension secret bindings. Bindings survive an update of the same managed instance, while stale bindings remain visible but are never injected when the new manifest stops declaring that name.

Agent surfaces

Extension lifecycle is agent-manageable. The compozy__extensions toolset reaches the same services as the CLI:

Tools that execute author or extension code (build, dev, reload) are interaction-gated; publish is additionally open_world; validate is read-only. Deterministic denials include EXTENSION_SOURCE_FORBIDDEN, EXTENSION_APPROVAL_REQUIRED, EXTENSION_NOT_INSTALLED, and EXTENSION_VALIDATION_FAILED. Credentials never appear in tool inputs: the publish token is resolved server-side and registered for redaction.

Native dev and reload never build. Call compozy__extensions_build first and pass its generation_hash.

Extension-owned desired-state records are inspectable through compozy__resources_list, compozy__resources_info, and compozy__resources_snapshot. An extension declares the corresponding Host API methods in permissions.requires, such as resources/list, resources/get, and resources/snapshot.

Troubleshooting

Related references:

• Develop Extensions
• Publish an Extension
• Extension Permissions
• Extension Secret Bindings
• Agent Plugins Interoperability
• Extension CLI Reference
• Hook Declaration Format
• Unified Marketplace