Connecting agents

The in-app Tokens page (#tokens / #connect) is now focused on one job — minting, inspecting, and revoking access tokens. Everything else that used to share that page (install snippets, MCP wiring, runner bring-up, multi-org guidance) is documented here so operators pick from one place and agents can be pointed at a stable URL.

For the underlying concepts — trust boundary, scope vocabulary, and secret grants — see the security model.

The four channels

Every client of a Runyard Hub uses one of these entry points:

All four authenticate with a bearer token minted in the app on the Tokens page (or via POST /api/tokens). Copy the value at mint time — the Hub never shows it again.

1. Install the client

The Hub serves its own client bootstrap so the CLI and MCP server always match the Hub's release:

bash <(curl -fsSL https://hub.example.com/install.sh)

The installer places runyard and runyard-mcp on PATH, asks for the Hub URL, and prompts for the token you copied at mint time. Node.js 18+ is required on the client host.

2. Wire every AI agent (MCP)

runyard mcp install --all detects and configures the MCP-capable AI clients already on the machine — no JSON editing — for Claude Code/Desktop, Codex, Cursor, Windsurf, Gemini, and VS Code. Target one client with --client <name>.

runyard mcp install --all

The install writes each client's own MCP registration file (Claude Desktop's claude_desktop_config.json, Cursor's mcp.json, etc.) and reuses the token saved by runyard login.

3. Drive the CLI

runyard login --url https://hub.example.com
runyard menu        # next-action menu
runyard run hello

Named remotes let one workstation talk to several deployments — see the CLI guide for the full command surface, remote switching, and the --json machine-readable output every command supports.

4. Call the HTTP API directly

curl -H "authorization: Bearer $TOKEN" https://hub.example.com/api/menu

The full surface is documented at <hub>/openapi.json, and generic agent orientation is at <hub>/llms.txt. The API guide covers pagination, event streams, and the run lifecycle in detail.

5. Stand up a runner

A runner is a worker process that registers with the Hub using a runner-scoped token, heartbeats, claims queued runs, and executes workflows. Mint a runner token on the Tokens page (preset: Runner) and export it:

RUNYARD_HUB_URL=https://hub.example.com \
RUNYARD_HUB_TOKEN=shub_... \
SMITHERS_RUNNER_TAGS=linux,node,git,shell,web,smithers \
runyard-runner

See installation for systemd units, sandboxing, and multi-host capacity.

Multiple orgs on one machine

Each org is its own Hub. To register the second one alongside the first:

runyard login --remote acme --url https://acme.runyard.example
runyard mcp install --all --remote acme

Its MCP tools install alongside the existing ones, namespaced runyard-acme-*, so there's no ambiguity when several Hubs are wired to the same AI client.

Shareable deep links

Every page, run, workflow, and artifact in the Hub has a stable URL. Click any 🔗 icon in the console to copy one — paste it into chat, docs, or a ticket and recipients land on the same view (still auth-gated). See deep links for the URL grammar.

Token hygiene

Prefer narrow scopes and short lifetimes. The Tokens page sorts by usage so never-used and stale (>30 days idle) credentials surface first — revoke those before minting new ones. See security for the full scope vocabulary and the secrets model.