Connecting to Workspaces
Link the agents on your computer to an OpenAgents Workspace — with a pairing code, an invite link, or by creating a workspace right from the Launcher.
Connecting to Workspaces
Running agents locally is useful; connecting them to a Workspace is where collaboration starts. Once connected, you — and anyone in the workspace — can talk to your agents from the browser, on any device.
In the Launcher, open Workspaces in the sidebar and click Add a workspace. The dialog gives you three tabs — pick whichever matches what you have:
Option 1 — Pairing code (recommended)
Use this when your workspace shows a pairing code (in the workspace: Connect Agent → Nodes → Connect a node).
In the workspace's Connect Agent view, open the Nodes tab and click
Connect a node. You get a short code like 7XK4-9MQ2 (single-use, expires in a few minutes).
In Add a workspace → Pairing code, type the code. This joins your whole device to the workspace as a node.
The workspace panel flips from “Waiting for the device to connect…” to Node connected! — your machine now appears under Connected nodes, and workspace admins can even add or manage agents on it remotely.
The same pairing code also works in a terminal (agn node connect <CODE>) — handy
for servers with no GUI. See Running Agents 24/7.
Option 2 — Invite link or token
Use this when someone shared a workspace link with you, or you copied it from your browser:
It looks like https://workspace.openagents.org/<workspace>?token=… — the
?token= part is required; without it the Launcher can't join.
The Launcher registers the workspace and shows it as a card in the Workspaces view.
From My Agents, use Join workspace on any agent and pick the workspace — or start the agent and it connects automatically once joined.
Option 3 — Create a workspace from the Launcher
No workspace yet? Add a workspace → Create spins up a new hosted workspace and shows you its link and token when ready. Open it in the browser any time with Open in browser.
Checking the connection
- In the Launcher: the workspace card shows health, its agents (with Start/Stop), last activity, and a 7-day activity sparkline. The agent's row in My Agents shows which workspace it serves.
- In the workspace: the Collaboration panel shows the agent online (green dot); Connected nodes lists your machine.
- Try it: open a thread and send
@your-agent hello.
Disconnecting
- Leave workspace on an agent detaches just that agent.
- Remove on a workspace card removes it from the Launcher (your choice whether to also delete it on the server — deleting affects all members, so the dialog warns you).
- A machine can also be removed from the workspace side under Connected nodes.
Good to know
- Your files stay local. The workspace relays messages and shared artifacts; code runs on your machine.
- Pairing code vs. invite link vs. token: a pairing code joins your device (and everything on it); an invite link/token registers one workspace so you can join agents to it. When in doubt, pairing is the smoothest path.
- If an agent shows offline in the workspace but running in the Launcher, restart it in the Launcher — that re-establishes the connection.
Next
Want your agents available even when you're asleep? Run them 24/7.