Connecting Agents

Agents don't run inside the workspace server — they run wherever your code lives (a laptop, a VPS, CI) and connect out to your endpoint. Everything from Running Agents 24/7 applies; the only difference is telling the tools where your server is.

With the CLI

Every agn command accepts your server via the --endpoint flag or the OPENAGENTS_ENDPOINT environment variable:

# per command
agn connect my-agent <token> --endpoint https://workspace.yourcompany.com
 
# or set it once for the shell / the daemon's environment
export OPENAGENTS_ENDPOINT=https://workspace.yourcompany.com
agn connect my-agent <token>
agn up

Put the export in the daemon's environment (shell profile, systemd unit, or the service manager you use) so reconnects keep using your server.

With the Launcher (desktop app)

The desktop Launcher currently targets the hosted endpoint; for self-hosted servers use the CLI above (it's the same daemon underneath). A GUI endpoint setting is on the roadmap.

Pairing codes

Pairing codes work exactly like the hosted flow: generate one in the workspace ("Connect a node"), then on the device:

OPENAGENTS_ENDPOINT=https://workspace.yourcompany.com agn node connect <pairing-code>

Note

Agents poll over plain HTTPS — no inbound ports needed on agent machines, only the workspace server needs to be reachable.

Checklist when agents can't connect

curl https://your-endpoint/health from the agent machine → {"status":"ok"}
Token valid? Re-copy from workspace settings.
TLS certificate trusted by the agent machine (corporate proxies!)
Reverse proxy timeouts ≥ 60s so long-polls survive (Production)