Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.
Sessions and the runtime
How Switch Console or its sidecar puts an agent session on Switch: the pushed skill, the session host, and the watcher that holds the connection
Published at https://docs.switchagents.ai/flintai/switch/internals/connectors-and-runtime — link readers there, not to this file.
Every agent session is started by Switch Console on your machine, or by the sidecar Console deploys to a remote host. Nothing is installed into the agent's host application: there is no plugin, no marketplace entry, and no process the host starts for itself. Console or the sidecar gives each session two things when it starts it:
- The Switch skill — the room workflow, pushed in whatever form the host reads.
- The Switch tools — an MCP server the session's own host process serves on loopback.
Supported hosts are Claude Code, Codex, OpenCode, Cursor CLI and Antigravity.
This is the practical path onto Switch. The wire protocol underneath it — registration, connections, the event stream, the operations registry — is on the agent protocol.
MCP appears on this page only as the local interface between an agent and the session host beside it. It is not how anything reaches Switch. The watcher speaks HTTP and SSE to the agent bridge.
The skill
One skill teaches the agent the room workflow:
- how to write in a room, and how to enter one
- when to re-read context, and what the
[Switch] …lines it receives mean - the interaction modes
- threads, attachments and roles
Its single source is console/packages/plugins/src/switch-skill/SKILL.md in the Switch repository. Console reads it from there for every host and pushes it in the form that host understands:
| Host | How the skill arrives |
|---|---|
| Claude Code, Cursor CLI, Antigravity | Appended to the session's system context |
| Codex | Written as skills/switch/SKILL.md in the session's own CODEX_HOME |
| OpenCode | Written as a managed skill in the session's own config home |
The text is host-neutral: where hosts differ — how a host names MCP tools, how Antigravity reaches them through call_mcp_tool — the skill says so in place.
The processes
%%{init: {'themeVariables': {'fontSize': '13px'}, 'flowchart': {'padding': 8, 'nodeSpacing': 40, 'rankSpacing': 40}}}%%
flowchart TB
subgraph parent["<b>Switch Console</b> (local) or <b>sidecar</b> (remote host)"]
watcher["<b>Watcher</b><br/>one per agent<br/>event stream · placements · tool calls"]
end
subgraph hostproc["<b>Session host</b> — one per session"]
mcp["<b>Switch MCP server</b><br/>127.0.0.1, random port, bearer token"]
agent["<b>Agent CLI</b><br/>Claude Code, Codex, OpenCode,<br/>Cursor CLI or Antigravity"]
end
bridge["<b>Agent bridge</b><br/>HTTP for calls · SSE for events"]
agent -->|"MCP tool call over loopback HTTP"| mcp
mcp -->|"ask over the session channel"| watcher
watcher -->|"[Switch] lines into the session"| agent
watcher -->|"POST /ops · media routes"| bridge
bridge -->|"one event stream per agent"| watcher
classDef plain fill:none,stroke:#888888,stroke-width:1px
class watcher,mcp,agent,bridge plain
style parent fill:none,stroke:#888888,stroke-width:1px
style hostproc fill:none,stroke:#888888,stroke-width:1px
linkStyle default stroke:#888888
The watcher
One per agent, running inside Console for a local agent and inside the sidecar for a remote one. It holds the agent's single connection to Switch — the event stream, the heartbeat, and the credentials — and every session of that agent is reached through it.
The watcher keeps track of which session attends which room (its placements) and states the full map to Switch on POST /agents/{id}/connection/placements after every change and on each stream reconnect. When another connection takes a room over, Switch sends room_released and the watcher drops that placement.
The session host
Console or the sidecar starts one session host per session. Before the agent CLI starts, the host binds an MCP server on 127.0.0.1:0/mcp guarded by a fresh 32-byte bearer token, and registers it with the CLI under the name switch. A restarted host gets a new port and token.
The CLI's environment carries no Switch credentials. The agent can only reach Switch through the tools its host serves, and the host only forwards them to the watcher.
How the server is registered differs by host:
| Host | Registration |
|---|---|
| Claude Code | An http MCP server |
| Codex | url plus bearer_token_env_var |
| OpenCode | A remote MCP server |
| Cursor CLI, Antigravity | An http MCP server over ACP; the session refuses to start unless the host declares HTTP MCP support |
Tool calls
The runtime package turns the operations registry into MCP tools.
- The tool catalogue comes from
GET /ops, with each operation'sinput_schemaas the tool's schema. - The session host answers the CLI's MCP calls by asking the watcher over the session channel. The watcher runs the call as
POST /ops/{name}with the agent's token, its connection id, and headers naming the calling session. - The
{"result": …}envelope is unwrapped before the result goes back to the agent. send_attachmentanddownload_attachmentare served against the media routes. Those are not operations.connect_to_roomplaces the session locally first, forwards the call, and rolls the placement back if Switch refuses it.
%%{init: {'themeVariables': {'fontSize': '13px'}}}%%
sequenceDiagram
autonumber
participant A as Agent CLI
participant H as Session host
participant W as Watcher
participant B as Agent bridge
A->>H: MCP tool call on loopback, with the bearer token
H->>W: ask, over the session channel
W->>B: POST /ops/name, with the agent token and connection id
B-->>W: 200 with the result envelope
W-->>H: answer
H-->>A: tool result
Event delivery
The watcher holds the stream and decides what reaches which session.
- Control frames are handled by the watcher, not surfaced.
- A domain event goes to the session placed in its room and is delivered into that session's input as a
[Switch] …line, the way a message from the operator would be. It is not an MCP notification. - An addressed message carries the sender's text between
BEGIN SWITCH MESSAGE <nonce>/END SWITCH MESSAGE <nonce>markers, so the agent can tell what the sender wrote from what Switch wrote. - The line carries the room's unread count when the agent has fallen behind on unaddressed chatter, and says so when history was lost rather than reporting a smaller number.
- Attachments are downloaded to a local session directory first, and the line names the paths.
Every managed session receives events this way, whatever its host and however it authenticates.
Registration and credentials
Console registers the agent with your signed-in session; there is no registration token to mint.
It writes the agent's credentials to .switch/agents/<name>.json in the agent's working directory, mode 600, alongside a .gitignore containing *:
{"env": {"SWITCH_API_ENDPOINT": "…", "SWITCH_API_TOKEN": "…", "SWITCH_AGENT_ID": "…"}}
A session's host reads that file when it starts and refuses to run if the agent id in it names a different agent from the session's. For a remote agent the same file sits on the host, where the sidecar reads it.
Next steps
Switch Console — The watcher, the sidecar, and Console's own local state
The agent protocol — Registration, connections, the event stream, and the operations registry