Skip to main content

​
What you see

​
Connecting to a server

The form asks for one Server address: the address the server’s agents connect to. It flags a malformed address as you type. A well-formed address that’s wrong is accepted, and shows up later as Server unreachable.If Switch Console says the address answered with a web page, you’ve entered the address of a separate Gateway, not the server itself. Enter the server’s own address instead, often the same host on port 8000. Get it from the administrator of your Switch server. See Add a server.
You get the same message whether the address is wrong or the server is down. Confirm the address before you investigate the server.
Opening the Gateway in a browser doesn’t prove Switch Console can reach it. The web app uses the browser’s own connection, so the Gateway can look healthy while Switch Console times out.
The server’s connection to that messaging app isn’t running. You see Bridge is not running — start it before searching its directory or Bridge is not running — cannot look this account up when you link your messaging account. Your messaging account isn’t the cause, so linking again gives the same message.The administrator of your Switch server can get it running again. On a server Switch Console runs for you, that’s you:
  1. Restart the server. The server’s connections to messaging apps start with it. On a server Switch Console runs, go to the server’s page in Switch Console and restart it there.
  2. If the connection still isn’t running, its credentials no longer work. The app may have been uninstalled on the messaging platform, or its token revoked. Fix it one of these ways:
    • On a team server, for a connection registered by pasting in a token: An admin can give it new credentials and keep its rooms. See Change or replace a connection.
    • Otherwise, including on a server Switch Console runs: Disconnect the app and connect it again.
Disconnecting a messaging app deletes every Switch room on that app, with its history, and can’t be undone. Try the steps above first.
The server is older than your Switch Console needs. Switch Console updates when you accept an update, but a server your team deployed stays on the version it was deployed at.The error usually names a field rather than a version. For example, creating an agent fails with Extra inputs are not permitted when Switch Console 0.40 is connected to a server older than Switch 0.31.0.Ask the administrator of your Switch server to upgrade it. Each Switch Console release needs the server release it was built with, or a later one. The Switch Console entries in the changelog name the server release each one needs. For what an upgrade means for anyone still on an older Switch Console, see Pin a version.A server Switch Console runs for you is updated like this:
  • On your computer: It gets the matching release each time Switch Console starts it.
  • On a host you’ve onboarded: It’s updated the same way, unless another Switch Console, including your own on a second computer, has used it in the last 14 days. In that case, Switch Console waits for you to start the update, because updating pauses everyone’s agents on that server for about a minute.
You’re signed out. Your agents are still listed, and so is any room a live session is in. Those rooms show an identifier rather than a name, which is usually the first thing you notice.Switch Console shows that you’re signed out in several places:
  • The server’s status label reads Signed out.
  • Its Home page reads Not signed in.
  • The sidebar shows a Sign in to <server> to see its rooms bar with a Sign in link.
  • Your Rooms is empty, with the same line.
Sign in again from the server. Whether that’s a password or single sign-on depends on how your server was set up.
Usually a network change Switch Console didn’t follow, such as a VPN reconnect. Your sign-in stays valid and the Gateway still answers, so nothing else looks wrong.Switch Console recovers by itself, usually within a minute of the network coming back. To fix it at once, restart Switch Console.

​
A server on your computer

These apply to a server Switch Console runs for you on your computer.
Only the bundled Mattermost needs Docker. Without Docker, the server runs normally but has no bundled chat app, and Switch Console doesn’t flag that anything was skipped.If you don’t have Docker, get a chat app one of these ways:
  • Add the bundled Mattermost: Install and run Docker, then start the server again.
  • Connect Slack, Discord, or Telegram instead: These connect outward from the server, so they work on a laptop that nothing can reach from outside. See Connect a messaging app.
On Linux, if Docker is installed but Switch Console can’t reach it: a common cause is that you aren’t in the docker group, because only its members can reach Docker. Switch Console may report this as the Docker daemon not running and suggest starting Docker Desktop, but check your group membership first. Check with id, and add yourself if docker isn’t in the list:
Anyone in the docker group can get root on that machine. Add only accounts you’d give root to anyway.
Group membership takes effect when a login session starts, so log out and back in, then check again:
If docker still isn’t listed, or a systemd --user process outlived the logout, restart the computer before you open Switch Console again.On Linux, if Switch Console says Docker isn’t installed when it is: Switch Console also needs the Docker Compose plugin, and reports Docker as not installed without it. The details it shows name Compose. Install the plugin, then start the server again. Switch Console checks for Docker each time, so you don’t need to restart it.
Switch Console signs you in to Mattermost for you, so you don’t need a password to use it inside Switch Console.To open Mattermost in a browser, go to the server’s Home page, and under Messaging apps, open the menu on the Mattermost row and select Sign-in details…. Sign-in details… shows the address, username, and password to use, with a button that opens Mattermost.
You already have a Gateway account, and Switch Console opens the Gateway for you, signed in. Switch Console created the account and keeps its password, so there’s no address or password to look up. To open it, with the server running, go to Home in Switch Console and select Open beside Full admin interface.On a team server someone deployed, ask them for the Gateway’s address and an account.

​
Getting an agent running

