InitHub Marketplace

Browse the marketplace on the web: hub.initrunner.ai

InitRunner's InitHub Marketplace lets you browse, install, share, and discover community agent packs and roles. You can explore packages on the web at hub.initrunner.ai, or use the CLI to install from InitHub, OCI registries, and the community index. Roles are downloaded, validated, and saved to ~/.initrunner/roles/ where they integrate automatically with the CLI and dashboard.

Quick Start

# Install from InitHub (default)
initrunner install alice/code-reviewer
initrunner install alice/code-reviewer@1.2.0

# Install from an OCI registry
initrunner install oci://ghcr.io/user/my-role:latest

# Inspect a role (works with all source types)
initrunner info alice/code-reviewer
initrunner info oci://ghcr.io/user/my-role:latest

# Search InitHub
initrunner search "code review"

# Run an installed role by name
initrunner run code-reviewer -p "Review this code"

# List / update / remove
initrunner list
initrunner update code-reviewer
initrunner update --all
initrunner uninstall code-reviewer

Source Identifiers

The install and info commands accept flexible source identifiers:

Detection order: oci:// prefix selects OCI, everything else installs from InitHub. The hub: prefix is accepted but optional.

Install Flow

When you run initrunner install, the following happens:

1. Parse the source identifier into owner, repo, path, and ref.
2. Download the YAML file from the source (InitHub API or OCI registry).
3. Validate the file as a valid InitRunner role definition (reuses the same validation as initrunner validate).
4. Check dependencies declared in the role's metadata.dependencies and warn about any that are missing.
5. Display a security summary showing the role name, description, tools, model provider, and other features. Prompt for confirmation.
6. Save the role to ~/.initrunner/roles/hub__{owner}__{name}.yaml.
7. Record the installation in ~/.initrunner/roles/registry.json with source URL, ref, commit SHA, and content hash.

Namespace Strategy

Installed roles use flat namespaced filenames to prevent collisions between different authors:

~/.initrunner/roles/
  hub__alice__code-reviewer.yaml
  hub__bob__code-reviewer.yaml
  registry.json

Two different authors can publish roles with the same name. The dashboard and CLI display the human-friendly name and disambiguate when collisions exist (e.g. code-reviewer (alice) vs code-reviewer (bob)).

CLI Commands

install

Install a role from InitHub or an OCI registry.

initrunner install owner/name                         # from InitHub
initrunner install owner/name@1.0.0                   # specific version
initrunner install oci://ghcr.io/user/role:latest     # from OCI
initrunner install owner/name --force                 # overwrite existing
initrunner install owner/name --yes                   # skip confirmation

Before installing, the command displays a security summary:

  Role:        code-reviewer
  Description: Reviews code for best practices and bugs
  Author:      jcdenton
  Tools:       filesystem
  Model:       openai/gpt-5-mini

Install this role? [y/N]:

uninstall

Remove an installed role.

initrunner uninstall code-reviewer

Removes both the YAML file and the manifest entry.

search

Search InitHub for agent packs.

initrunner search "code review"
initrunner search python

Results are displayed in a table:

                        InitHub Packages
┌────────────────────┬─────────────────────────────────┬──────────────┐
│ Package            │ Description                     │ Tags         │
├────────────────────┼─────────────────────────────────┼──────────────┤
│ alice/code-reviewer│ Reviews code for best practices │ code, review │
│ bob/python-linter  │ Lints Python files              │ code, python │
└────────────────────┴─────────────────────────────────┴──────────────┘

info

Inspect a role's metadata and tools without installing. Works with all source types.

initrunner info hub:owner/name
initrunner info oci://ghcr.io/user/role:latest
initrunner info code-reviewer

Resolves the source and displays a summary table. Hub sources show package metadata (versions, downloads) and OCI sources show bundle manifest info:

        Role: code-reviewer
┌─────────────┬────────────────────────────────────┐
│ Field       │ Value                              │
├─────────────┼────────────────────────────────────┤
│ Name        │ code-reviewer                      │
│ Description │ Reviews code for best practices    │
│ Author      │ jcdenton                           │
│ Model       │ openai/gpt-5-mini                  │
│ Tools       │ filesystem                         │
│ Triggers    │ no                                 │
│ Ingestion   │ no                                 │
│ Memory      │ no                                 │
└─────────────┴────────────────────────────────────┘

list

Show installed roles.

initrunner list
initrunner list --installed

update

Update installed roles to the latest version.

initrunner update code-reviewer     # update a specific role
initrunner update --all             # update all installed roles
initrunner update                   # same as --all

