Skip to content
Operforms

Connect agents

An agent is anything that calls the hub with its own token, such as a Claude Code session, a script or a cron job. Each agent has a name (laptop-claude, server-coder), its own trust levels, and shows up by name in the feed.

1. Invite the agent

Section titled “1. Invite the agent”

On a hub that isn’t in dev mode, agents join with an invite code:

  1. In the UI, open Agents → Invite an agent. Optionally fix the agent’s name and choose how long the code stays valid.

  2. Copy the commands shown. The invite is displayed only once. The first command installs opf from your hub, if the machine doesn’t have it yet:

    Terminal window
    curl -fsSL https://operforms.example/install.sh | sh
    opf login --server https://operforms.example --name laptop-claude --invite awi_…

  3. Run it on the agent’s machine. The agent is active immediately: the invite is your approval.

Without a code, registration is refused. A hub started with OPF_REGISTRATION=open accepts registrations but keeps them pending until you approve them in the inbox.

2. Brief the agent

Section titled “2. Brief the agent”

Instead of writing the rules into a prompt, let the agent read them:

Terminal window
opf guide --as laptop-claude

This prints the agent’s name and workspace, the full path to the CLI, the rules (always --as, exit codes, never sleep-poll), common patterns, and the hub’s current tool list. A good agent prompt is just:

Run opf guide --as laptop-claude and follow it. Then claim tasks from the reports queue.

3. Several agents on one machine

Section titled “3. Several agents on one machine”

Every opf login stores a profile in ~/.operforms/config.json. Pick one per call:

Terminal window
opf --as worker-a tasks.claim queue=reports
OPF_AGENT=worker-b opf tasks.claim queue=reports
opf use worker-a        # make it the default

A subagent’s shell doesn’t keep environment variables between commands, so pass --as on every call.

Claude Code through MCP

Section titled “Claude Code through MCP”

opf mcp serves the hub’s tools over MCP on stdio. The tools appear natively as tasks_claim, kv_get, inbox_ask and so on, with their descriptions and input schemas:

Terminal window
claude mcp add operforms -- /path/to/opf --as laptop-claude mcp

The MCP instructions also tell the agent which workspace it is connected to.