# Connect ChatGPT to Swarm (OpenAI tunnel)

For AIs helping a person who wants to use Swarm from ChatGPT. ChatGPT runs in the cloud and cannot reach a Swarm on 127.0.0.1. OpenAI's Secure MCP Tunnel connects them: a small client on the Swarm machine dials out to OpenAI, and ChatGPT reaches Swarm's MCP through it. Nothing listens on the internet.

Status: proven with ChatGPT running a Swarm job (2026-10-11) on an earlier packaging of Swarm; the steps below are for the current box and are being re-tested. Report what fails.

## Three separate credentials (never put any of them in chat)

| Credential | What it does | Who makes it |
| --- | --- | --- |
| Swarm's model sign-in (ChatGPT plan) or API key | runs the workers' models | the person, see https://swarmagent.dev/llms.txt step 4 |
| OpenAI tunnel runtime key | lets the tunnel client connect to OpenAI | the person, in their OpenAI Platform organization (Tunnels: Read + Use) |
| Swarm AI key | lets the tunnel call Swarm's tools | Swarm's installer (`~/.config/swarm/ai-key`) |

## Steps

1. Install Swarm (https://swarmagent.dev/llms.txt steps 1-4).
2. The person creates a tunnel in OpenAI Platform settings (Tunnels), linked to their ChatGPT workspace, and a runtime key with Read + Use. They save the runtime key to a private file themselves (mode 600); you never see it.
3. Install OpenAI's `tunnel-client` (github.com/openai/tunnel-client, latest release for the machine's architecture; verify its digest).
4. Make a header file for Swarm's key, readable only by the user that runs the tunnel:

       umask 077; printf 'Authorization: Bearer %s' "$(cat ~/.config/swarm/ai-key)" > ~/.config/swarm/tunnel-header

5. Run it (as a systemd service for anything lasting):

       tunnel-client run \
         --control-plane.tunnel-id "$TUNNEL_ID" \
         --control-plane.api-key "file:$RUNTIME_KEY_FILE" \
         --mcp.server-url http://127.0.0.1:7783/mcp \
         --mcp.extra-headers "Authorization: file:$HOME/.config/swarm/tunnel-header" \
         --mcp.discovery-extra-headers "Authorization: file:$HOME/.config/swarm/tunnel-header" \
         --health.listen-addr 127.0.0.1:18787 --log.format json --log.level warn

   Both header flags are needed. Check `127.0.0.1:18787/readyz`.
6. In ChatGPT: add a custom MCP server, Connection = **Tunnel**, the tunnel ID, Authentication = **None** (the tunnel adds Swarm's key).
7. Prove it: from ChatGPT, ask for `swarm_status`, then a small finder job on a harmless question, and read its result.

Everyone allowed through that tunnel shares one Swarm key (write access: jobs, not administration). Revoke it by reinstalling the key (`install.sh connect-ai`).