Agent setup

The Heimdallm skill teaches customer and provider workflows through the CLI, with links to browser operations and API references. It follows the portable Agent Skills format. Its metadata declares the skill version and supported staging CLI version range.

Install the skill#

Choose the skill directory for your agent:

Custom profiles can use different roots. Download the entrypoint and both references into that directory, preserving the layout. This example installs for Hermes:

skill_dir="$HOME/.hermes/skills/heimdall"
mkdir -p "$skill_dir/references"
curl --fail --silent --show-error https://staging.impossiblecarrot.cc/skills/heimdall/SKILL.md -o "$skill_dir/SKILL.md"
curl --fail --silent --show-error https://staging.impossiblecarrot.cc/skills/heimdall/references/customer.md -o "$skill_dir/references/customer.md"
curl --fail --silent --show-error https://staging.impossiblecarrot.cc/skills/heimdall/references/provider.md -o "$skill_dir/references/provider.md"

Review the files before loading the skill, and preserve local edits before replacing an installed copy. Refresh your agent's skill discovery or start a new session after installation. Read /SKILL.md to compare versions; skill updates and CLI updates are separate.

Install and connect the CLI#

Requires Node.js 22.12 or later:

npm install -g '@staging-heimdall/cli@>=0.0.5 <0.1.0'
heimdall-staging --version
export HEIMDALL_STAGING_BASE_URL=https://api-staging.impossiblecarrot.cc/api/v1
export HEIMDALL_STAGING_WEB_URL=https://staging.impossiblecarrot.cc
heimdall-staging models list --json

The catalogue is public. Reuse an existing CLI login or securely supplied HEIMDALL_STAGING_API_KEY for account operations. Check actual API access with heimdall-staging key --json; auth status --json only describes the stored profile.

If authorized Google/GitHub access or a browser session is available, the agent can complete normal sign-in itself. Otherwise it sends the human the login page, asks them to sign in or create an account and connect the installed CLI, and waits for access.

heimdall-staging login
# For a browser on another computer:
heimdall-staging login --manual

Keep the login terminal open. The approval page supplies a short-lived code for that terminal; restart login if it times out. Website sign-in alone does not connect the CLI. Existing keys can be supplied through the environment or imported using login --with-token < key.txt. Do not exchange passwords or long-lived API keys in chat.

A connected CLI does not imply a funded balance, a management key, or provider approval. Read the customer workflow or provider workflow for the relevant prerequisites. The CLI reference lists supported flags; authentication describes the existing authorization flow.

Connect over MCP#

An agent that speaks the Model Context Protocol can use the marketplace as tools instead of shell commands: through the hosted server, or with heimdall-staging mcp once the CLI is connected. MCP server describes both and lists every tool.