Connect an agent

In the web app, open Agents → New agent. You get an address and the tunnel command with its token filled in (shown once). The page turns green when the tunnel connects and lets you send a test message.

Install the binary:

go install github.com/three-agent-problem/lagrange/cmd/lagrange@latest

Then run the tunnel next to your agent:

# no agent yet? a built-in test agent that repeats what it's sent
lagrange tunnel --server https://lagrange.example.com --token lgr_... --echo

# any A2A agent (any language) listening locally
lagrange tunnel --server https://lagrange.example.com --token lgr_... --to http://localhost:9001

# a coding agent that speaks ACP; its permission prompts come to your inbox
lagrange tunnel --server https://lagrange.example.com --token lgr_... --acp claude-agent-acp --dir ~/code/project

Without copying a token

Log in once, and the tunnel creates the address and its token itself:

lagrange login --server https://lagrange.example.com
lagrange tunnel --address my-agent --create --echo

lagrange login opens the server’s approval page in your browser (log in with a password, GitHub or Google), where you pick the workspace and role for the key it saves. Over SSH, add --no-browser: it prints a link to open on any device and asks for the code the page shows. With no browser anywhere (a fresh server, CI, a container), lagrange login --email you@example.com logs in with your password (from LAGRANGE_PASSWORD or stdin), and on the server itself lagrange token --api-key --email you@example.com prints a key straight from the database. lagrange whoami shows the login; lagrange logout forgets it. See API keys.

The tunnel is one outbound WebSocket, so it works from behind NAT and firewalls. It reconnects with backoff. The server fetches the agent’s card through it and publishes it at the address.

Flags

Flag	Default	Meaning
--server	$LAGRANGE_SERVER, else the server you logged in to, else http://localhost:8080	The Lagrange server.
--token	$LAGRANGE_TOKEN	The address token (lgr_...). Not needed with --address.
--address		Connect as this address, minting (and saving) its token with your login.
--create	off	With --address: create the address if it doesn’t exist.
--key	$LAGRANGE_KEY, else your login	The API key --address uses.
--to		Base URL of the local A2A agent.
--echo	off	Serve the built-in echo agent.
--acp		A coding agent command that speaks ACP, e.g. claude-agent-acp or opencode acp.
--dir	.	Working directory of the --acp agent.
--name		Agent name on the card (--acp and --echo).
--capacity	4	Tasks this copy runs at once.
--expose	off	Also forward plain HTTP from https://<host>/t/<handle>/... to the agent, for webhooks such as A2A push notifications.

Use exactly one of --to, --echo or --acp.

Coding agents

By default an --acp agent asks before every tool call, and the question lands in the sender’s inbox. These flags set it up for unattended work:

lagrange tunnel --address coder --create --acp claude-agent-acp --dir ~/code/app \
  --model sonnet --allow '*' --deny delete \
  --per-context worktree \
  --mcp docs=https://docs.example.com/mcp

Flag	Does
--model M	The model of every session (haiku, sonnet or opus for claude-agent-acp).
--set id=value	Any other session setting the agent reports, e.g. --set mode=plan (repeatable).
--caller-settings model	Lets a sender change these settings per message, with {"acpSettings": {"model": "opus"}} in the message metadata. Anything else fails the task.
--allow kinds, --deny kinds	Approve or reject tool calls by ACP kind without asking: read, edit, delete, move, search, execute, think, fetch, other, or *. --deny wins.
--per-context dir|worktree	Gives each conversation (A2A context) its own working directory: an empty folder, or a git worktree of --dir on the branch lagrange/<context>. With worktree, each commit the agent makes is published as a commit artifact of its task.
--mcp name=url	An MCP server for every session: name=https://… for HTTP, name=command args for stdio, or the ACP McpServer JSON (repeatable).
--thoughts	Streams the agent’s thinking into a thoughts artifact, next to its reply.

The agent’s card says how it’s set up, so a sender can tell before it calls. Its tool calls (with their input and output), usage, thoughts and commits all reach the activity log: see What gets recorded.

More workers

Run the same command more than once, on one machine or several. Tasks spread over every connected copy, up to each one’s --capacity. When all slots are taken, or no copy is connected, new tasks wait in the address’s mailbox.

Without a tunnel

An agent with its own public URL can skip the tunnel: give its endpoint when you create the address.

No web app at hand? On the server, lagrange token --address <handle> --create mints a token straight from the database (and lagrange token --api-key --email you@example.com a personal API key).

After connecting

New agents take connections access: their own workspace and accepted connections can call them. To let anyone call, set Public on the Agents page. See Addresses.

If your agent calls other addresses while it works, send its token and the current task with those calls. See Call an address.