Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.
Running Switch locally for development
This covers the local-development path only: everything runs on your own
machine, with hot-reload on the backend and the frontend. It's a different
shape from the two paths the published docs cover —
standalone (single Docker Compose stack,
built images, no host toolchain) and the Helm chart — so don't reach for
those commands here; just standalone-up runs a whole different set of
containers and none of what follows applies to it.
Everything below is one recipe per just line, all defined in the root
justfile. Run just with no arguments any time to see
the full list.
Prerequisites
Docker, uv,
just (brew install just), and Node for the
gateway frontend.
just init-env # first-time setup — generate .env with random secrets
uv sync # install Python dependencies (core/)
just gateway-install # install gateway frontend deps (first time only)
just init-env copies .env.example to .env and fills every secret field
that ships blank — DB_PASSWORD, DB_OWNER_PASSWORD,
AGENT_REGISTRATION_TOKEN, GATEWAY_ADMIN_PASSWORD,
MATTERMOST_ADMIN_PASSWORD, MATTERMOST_USER_PASSWORD — with a freshly
generated openssl rand -hex 24 value, sets SECRET_KEYS to one generated
key (local:<64 hex characters>), then prints the gateway admin login
it just set. The fields ship blank on purpose: it means no default
credential (the old admin/admin) can ever reach a running stack by
accident. The recipe refuses to touch an existing .env, so re-running it
never rotates secrets out from under a stack that's already up — delete
.env first if you actually want to regenerate everything. just loads
.env automatically for every recipe below (set dotenv-load := true in
the justfile), so nothing else needs to source it.
An .env from before SECRET_KEYS existed makes just run fail at startup
naming the missing setting. Add SECRET_KEYS=local:$(openssl rand -hex 32)
(the generated value, not the command) and leave JWT_SECRET_KEY as it is:
the first boot re-encrypts what it encrypted, and it keeps your current login
valid. key-rotation.md explains both.
Two database roles, not one
.env carries two sets of Postgres credentials, because row-level security
is inert against the role that owns the tables it protects — Postgres
exempts a table's owner from its own policies. DB_USER / DB_PASSWORD name
the runtime role: a plain, unprivileged login that switch-core
authenticates as for every request, and the one the tenant-isolation
policies actually apply to. DB_OWNER_USER / DB_OWNER_PASSWORD name the
schema owner, used for exactly two things at boot — running Alembic and
re-issuing the runtime role's grants right after — and never to serve a
request. just up's init-db container creates the runtime role on a fresh
volume; it does not grant it anything, because on a fresh volume there is
nothing yet to grant — switch-core does that itself once the owner
connection has migrated the schema.
If you have an existing .env from before this split, add DB_OWNER_USER
and DB_OWNER_PASSWORD to it and change DB_USER to switch_app (see
.env.example), then run just reset to rebuild the Postgres volume from
scratch — that's the clean way to get the runtime role created, since
init-db only creates it on a fresh volume. Reusing an old volume with the
new .env leaves the runtime role missing entirely. just up refuses to
start while the two owner variables are absent, and says this, rather than
bringing up a Postgres container with an empty POSTGRES_USER and leaving
you to work backwards from whatever fails after it.
Boot refuses to serve if the runtime connection turns out not to be
restricted — a superuser, a role with BYPASSRLS, or the owner of a policied
table — because that failure is silent otherwise: a deployment that believes
it is isolating tenants and is not looks identical to one that is. Set
DB_REQUIRE_RESTRICTED_ROLE=false as an escape hatch for a stack that has
not created its runtime role yet; switch-core then logs an error on every
boot instead, as a standing reminder that tenant isolation is not active.
Starting the stack
just up # start the supporting services (Docker Compose)
just migrate # apply database migrations
just run # run switch-core (:8000)
just gateway-dev # run the gateway frontend, in a separate terminal (:5173)
just up starts the supporting services only: PostgreSQL, Mattermost
(seeded as the local collaboration bridge), and a one-shot setup container
that provisions the Mattermost team/bot/admin accounts named by the
MATTERMOST_* variables. It does not start switch-core and does not
start the gateway frontend — you run both of those yourself, in their own
terminals, so each gets hot-reload while you work. just down stops the
stack; just reset also wipes its volumes (Postgres data included).
switch-core refuses to connect to a private address at a URL a bridge config
names, unless OUTBOUND_ALLOWED_PRIVATE_HOSTS lists it. The .env.example
default, localhost, covers the local Mattermost. An .env from before that
setting existed lacks it, and
the Mattermost bridge then refuses to start with a message naming the variable:
add the line from .env.example.
just migrate runs alembic upgrade head against the Postgres started by
just up. Run it once after the stack is up and again after pulling any
change that adds a migration — just run does not apply migrations itself
and will fail against a database that's behind.
just run starts switch-core (python -m switch_core.main) on
SERVER_PORT (8000 by default). This one process is both the Agent Bridge
API (where agents and the MCP server connect) and the gateway management API,
mounted at /gateway on the same app — there is no separate backend process
for the dashboard.
The part that's easy to miss: just gateway-dev
just up does not start the gateway frontend, and nothing warns you.
The operator dashboard you'd open in a browser is a separate Vite dev
server, started with just gateway-dev (cd gateway && npm run dev), and it
listens on :5173, not :8000. Forget to start it and there is simply
nothing at localhost:5173; go to localhost:8000 instead expecting a UI
and you get switch-core's raw JSON API responses.
That is a development default, not how a deployed server works. switch-core
serves the dashboard itself, on its own port beside the API, whenever
GATEWAY_UI_DIR names a built dashboard — and the server image sets it, so a
deployed server has one address for everything. To get the same in dev, build
the dashboard once (cd gateway && npm run build) and run with
GATEWAY_UI_DIR=gateway/dist; Vite stays the way to work on the dashboard
itself, because it reloads as you edit. The separate gateway image (an nginx
container serving the same build and forwarding /gateway to switch-core)
still works in standalone and Helm deployments, but nothing needs it any more.
The Vite dev server proxies every /gateway/* request to
http://127.0.0.1:8000 (see gateway/vite.config.ts), so from the browser's
point of view the dashboard and its API calls share one origin
(localhost:5173) even though two separate processes are actually serving
them. That's also why cookie-based gateway auth (including OIDC login, see
GATEWAY_OIDC_SETUP.md) just works in dev without
any CORS configuration: as far as the browser can tell, it never left
:5173.
Viewing the dashboard as each role
To check what each permission level sees, run just seed-dev-roles once the
stack and just run are up. It creates a test account per level on your
local server (an org admin, a workspace admin and a member, with a random
password) plus a second workspace that only the org admin can open, and saves
their logins, with the gateway admin's from .env as the operator, to
gateway/.dev-role-accounts.json (gitignored). It is safe to run again.
With the new layout turned on (FEATURE_FLAGS_ENABLED=gateway_v2),
just gateway-dev then shows a Role: control at the right end of the top
bar. Sign in once as anyone, such as the gateway admin from .env: the
server tells a signed-out page none of its flags, so the control is not on
the sign-in page. Picking a role signs you in as that account, an ordinary
password sign-in, and reloads the page, staying in the same workspace when
that account can open it. The server sees only that account, so what you see is
exactly what a person with that role gets.
It exists only in the Vite dev server: a production build leaves it out, and
npm run build fails if any of it gets in (gateway/scripts/check-no-dev-tools.mjs).
The dashboard switch-core serves from GATEWAY_UI_DIR is such a build, so it
never has the switcher.
Which URL is which
| URL | What's there | Started by |
|---|---|---|
http://localhost:5173 |
The operator dashboard (Vite dev server). Open this in a browser. | just gateway-dev |
http://localhost:8000 |
switch-core: the Agent Bridge API, the MCP server, and the gateway management API under /gateway/*. Also the dashboard when GATEWAY_UI_DIR points at a build; otherwise JSON, not a UI. |
just run |
http://localhost:8081 |
switch-core's collaboration callback listener — where Mattermost delivers a button press. Bound only once a bridge asks to be called back, so it is often not there at all. | just run |
http://localhost:8065 |
Mattermost, seeded as the local collaboration bridge. | just up |
http://localhost:5432 |
PostgreSQL. | just up |
FRONTEND_BASE_URL in .env (default http://localhost:5173) tells
switch-core where to send the browser back to after a flow that leaves the
dashboard, such as the OIDC login redirect — it should match wherever
just gateway-dev is actually listening.
Connecting Switch Console to your local server
Switch Console (the desktop app) connects to a Switch server by one address:
switch-core's. In local dev that is http://localhost:8000. Console
writes it into each connected agent's own config as the endpoint it
registers against (the Agent Bridge / MCP surface), calls the gateway
management API under /gateway/* on it (signing in, listing agents and
rooms, the reachability check), and opens dashboard pages on it — the
Open button under "Full admin interface", and links to rooms and agents.
Those dashboard pages are the one thing that needs more than just run:
switch-core serves them only when GATEWAY_UI_DIR names a built dashboard
(see above). Without it, everything else works and the Open button loads
a bare JSON response instead of the admin UI. Either run with
GATEWAY_UI_DIR=gateway/dist after building the dashboard, or open the Vite
dev server at localhost:5173 in a browser yourself.
If you paste http://localhost:5173 by mistake, Console refuses it when you
save, because it answers with a web page rather than the API.
In Switch Console, add a server, choose Connect to an existing server,
and enter http://localhost:8000.
A server saved by an older Console with two addresses keeps working: its API address became its one address, and the old Gateway URL is kept, out of sight, for opening dashboard pages until the server serves its own dashboard and the old address stops answering.
A local Switch Cloud
A shared deployment runs whatever was last deployed to it, which is often older than the branch you are testing. Switch Console can instead treat a server run from your checkout as Switch Cloud, so the first-run Cloud path, invite links and invitation e-mails can all be tried against your code:
just up # Postgres and the rest, as usual
just local-cloud # switch-core on :8000, plus a mail catcher
just local-cloud-console # the Console, with Switch Cloud at http://localhost:8000
- Sign-in is by password. The gateway admin from
.envworks, andjust local-cloud-user <email> "<name>" <password>adds more accounts. Every account made this way joins the admin's workspace; create another workspace in the Console to invite people into, or to open to a domain. - Invitation e-mails are sent to Mailpit, which keeps them rather than
delivering them: read them at
http://localhost:8025. Their links point athttp://localhost:8000, so pasting one into the Console's "Paste your invite link" finds the local Cloud. That comes fromFRONTEND_BASE_URL, whichjust local-cloudsets to:8000. The dashboard's own links follow it, so they open switch-core's JSON rather than the dashboard unless switch-core is serving it: build it (just gateway-build) and runGATEWAY_UI_DIR=gateway/dist just local-cloud, and they open the dashboard on:8000, as they do on a deployed Cloud. - Joining by domain is offered only for the domain of the admin's own
address:
switch.localfor the default admin. Give test accounts addresses there. - The Cloud address must be https, except for
localhost,127.0.0.1and[::1], which may be plain http for exactly this. The Console matches its Switch Cloud entry by address, so an install that has signed in to the real Cloud gets a second "Switch Cloud" server for the local one rather than reusing it. - The Console's data (servers, sign-ins, its database) lives in its own
directory,
switchdash-local-cloudunder the system's app-data folder, rather than the one every other dev build shares. Branches that number their migrations differently cannot break each other's database this way. Delete that directory to start the Console from scratch.
Auto-route locally
Auto-route (the decision_routing feature flag) asks a decision service who
should answer an untagged message. just decision-up starts one beside the
stack: the decision service on :8230 (DECISION_PORT to change it) and a
llama.cpp server for its model, Qwen3.5-4B in 4-bit, whose weights (about
2.7 GB) download once into the decision-models volume, from a fixed
Hugging Face commit and checked against their SHA-256 (a file that fails is
deleted and downloaded again). It is the compose
decision profile; just decision-up gpu is the decision-gpu profile, for
Linux with an NVIDIA GPU and the NVIDIA Container Toolkit.
Production (the Helm chart) defaults to a different model, Strands Decider
4B, which made far fewer wrong picks on our routing scenarios (2 against
Qwen's 9 in 100) but needs an NVIDIA GPU with 24 GB, so it can't be the local
default. just decision-up strands (the decision-strands-gpu profile) runs
it on Linux with an NVIDIA GPU (24 GB), about 24 GiB of free RAM and the
NVIDIA Container Toolkit; there is no GPU passthrough on macOS. It builds the
switch-decision-strands image, and the first start downloads the checkpoint
and its Gemma 4 base model (about 17 GB, Gemma terms apply) into the
decision-hf volume, then loads it, which takes minutes; HF_TOKEN is
optional. decision/README.md has the numbers and the licence note.
switch-core runs on the host, so point it at the service in .env and
restart just run:
FEATURE_FLAGS_ENABLED=follow_the_conversation,decision_routing
DECISION_ENDPOINT_URL=http://localhost:8230
DECISION_TIMEOUT_SECONDS=30
On CPU each decision takes several seconds, far over the one-second target a
GPU meets, so raise the timeout as above. It is fine for trying auto-route
out, not for judging its latency. Another model is DECISION_MODEL_URL,
DECISION_MODEL_FILE and DECISION_MODEL (plus HF_TOKEN for a gated one).
just decision-down stops it. decision/README.md covers the service itself.
Other useful recipes
| Command | What it does |
|---|---|
just decision-up [gpu|strands] / just decision-down |
Start / stop the decision service for auto-route (see above) |
just local-cloud / just local-cloud-console |
Run switch-core as a stand-in for Switch Cloud, and the Console pointed at it (see above) |
just format / just check |
Format with ruff / lint-check in CI mode (no changes) |
just typecheck |
mypy over core/switch_core/ |
just test / just test -k name |
Run the test suite / a single test |
just test-integration |
Integration tests against a real Postgres via testcontainers |
just migration "message" |
Autogenerate a new Alembic migration |
just gateway-build |
Build the gateway frontend's production bundle |
just seed-dev-roles |
Create the test accounts the dashboard's dev role switcher signs in as (see above) |