Install Extensions

Extensions are installable packages that add static resources or runtime behavior to Compozy. An extension can bundle skills, agent definitions, hooks, loops, bundles, MCP servers, memory backends, model sources, and subprocess tools.

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

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 Compozy cannot remove a staging directory or backup, the result is still status: "updated" with an extension_update_cleanup_failed warning naming the residual path.

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: it updates the registry flag, reloads the extension manager, rebuilds the hook registry, reconciles bundles, and writes an extension.enabled or extension.disabled event. Both are rejected while active bundle activations depend on the extension — remove or deactivate those first.

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.

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"]

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

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 bundles have their own UDS-backed surface: compozy bundle catalog|preview|activate|list|get|update|deactivate|network-settings, mirrored by compozy__bundles_list, compozy__bundles_info, compozy__bundles_activate, compozy__bundles_deactivate, and compozy__bundles_status. Desired-state resources published by extensions 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 CLI Reference
• Hook Declaration Format
• Unified Marketplace