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.

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

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, the CLI writes the local registry directly. 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 and status use the daemon when it is running and fall back to the local registry when it is offline.

Enable Or Disable

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

When the daemon is running, enable and disable reload the extension manager, rebuild the hook registry, and reconcile bundles. When the daemon is offline, the commands update the registry flag; the next daemon start applies the new state.

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 also reads GITHUB_TOKEN from the daemon or CLI 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

Install a specific version or asset:

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

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. AGH downloads the release archive into a staging directory.
2. The installer extracts the archive and locates extension.toml.
3. The installer accepts a manifest at archive root or inside one top-level directory.
4. AGH validates the manifest and computes the install checksum.
5. AGH moves the package to <AGH_HOME>/extensions/<name>.
6. AGH persists registry metadata: source tier marketplace, slug, registry name, and remote version.

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.

After install, restart the daemon to activate the new extension if it is already running.

Check For Updates

Check one marketplace extension:

agh extension update prompt-enhancer --check

Update one marketplace extension:

agh extension update prompt-enhancer

Check or update all marketplace-installed extensions:

agh extension update --all --check
agh extension update --all

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 prints a restart message.

Source Tiers And Marketplace Security

Extensions have one source tier:

Trusted tiers receive the actions and security grants requested by their manifests. Marketplace extensions are constrained to a read-oriented ceiling: memory.read, observe.read, session.read, skills.read, and tool.read. Host API actions are filtered to methods whose required capability fits that ceiling.

Troubleshooting

Related references:

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