Skip to content

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

docs(readme): put installing Switch Console right below the intro (#967)

Louis Amaudruzfcc55644657c
diff --git a/README.md b/README.md
index f69bdcf6b..905519055 100644
--- a/README.md
+++ b/README.md
@@ -37,6 +37,20 @@ Switch is the underlying infrastructure and framework that allows you to build t
<img src="assets/switch-overview.jpg" alt="Switch architecture — agents and platforms connected through Switch" width="860">
</div>
+## Get started in two steps
+
+1. **Install Switch Console**, the desktop app, for your platform.
+2. **Open it and talk to switch-buddy**, your own assistant in Switch. Tell it what you want: it creates your first agents and channels, helps you connect the chat app your team uses, and answers anything about Switch.
+
+| Platform | Install |
+| --- | --- |
+| macOS | [Apple Silicon](https://github.com/sandbox-quantum/switch/releases/latest/download/switch-console-arm64.dmg) · [Intel](https://github.com/sandbox-quantum/switch/releases/latest/download/switch-console-x64.dmg) |
+| Windows | [Installer](https://github.com/sandbox-quantum/switch/releases/latest/download/switch-console-x64.exe) |
+| Linux x64 | [AppImage](https://github.com/sandbox-quantum/switch/releases/latest/download/switch-console-x86_64.AppImage) · [DEB](https://github.com/sandbox-quantum/switch/releases/latest/download/switch-console-amd64.deb) |
+| Linux ARM64 | [AppImage](https://github.com/sandbox-quantum/switch/releases/latest/download/switch-console-arm64.AppImage) · [DEB](https://github.com/sandbox-quantum/switch/releases/latest/download/switch-console-arm64.deb) |
+
+See the [latest release](https://github.com/sandbox-quantum/switch/releases/latest) for all desktop builds.
+
## Watch it work
The same incident, in the apps teams already use. Someone reports checkout failing, an agent opens an incident channel, pulls the error rate and finds the deploy behind it — with a second agent doing the charting. Under a minute each, no narration.
@@ -124,9 +138,9 @@ Most tools in this space want to become the place your team works. Switch does n
Getting humans and agents to work as one team is the part nobody has solved yet. That is where our effort goes, rather than into rebuilding chat apps and coding agents that already work well.
-## Getting started
+## Docs
-### Let an agent walk you through the onboarding
+### Let an agent walk you through them
Rather than working through the documentation yourself, connect an agent to it
@@ -162,122 +176,10 @@ opencode mcp add
```
Then follow the procedure and provide `https://docs.switchagents.ai/mcp` as the MCP server URL.
+### Read them yourself
-
-### I want to try it out myself
-
-**Follow the [getting started guide](https://docs.switchagents.ai/switch-rooms/getting-started).**
-It covers the whole path properly. The short version:
-
-1. Download the Switch Console app for your platform and install it.
-2. Start a local server from the app.
-3. Add your first agent: a name, a working directory, and the provider you use.
-4. Create a channel and talk to it.
-
-| Platform | Download |
-|---|---|
-| macOS (Apple Silicon) | [.dmg](https://github.com/sandbox-quantum/switch/releases/latest/download/switch-console-arm64.dmg) |
-| macOS (Intel) | [.dmg](https://github.com/sandbox-quantum/switch/releases/latest/download/switch-console-x64.dmg) |
-| Linux (x64) — **early access** | [.AppImage](https://github.com/sandbox-quantum/switch/releases/latest/download/switch-console-x86_64.AppImage) · [.deb](https://github.com/sandbox-quantum/switch/releases/latest/download/switch-console-amd64.deb) |
-| Linux (arm64) — **early access** | [.AppImage](https://github.com/sandbox-quantum/switch/releases/latest/download/switch-console-arm64.AppImage) · [.deb](https://github.com/sandbox-quantum/switch/releases/latest/download/switch-console-arm64.deb) |
-| Windows (x64) — **early access** | [.exe](https://github.com/sandbox-quantum/switch/releases/latest/download/switch-console-x64.exe) |
-
-**Early access means the Windows and Linux builds of Switch Console are ready to use and still changing.** Expect rough edges, and behavior that can differ from one release to the next. When you hit one, [open an issue](https://github.com/sandbox-quantum/switch/issues) — a report is what moves it up the list. This is about the desktop app only: running a Switch server on Linux is the primary deployment path and carries no such label.
-
-
-### I want to deploy Switch for my team
-
-Read [hosting remotely](https://docs.switchagents.ai/switch-rooms/deploy/host-remotely).
-
-
-## Architecture at a glance
-
-
-### Switch Core
-
-```mermaid
-flowchart LR
- subgraph people["People"]
- slack["Slack"]
- teams["Teams"]
- discord["Discord"]
- telegram["Telegram"]
- mattermost["Mattermost"]
- end
-
- subgraph core["Switch Core"]
- collab["Collaboration Bridge"]
- rooms[("Rooms in PostgreSQL<br/>messages · media · LISTEN/NOTIFY")]
- agentbridge["Agent Bridge<br/>HTTP + SSE · MCP"]
- gateway["Gateway API"]
- end
-
- subgraph agents["Agents"]
- cli["CLI agents<br/>via Switch Console"]
- custom["Custom agents<br/>via Agent Protocol"]
- end
-
- dashboard["Operator Dashboard"]
-
- slack --- collab
- teams --- collab
- discord --- collab
- telegram --- collab
- mattermost --- collab
-
- collab <--> rooms
- rooms <--> agentbridge
- rooms --- gateway
- gateway --- dashboard
-
- agentbridge <--> cli
- agentbridge <--> custom
-```
-
-Switch Core is the infrastructure that joins your agents and your collaboration
-apps together.
-
-At its centre are rooms, held in PostgreSQL, where everyone meets. Every
-participant is a client of that store: people arriving through a bridged
-channel, agents connected through the Agent Bridge, and Switch's own services.
-
-**Agent Bridge.** Agents speak the Switch Agent Protocol: HTTP for what they
-send, SSE for what Switch pushes back, so they hear about a message as it
-happens. [Switch Console](console/) and the sidecar it deploys to remote hosts
-speak it for every CLI-based agent session they start: each session gets the
-Switch tools as a local MCP server and a skill that teaches it the room
-workflow.
-
-**Collaboration Bridge.** Each chat platform connects through its own adapter,
-with its own transport: Socket Mode for Slack, an HTTP listener for Teams, the
-gateway websocket for Discord, long polling for Telegram, a websocket for
-Mattermost. It relays both ways,
-maps each channel to a room, and gives every agent its own name and avatar in
-the channel.
-
-**Room Service and Gateway API.** The management layer: rooms, roles,
-instructions, permissions, attached knowledge and connected messaging apps. The
-Gateway API is the control plane behind the operator dashboard, and PostgreSQL
-holds the state.
-
-### Switch Console
-
-Switch Console is the desktop app on the other side of the Agent Bridge. It does
-three jobs.
-
-**It runs your agents.** Define an agent once with its name, working directory
-and provider, and Console handles its identity, credentials and sessions,
-including starting one automatically when somebody addresses it in a channel.
-Run it on your own machine, or on a remote host you own so it is there for your
-team around the clock.
-
-**It manages the everyday.** Connect your messaging apps, create channels and
-configure who and what is in them, without leaving the app. The operator
-dashboard covers the rest.
-
-**It runs your server.** Point it at your team's Switch server, or have it stand
-one up for you, on this machine or on a host you own, without you writing any
-Compose or Helm configuration.
+- [Getting started](https://docs.switchagents.ai/switch-rooms/getting-started): from your first agent to your first channel.
+- [Hosting remotely](https://docs.switchagents.ai/switch-rooms/deploy/host-remotely): deploy Switch for your team.
## Telemetry