If an agent doesn’t answer in a room, see When an agent doesn’t answer.
Switch Console reads your PATH once, when it starts. If installing the provider added a folder to your PATH, as a first Homebrew install or a version manager can, Switch Console doesn’t look there until you restart it.A provider installed to ~/.local/bin shows up when you select the refresh icon, with no restart. For any other folder, quit Switch Console completely and open it again:
This applies to agents Switch Console runs. A managed agent’s machine reports a reason code instead. See Your agent couldn’t create an agent.Switch Console raises Session did not start when a session never reports itself. The session is most likely waiting on a confirmation in the agent provider’s own command line.Read the message as a guess, not a diagnosis. It names two possible causes, a workspace-trust confirmation or a permissions one, because Switch Console can see only that nothing came back. Folder trust is the more common one, but the two look the same from Switch Console and need the same thing from you.Open that session’s terminal and answer what’s on it. The session never started, so there’s no agent in the room to ask, and Switch Console can’t answer the prompt for you.If this keeps happening, check the auto-trust setting. At the bottom of the sidebar, select Settings, then General. Auto-trust worktree directories is on by default, and it writes the trust entry for Claude Code, Codex, and Cursor before the session launches.
When your agent can’t create an agent, Switch creates nothing and your agent tells you why. Fix the issue and ask again.
Switch Console has probably moved your agent onto a managed machine. On a server with agent management active, it does that by itself, and a managed agent’s sessions aren’t listed in Switch Console.To check, open your agent’s page: a managed agent shows on followed by its machine’s name at the top.Your agent keeps answering in its rooms. Any turn that was in progress when it moved was cut, and the room is told to send the request again.After a move, check your agent’s page against how you had it set, because some advanced settings may not carry over and nothing tells you which. See When your agents move to a managed machine.If your agent answers but can’t reach files it used to work on, check the machine named on its page. The automatic move keeps an agent on the same computer, so a different one means it was created or moved there. See Your agent can’t reach its files.
Switch Console passes your agent only a fixed set of environment variables, not everything in your shell. Your own MCP servers still load, and gh auth login still applies. But an API key or other variable an MCP server reads from your shell doesn’t reach the MCP server.To fix it, set the value in the MCP server’s own configuration, such as its env block:
  • Put it in your user-level configuration, not a project file you might commit.
  • Write the value itself. A ${VAR} reference there reads the same environment the variable is missing from.
Your agent probably runs on a different computer from the one its files are on. An agent created on another machine, or moved to one, has only what that machine has. Its working directory, provider sign-in, git credentials, SSH keys, and environment variables stay on your computer. It can still read the room and answer there.To see where your agent runs, check its page for on followed by the machine’s name, or see the Gateway’s Machines list. Then find out where its files are:
  • The files are on that machine: For a managed agent, change its Directory to point at them. For an agent Switch Console runs, register a new one with the right directory. See Rename or move the agent.
  • The files are on that machine and your agent still can’t read them: The machine may run each agent as a separate user, and those users can’t reach home directories. Ask whoever set up the machine where agents’ files should go.
  • The files aren’t on that machine: If your agent should run there, put the files there. Switch doesn’t copy your repository for you. See Run an agent on the host. If it shouldn’t, create the agent on the computer where the files are.
In each case, your agent needs its own provider sign-in and credentials on the machine it runs on. If you don’t own the agent, ask its owner to make the change.
Switch posts in the room that your agent’s machine is offline or reconnecting, and names the machine. Your agent runs on a managed machine, so opening Switch Console won’t help.Check that the machine is on and that its agent controller is running. The Gateway’s Machines list shows each machine’s state. Once the machine reconnects, your agent answers when it’s next addressed.
Each time your agent needs permission, its session stops and waits for you. The request appears in the room, and it’s easy to miss when you’re working elsewhere.In Switch Console, open your agent’s page from Your Agents, and under General, check that Auto mode is on. With it on, the agent’s provider decides which actions run without asking, and the agent asks only about the rest. On Antigravity, the agent still asks before commands, and on Cursor, before everything.To stop the agent from asking at all, turn on Bypass permissions. Turn it on only for an agent you trust to work unattended in its directory. See Working safely with agents.Either change reaches a running session when it finishes its current turn. See Let the agent act without asking.If your agent went quiet after you declined a request, see The agent is waiting for a response.

​
Running Switch Console on Linux

Switch Console is running under Wayland with nothing drawn. There’s no error and no crash. It happens most often in a virtual machine.End the process that has no window, then start it under X11 instead:
Closing the window leaves Switch Console running, and the next launch reuses that process. Changes you made on the machine in between don’t take effect, because nothing restarted.End it before you launch it again:
Switch Console can’t reach the desktop secret service, so it stops saving your sign-ins. It won’t fall back to anything less protected, so it stores nothing.On GNOME, name the backend rather than leaving it to be detected:
The fixes above are command-line flags, so they apply only to the launch you typed them into. Starting Switch Console from the applications menu or the dock runs it without them.To make a launcher that includes the flags, copy the entry the package installed and edit your copy. A copy in your home directory takes precedence over the system one and survives an upgrade:
Then add the flags you need to the Exec line in the copy, before the trailing %U:
Copy and edit rather than writing an entry from scratch. The installed entry includes the values that let your desktop match the running window to its launcher, and an entry written by hand without them opens a second dock icon.