switch
★ 4.5kAbout
Community Ratings
No ratings yetNew this week
Read recap →Features
- Collaborative rooms in Slack, Microsoft Teams, Discord, Telegram, and Mattermost
- Direct agent conversations in Switch Console
- Support for different agents, models, and providers
- Agent roles, instructions, and connectors
- Room-based context and access controls
- Workspace administration and connector controls
- Agent-assisted setup of agents and rooms
- Workflow automation across team channels
Details
- Last Updated
- Nov 18, 2026
- Created
- Jul 16, 2026
- Install Methods
- binary
- Privacy & Independence
- Cloud: Optional
- User Model
- Multi-User
- Deployment
Deployment: Docker Compose ✓8 Containers — heavy hosting footprintRuns as 8 containers
Run switch yourself
Pick how much you want to manage.
netcupBest match
Full control
A small server, then Docker Compose.
About 20 minutes with Docker
Hetzner
Full control
A small server, then Docker Compose.
About 20 minutes with Docker
DigitalOcean
Full control
A small server, then Docker Compose.
About 20 minutes with Docker
1 more way to host
Some links earn us a commission. netcup pays us one and is our preferred VPS host.
Is this your project? Sponsor a listing
Run switch with Docker Compose
Compose file from the switch project repository.
8 services · database: postgres · infra: postgres · 3 unclassified (mailpit, curl, llama.cpp)
no resource limits declared
needs persistent storage (5 volumes)
deploy/local/docker-compose.yml · @ b027564 · scanned Nov 18, 2026
services:
postgres:
image: postgres:16-alpine
ports:
- "${SWITCH_BIND_ADDR:-127.0.0.1}:5432:5432"
environment:
# The container's bootstrapped superuser is the SCHEMA OWNER
# (DB_OWNER_USER), not the runtime role Switch serves requests as
# (DB_USER). Row-level security is inert against a table's owner, so
# the role every request authenticates as must be a separate, deliberately
# unprivileged login — created below by init-db, once the owner is up.
POSTGRES_USER: ${DB_OWNER_USER}
POSTGRES_PASSWORD: ${DB_OWNER_PASSWORD}
POSTGRES_DB: ${DB_NAME}
volumes:
- pgdata:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U ${DB_OWNER_USER}"]
interval: 2s
timeout: 3s
retries: 10
init-db:
image: postgres:16-alpine
environment:
PGPASSWORD: ${DB_OWNER_PASSWORD}
# Runs as the owner: creating a role needs privileges
# the runtime role is deliberately never given. Note the mixed quoting in
# the CREATE ROLE / ALTER ROLE statements is not optional — DB_USER is an
# identifier (double-quoted, and safe only because .env.example pins it to
# a fixed, non-attacker-controlled name) and the password is a string
# literal (single-quoted); swapping them would either fail to parse or
# quietly create a role named after the password.
#
# No GRANT here on purpose: on a fresh volume there is nothing yet to
# grant. The `switch` database has no tables until switch-core runs
# Alembic against the owner connection, so the runtime role's CRUD grants
# are issued by switch-core itself at boot, immediately after migrating —
# see db/runtime_role.py. This step only has to make the role exist.
entrypoint: >
sh -c "
until pg_isready -h postgres -U ${DB_OWNER_USER}; do sleep 1; done
psql -h postgres -U ${DB_OWNER_USER} -tc \"SELECT 1 FROM pg_roles WHERE rolname='${DB_USER}'\" | grep -q 1 ||
psql -h postgres -U ${DB_OWNER_USER} -c 'CREATE ROLE \"${DB_USER}\" LOGIN PASSWORD '\\''${DB_PASSWORD}'\\'' NOSUPERUSER NOCREATEDB NOCREATEROLE NOBYPASSRLS;'
psql -h postgres -U ${DB_OWNER_USER} -c 'ALTER ROLE \"${DB_USER}\" PASSWORD '\\''${DB_PASSWORD}'\\'';'
"
depends_on:
postgres:
condition: service_healthy
# A mail catcher for invitation e-mails, started by `just local-cloud` only
# (the `mail` profile keeps it out of `just up`). It accepts anything on
# 1025 and shows it at http://localhost:8025; nothing is delivered onwards.
mailpit:
image: axllent/mailpit:latest
profiles: ["mail"]
ports:
- "${SWITCH_BIND_ADDR:-127.0.0.1}:1025:1025"
- "${SWITCH_BIND_ADDR:-127.0.0.1}:8025:8025"
# ── Decision service (auto-route) ───────────────────────────────────────────
# `just decision-up [cpu|gpu|strands]`, or one of these profiles. Each starts
# the decision service on :8230 and a model server beside it:
# decision Qwen3.5-4B on llama.cpp, on CPU (any machine). The
# local default.
# decision-gpu the same on an NVIDIA GPU.
# decision-strands-gpu Strands Decider 4B, the production default (the
# Helm chart's): more accurate, but it needs an NVIDIA
# GPU with 24 GB, about 24 GiB of free RAM to load,
# and the first start downloads about 17 GB.
# The GPU profiles need Linux, an NVIDIA GPU and the NVIDIA Container
# Toolkit; there is no GPU passthrough on macOS. Weights download once into
# a volume (`decision-models`, or `decision-hf` for Strands). switch-core
# runs on the host, so point it at the service in .env (see .env.example,
# "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), hence the longer timeout; fine for trying auto-route out.
decision-model-download:
image: curlimages/curl:8.11.1
profiles: ["decision", "decision-gpu"]
# The fresh named volume is root's.
user: "0:0"
# Pinned to a Hugging Face commit and checked against its SHA-256, as in
# the Helm chart. A file that fails the check is deleted (and, if it was
# already on the volume, downloaded again), so a bad file never sticks.
# To try another model, set DECISION_MODEL_URL, _FILE and _SHA256
# together (an empty _SHA256 skips the check).
environment:
MODEL_URL: ${DECISION_MODEL_URL:-https://huggingface.co/unsloth/Qwen3.5-4B-GGUF/resolve/e87f176479d0855a907a41277aca2f8ee7a09523/Qwen3.5-4B-Q4_K_M.gguf}
MODEL_FILE: ${DECISION_MODEL_FILE:-Qwen3.5-4B-Q4_K_M.gguf}
MODEL_SHA256: ${DECISION_MODEL_SHA256-00fe7986ff5f6b463e62455821146049db6f9313603938a70800d1fb69ef11a4}
# Only for a gated model (one whose licence your Hugging Face account
# has accepted).
HF_TOKEN: ${HF_TOKEN:-}
entrypoint:
- sh
- -c
- |
set -eu
target="/models/$$MODEL_FILE"
verify() { [ -z "$$MODEL_SHA256" ] || echo "$$MODEL_SHA256 $$target" | sha256sum -c -; }
if [ -s "$$target" ]; then
if verify; then echo "have $$MODEL_FILE"; exit 0; fi
echo "$$MODEL_FILE on the volume fails its checksum; deleting it and downloading it again" >&2
rm -f "$$target"
fi
echo "downloading $$MODEL_URL"
set -- -fsSL --retry 5 --retry-delay 10 -C - -o "$$target.partial"
if [ -n "$$HF_TOKEN" ]; then set -- "$$@" -H "Authorization: Bearer $$HF_TOKEN"; fi
curl "$$@" "$$MODEL_URL"
mv "$$target.partial" "$$target"
if ! verify; then
echo "the downloaded $$MODEL_FILE fails its checksum; deleted it, so the next start downloads it again" >&2
rm -f "$$target"
exit 1
fi
volumes:
- decision-models:/models
decision-model:
image: ghcr.io/ggml-org/llama.cpp:server
profiles: ["decision"]
command:
- -m
- /models/${DECISION_MODEL_FILE:-Qwen3.5-4B-Q4_K_M.gguf}
- --host
- 0.0.0.0
- --port
- "8300"
- -c
- "16384"
- -np
- "4"
- --jinja
volumes:
- decision-models:/models:ro
healthcheck:
test: ["CMD", "curl", "-fs", "http://localhost:8300/health"]
interval: 5s
timeout: 3s
retries: 60
start_period: 10s
depends_on:
decision-model-download:
condition: service_completed_successfully
decision-model-gpu:
image: ghcr.io/ggml-org/llama.cpp:server-cuda
profiles: ["decision-gpu"]
command:
- -m
- /models/${DECISION_MODEL_FILE:-Qwen3.5-4B-Q4_K_M.gguf}
- --host
- 0.0.0.0
- --port
- "8300"
- -ngl
- "99"
- -c
- "16384"
- -np
- "4"
- --jinja
# The decision service reaches whichever model server runs at one name.
networks:
default:
aliases: [decision-model]
volumes:
- decision-models:/models:ro
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: 1
capabilities: [gpu]
healthcheck:
test: ["CMD", "curl", "-fs", "http://localhost:8300/health"]
interval: 5s
timeout: 3s
retries: 60
start_period: 10s
depends_on:
decision-model-download:
condition: service_completed_successfully
# Strands Decider 4B's model server (decision-strands-gpu). The checkpoint
# and its Gemma 4 base download from Hugging Face into `decision-hf` on the
# first start, then load; the port opens only once the model is loaded, so
# allow several minutes (much longer on the first start). HF_TOKEN is
# optional: for a gated checkpoint or higher Hub rate limits.
decision-model-strands:
build:
context: decision/model-servers/strands
image: switch-decision-strands:local
profiles: ["decision-strands-gpu"]
environment:
HF_TOKEN: ${HF_TOKEN:-}
# The checkpoint's and its base model's Hugging Face commits, as in the
# Helm chart (decision.modelServer.strands.revision / baseRevision).
STRANDS_REVISION: 1344d44397c457f3be34b8ff15c593b41248c6bf
STRANDS_BASE_REVISION: ee0ef6023621cff504d758262d4e04895a5af4a2
volumes:
- decision-hf:/models
deploy:
resources:
reservations:
devices:
- driver: nvidia
count: 1
capabilities: [gpu]
healthcheck:
test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8400/health', timeout=3)"]
interval: 10s
timeout: 5s
retries: 3
start_period: 30m
decision: &decision
build:
context: decision
dockerfile: Dockerfile
image: switch-decision:local
profiles: ["decision", "decision-gpu"]
ports:
- "${SWITCH_BIND_ADDR:-127.0.0.1}:${DECISION_PORT:-8230}:8230"
# Docker Desktop and OrbStack define host.docker.internal; Linux Docker
# only does when asked. It is how this container reaches a collector on
# the host (see OTLP_ENDPOINT below).
extra_hosts:
- "host.docker.internal:host-gateway"
environment:
# Logging follows switch-core's settings in .env, as switch-decision.
# A name with no value is passed only when .env or the shell sets it,
# so an unset OTLP_ENDPOINT leaves log shipping off. It ships logs only,
# never metrics. In here localhost is this container: for a collector on
# the host, OTLP_ENDPOINT has to name host.docker.internal.
<<: &decision-logging
LOG_FORMAT:
LOG_LEVEL:
ENVIRONMENT:
SERVICE_NAME: switch-decision
OTLP_ENDPOINT:
DEPLOYMENT_ID:
OTLP_LOGS_ENABLED:
OTLP_TIMEOUT_SECONDS:
OTLP_HEADERS:
POD_NAME: decision
DECISION_BACKEND: llamacpp
DECISION_MODEL: ${DECISION_MODEL:-qwen3.5-4b-q4_k_m}
LLAMACPP_URL: http://decision-model:8300
# A CPU decision takes seconds; the service's own model-server timeout.
DECISION_TIMEOUT_S: "60"
healthcheck:
test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8230/health', timeout=3)"]
interval: 5s
timeout: 5s
retries: 30
depends_on:
decision-model:
condition: service_healthy
required: false
decision-model-gpu:
condition: service_healthy
required: false
# The decision service in front of Strands Decider: the same image, speaking
# SystemOne to its model server.
decision-strands:
<<: *decision
profiles: ["decision-strands-gpu"]
environment:
<<: *decision-logging
POD_NAME: decision-strands
DECISION_BACKEND: systemone
DECISION_MODEL: strands-decider-E4B
SYSTEMONE_URL: http://decision-model-strands:8400/v1/systemone
depends_on:
decision-model-strands:
condition: service_healthy
volumes:
pgdata:
decision-models:
decision-hf:
This file may be out of date. Check the switch documentation for current setup steps.
Tags
Track your self-hosted stack
Bookmark software to try, rate tools you've used, and keep your collection in one place.