The update process compares the remote version or digest against the stored value. If unchanged, the role is skipped.

Metadata Extensions

The role metadata section supports three optional fields for registry use:

metadata:
  name: code-reviewer
  description: Reviews code for best practices and bugs
  author: jcdenton              # role author
  version: "1.0.0"              # semantic version
  dependencies:                 # external dependencies
    - python>=3.11
    - ffmpeg

Options

All fields are optional and backwards-compatible — existing roles without these fields continue to work.

Dependency Checking

During installation, declared dependencies are checked:

• Binary dependencies (e.g. ffmpeg): checked with shutil.which(). A warning is printed if not found on PATH.
• Python version (e.g. python>=3.11): compared against the running interpreter version.

Dependency warnings do not block installation — they are advisory only.

Local Manifest

The registry manifest at ~/.initrunner/roles/registry.json tracks all installed roles:

{
  "roles": {
    "code-reviewer": {
      "source": "hub:alice/code-reviewer",
      "hub_package": "alice/code-reviewer",
      "version": "1.2.0",
      "local_path": "hub__alice__code-reviewer.yaml",
      "installed_at": "2026-02-10T12:00:00+00:00",
      "sha256": "abc123..."
    }
  }
}

The manifest is written atomically (write to .tmp, then rename) to prevent corruption.

Provider Overrides

When you switch a role's provider with initrunner configure, the override is stored in registry.json rather than modifying the installed YAML:

{
  "roles": {
    "code-reviewer": {
      "source": "hub:alice/code-reviewer",
      "hub_package": "alice/code-reviewer",
      "version": "1.2.0",
      "local_path": "hub__alice__code-reviewer.yaml",
      "installed_at": "2026-02-10T12:00:00+00:00",
      "sha256": "abc123...",
      "overrides": {
        "provider": "anthropic",
        "model": "claude-sonnet-4-6"
      }
    }
  }
}

Overrides survive hub updates, reinstalls, and --force re-installs. The installed YAML stays pristine. Use initrunner configure <name> --reset to remove the override and revert to the original provider/model.

The loader applies registry overrides before building the agent. The --model CLI flag takes higher priority than registry overrides.

Post-Install Adaptation

After initrunner install, the CLI runs a provider compatibility check. If the role requires an API key you don't have (e.g. the role uses provider: openai but OPENAI_API_KEY is not set), the CLI:

1. Lists all providers you have API keys configured for.
2. Offers one-step adaptation to a configured provider.
3. Stores the override in registry.json.

Pass --yes to auto-adapt non-interactively. The adaptation also checks effective embedding providers — if the role uses RAG or memory, the embedding provider's key is validated too.

OCI Registry

InitRunner supports publishing and installing roles via any OCI-compliant container registry (Docker Hub, GHCR, ECR, etc.):

initrunner install oci://ghcr.io/org/my-agent:1.0.0

OCI references use the oci:// prefix to distinguish them from other source types. For full details on authentication, bundle format, publishing, and security, see OCI Distribution.

Finding Packages

Use initrunner search to find packages on InitHub:

initrunner search "code review"
initrunner search python --tag automation

Or browse the web interface at hub.initrunner.ai.

Dashboard Integration

Installed roles appear automatically in the dashboard (initrunner dashboard). The agents page scans ~/.initrunner/roles/ alongside other directories and handles namespaced filenames:

• Names are displayed without the hub__owner__ prefix.
• When two installed roles have the same name from different authors, the display disambiguates them: code-reviewer (jcdenton) vs code-reviewer (adamjensen).

No additional configuration is needed — installed roles are discovered on startup.

Using Installed Roles

Installed roles can be run by display name, owner/name, or full path:

# Run by display name (resolves from installed roles)
initrunner run code-reviewer -p "Review this code"

# Run by owner/name
initrunner run alice/code-reviewer -i

# Validate an installed role
initrunner validate code-reviewer

# Full path also works
initrunner run ~/.initrunner/roles/hub__alice__code-reviewer.yaml -p "Review this code"

When two installed roles share the same display name from different authors, use owner/name to disambiguate.

Audit logging works normally — runs are logged by the agent_name from the role's metadata.

Error Handling

Security

• Downloaded YAML is validated with the same parser used by initrunner validate before being saved to disk.
• A security summary (tools, model, features) is displayed and confirmation is required before installation.
• Content integrity is tracked via SHA-256 hash in the manifest.
• Downloads are restricted to the InitHub API and OCI registries — no arbitrary URLs.
• The manifest is written atomically to prevent corruption from interrupted writes.