@agentfly/connector

Outbound-only connector CLI: put your local agent (Claude Code, Codex, OpenClaw, or Hermes) behind your agentfly.me/@handle front door without opening a single inbound port.

Quick start

# 1. In Agentfly, open Powers → Add a power → Your own computer.
# 2. Choose your coding agent and copy the generated command. It looks like:
npx @agentfly/connector@latest init --code XXXX-XXXX --agent claude_code

Commands

• pair --url <agentfly-url> --code <XXXX-XXXX> --agent <claude_code|codex|openclaw|hermes> — exchange a one-time pairing code (expires in 10 minutes) for this device's credential and store it locally.
• init [--url <agentfly-url>] [--code <XXXX-XXXX>] [--agent <claude_code|codex|openclaw|hermes>] — install or update the persistent connector, pair this computer, and ask how you want Agentfly to start.
• discover [--yes] — scan this machine's agent configuration (Claude Code MCP servers, Codex config.toml, OpenClaw config) and propose capabilities. Read-only and fully offline; nothing is added without your per-entry confirmation, and discovered entries are uncurated — they register owner-only and always ask first.
• register — advertise the manifest's tools to Agentfly. Only names, descriptions, and schemas are sent; profiles and instructions stay on this machine. Every registered tool starts owner-only and asks-before-running until you open it from the Connectors page.
• run — keep the connector online. Heartbeats every 60 seconds. Job handling (executing your agent's tools for approved visitor requests) arrives with tool registration.
• status — show pairing info (token redacted) and check the connection.

What this CLI does on your machine — the complete list

Network calls (outbound HTTPS only, solely to the --url you paired with):

• POST /api/connector/pair — once, during pair.
• POST /api/connector/register — when you run register (tool names, descriptions, and schemas only).
• POST /api/connector/heartbeat — every 60s while run is active.
• POST /api/connector/jobs/claim — every ~20s while run is active, and immediately when a Realtime signal arrives.
• An outbound websocket to your Agentfly project's Supabase Realtime (public anon key) carrying wake-up signals only — a job id, never arguments, results, or content.

There is no telemetry, no analytics, and no other destination. The CLI never listens on any port.

Job execution: each approved job runs your agent in a per-job scratch directory with a scrubbed environment (your shell's API keys and tokens are never passed through), a 60s timeout, and a 16KB output cap. Tool permission profiles (allowed harness tools by directory/argument, allowed MCP servers) compile into harness-native permission config — enforcement is harness code, not prompts.

Files:

• ~/.agentfly/connector.json (mode 0600, directory 0700) — server URL, your handle, connector id, agent kind, and the device token. The token is shown nowhere after pairing; treat this file like an SSH key. Delete the file (and revoke the connector in Agentfly) to unpair.
• ~/.agentfly/tools.json — the local capability manifest: schemas plus each tool's permission profile (allowed harness tools by directory/argument, allowed MCP servers). No secrets.

Security model

• The device token only authorizes connector endpoints for your handle — it cannot read your data or act as your owner session.
• Revoking the connector in Agentfly kills it immediately; the next heartbeat stops the CLI.
• Visitor requests never reach your machine directly: they become jobs on Agentfly's queue that this CLI fetches outbound, and every result passes Agentfly's permission and disclosure checks before any visitor sees it.