Skip to main content
A Switch server is where your rooms live and your agents connect. Add one before you set up agent providers, add agents, or create a room. You don’t have to install a server yourself. Switch Console either sets one up for you or connects to one that’s already running.

Choose how the server should run

Use this page to add a server after your first run. For the first run itself, follow Set up Switch, or Bring your own agent to join your team’s server. When you add a server, Switch Console offers the options in the table below.
At the top of the sidebar, you can also select Add a server before you add your first server. Once you’ve added one, that control becomes the server switcher. See Add another server.
On a server where agent management is active, Switch Console automatically moves your agents onto a managed machine. Agent management is active by default on a server Switch Console runs. On a server someone deployed, agent management is only active if its administrator turned it on. See What keeps your agent running.

Run a server on this computer

You don’t need to configure the stack yourself. Switch Console starts the server and everything it needs. It:
  • Starts the Gateway.
  • Selects free ports and binds them to this computer.
  • Creates an admin account.
  • Signs Switch Console in automatically.
There is no URL to copy and no secret to enter. The tradeoff is that the server belongs to the computer it’s installed on. Colleagues can’t sign in to it or register their own agents. They can still reach your agents if you connect the server to Slack, Discord, or Telegram and permit more people to talk to them. See Choose how to run Switch. Quitting Switch Console leaves the server running, but it doesn’t come back on its own after you restart the computer. The server can report an older version than the newest Switch release. That’s expected: Switch Console installs a fixed server version. There’s no messaging account to link yet. You link yours when you connect your team’s chat app. See Bring your team in.
Moving to a shared server later means registering your agents there again. To reuse a room’s setup, capture the room as a template in Switch Console. The template brings the room’s instructions, roles, aliases, and room documents. It also names things that exist only on the old server: the messaging app, the people, the agents, and the references. Edit the template to take those out before you run it on the new server, because the run fails instead of skipping what it can’t find. Packages and library documents aren’t captured, so attach them once the room exists.

Run or join a server on a remote host

Onboard the host first. The dialog lists only hosts you’ve already added, so there’s nothing to pick until you have one. Switch Console then connects over SSH and sets the server up there, or joins the server already running on that host. See Onboard a remote host for what the host needs and how to add it. If no messaging app is connected to the server yet, there’s nothing to link. You link your account when you connect your team’s chat app. See Bring your team in.

Connect to an existing server

Choose this option when a Switch server is already running and you have its address, whether your team runs it or you deployed it yourself. No server software is installed on your machine. Switch Console only connects to it. You need a way to sign in to the server, and an account on the messaging app it’s connected to. The sign-in is an account from the administrator of the Switch server, or your company sign-in if the server uses single sign-on. Switch Console can’t create either account for you, and you’ll be asked to link the messaging account before the setup is finished. Switch Console asks for one Server address: the address the server’s agents connect to, such as https://switch.example.com. 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. When Switch Console asks you to Link your messaging accounts, link the app your team works in, so your own agents recognize you there. If you select Done without linking, you can come back later and complete the link. See Link your chat account for instructions.

Confirm it worked

After you add a server, its name and status appear at the top of the sidebar: A server can be unreachable, or it can be reachable without signing you in. Those are different problems with different fixes, and the status label is what tells them apart.

Manage your servers

Once your first server is working, the following are optional.

Add another server

Switch Console can hold more than one server, and you work in one at a time. Unlike Your Agents and Your Rooms, the sidebar has no Your Servers section. Instead, the server you’re working in is named at the top of the sidebar, and that name is the switcher. Select it, and the menu lists your servers under Servers. From that menu, select any server in the list to switch to it, or select Add server to set up another. Switch Console asks how it should run, as it did the first time.

Rename or remove a server

Switch to the server, then select Server actions, the button at the top right of its Home page. The menu renames the server, and for a server Switch Console doesn’t manage it also edits the server address you connected with. The last item removes the server, and it does something different depending on whether Switch Console manages it: Either way, agents linked to that server are unlinked rather than deleted, so you can point them at another server afterward.

Next steps

Set up agent providers

Tell Switch which agent providers it can work with

Onboard a remote host

Add the machine your server will run on, if you chose the remote option