Install Extensions

Extensions are installable packages that add static resources or runtime capabilities to AGH. An extension can bundle skills, agent definitions, hooks, bundles, MCP servers, bridge adapters, memory backends, and subprocess services.

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

Extension lifecycle is agent-manageable. The agh__extensions toolset and the parallel agh extension CLI reach the same registry, marketplace, install, update, remove, enable, and disable services:

Tool mutations require approval and pass through the same source-trust filter as the CLI. Deterministic denials include EXTENSION_SOURCE_FORBIDDEN, EXTENSION_APPROVAL_REQUIRED, EXTENSION_NOT_INSTALLED, and EXTENSION_VALIDATION_FAILED. Marketplace trust roots and raw marketplace credentials stay on operator surfaces and are not exposed as tool inputs.

Every install records provenance and a trust report in the extension registry. The payload includes the source tier, slug or local path, checksum, checksum verification result, allow_unverified, the install actor, and deterministic diagnostics when capability or trust checks reject the package. The HTTP/UDS API, native tools, CLI, and settings page all surface the same trust decision.

Extension bundles have their own UDS-backed CLI surface. After installing an extension, agents can inspect and manage preset activations with agh bundle catalog, agh bundle preview, agh bundle activate, agh bundle list, agh bundle get, agh bundle update, agh bundle deactivate, and agh bundle network-settings. The same daemon service is exposed to agents through agh__bundles_list, agh__bundles_info, agh__bundles_activate, agh__bundles_deactivate, and agh__bundles_status. Desired-state resources published by extensions are inspectable through agh__resources_list, agh__resources_info, and agh__resources_snapshot; the old singular resource.read and resource.write capability names are not accepted.

Install From A Local Directory

A local extension directory must contain extension.toml or extension.json.

prompt-enhancer/
  extension.toml
  package.json
  dist/
    index.js

Install it:

agh extension install ./prompt-enhancer --allow-unverified

If the daemon is running, the CLI sends the path and checksum to the daemon over UDS. The daemon copies the directory into the managed extension root, persists the registry row, reloads extensions, rebuilds hooks, reconciles bundles, and returns the current status.

If the daemon is not running, local-directory install is allowed only with --allow-unverified --yes. That fallback writes the local registry directly and records allow_unverified=true in provenance. The extension is discovered on the next daemon start.

Declare Required Environment

Extensions that need process environment variables declare the variable names in their manifest:

[extension]
name = "daytona"
version = "1.2.3"
min_agh_version = "0.5.0"
requires_env = ["DAYTONA_API_KEY", "DAYTONA_ORGANIZATION_ID"]

AGH validates requires_env as environment variable names during install and status loading. Diagnostics report only names, never values. If a required variable is unset or empty, agh extension list, agh extension status, the API, and the settings page surface it through missing_env.

List And Inspect Installed Extensions

agh extension list
agh extension status prompt-enhancer

status returns both registry and runtime information:

list uses the daemon when it is running and falls back to the local registry when it is offline. status and provenance require the daemon so they can include runtime truth and trust evidence.

Enable Or Disable

agh extension disable prompt-enhancer
agh extension enable prompt-enhancer

Enable and disable require the daemon. The daemon updates the registry flag, reloads the extension manager, rebuilds the hook registry, reconciles bundles, and writes an extension.enabled or extension.disabled event.

Disabling is rejected while the extension has active bundle activations. Remove or deactivate those bundle activations first, then disable the extension.

Remove An Extension

agh extension remove prompt-enhancer

Removal deletes the managed install directory and registry row with rollback handling. Like disable, removal is rejected while active bundle activations still depend on the extension.

Configure Marketplace Installs

Marketplace settings live under [extensions.marketplace]:

[extensions.marketplace]
registry = "github"
# Optional. Empty uses the GitHub API default.
base_url = "https://api.github.com"

registry = "github" is the only accepted registry value today. base_url may use https or http; http logs an insecure-scheme warning. The GitHub client reads GITHUB_TOKEN from the daemon environment for authenticated release access.

Search Marketplace Sources

The CLI exposes a search command:

agh extension search prompt --limit 20

Current caveat: the built-in GitHub registry source supports release lookup and download, but it does not implement full-text search. A GitHub-only marketplace configuration can install a known slug, but search may return no results until a searchable source is configured.

Use --from when multiple marketplace sources exist:

agh extension search bridge --from github

Install From A Registry

Install a known marketplace slug:

agh extension install owner/repo --allow-unverified

Install a specific version or asset:

agh extension install owner/repo --version v0.3.1 --allow-unverified
agh extension install owner/repo --asset agh-extension-linux-amd64.tar.gz --allow-unverified

Registry flags are valid only for registry installs. If the argument is an existing local directory, --from, --version, and --asset are rejected.

Marketplace install flow:

1. The CLI, HTTP client, web app, or native tool sends the install request to the daemon.
2. AGH downloads the release archive into a staging directory.
3. The installer extracts the archive and locates extension.toml.
4. The installer accepts a manifest at archive root or inside one top-level directory.
5. AGH validates the manifest, computes the install checksum, and evaluates the trust report.
6. AGH rejects unverified checksums unless the caller explicitly sends allow_unverified=true.
7. AGH moves the package to <AGH_HOME>/extensions/<name>.
8. AGH persists registry metadata: source tier marketplace, slug, registry name, remote version, provenance, trust report, and diagnostics.
9. AGH reloads extension runtime resources and writes an extension.installed event.

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.

Use --allow-unverified --yes only when the operator intentionally accepts a package without a registry-verified checksum. Machine-readable output refuses --allow-unverified without --yes so agents cannot hide an interactive trust prompt.

Check For Updates

Check one marketplace extension:

agh extension update prompt-enhancer --check

Update one marketplace extension:

agh extension update prompt-enhancer --allow-unverified

Check or update all marketplace-installed extensions:

agh extension update --all --check
agh extension update --all --allow-unverified

Update only works for extensions installed from a registry with slug metadata. Local extensions are not update targets. A successful update replaces the managed install directory, updates the registry row and provenance, reloads runtime resources, and writes an extension.updated event. As with install, unverified updates require explicit --allow-unverified --yes.

Inspect Provenance And Trust

agh extension provenance prompt-enhancer

The provenance response is the audit record for the installed package. It includes the install source, registry tier, slug or path, selected version, checksum, checksum verification result, allow_unverified, install actor, install time, trust decision, warnings, and deterministic diagnostics. Use it before enabling a package from an untrusted source or when an agent needs to justify why an install was accepted or rejected.

Registry Tiers, Trust Reports, And Marketplace Security

Marketplace registry entries have one registry tier. Local and bundled extension sources still exist, but registry trust is recorded separately in the provenance payload.

Trust reports include decision, registry_tier, checksum_verified, allow_unverified, and warning diagnostics such as extension_checksum_unverified. Marketplace extensions are constrained to a read-oriented ceiling: logs.read, memory.read, observe.read, session.read, skills.read, and tool.read. Host API actions are filtered to methods whose required capability fits that ceiling.

If an extension requests capabilities outside its trust tier, the install returns deterministic diagnostics in the trust report instead of silently dropping the request. Operators can make an unverified checksum decision with allow_unverified, but capability ceilings still apply.

Troubleshooting

Related references:

• Develop Extensions
• Extension CLI Reference
• Hook Declaration Format
• Skills Marketplace