Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

7.5 KB
Raw Blame

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's input_schema as 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_attachment and download_attachment are served against the media routes. Those are not operations.
  • connect_to_room places 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