Skip to content

The switchboard.toml file

How Switchboard builds and starts your website, and the settings in switchboard.toml.

Every website has a switchboard.toml file in its main folder. It tells Switchboard how to build and start your website. The template sets it up correctly for you; you usually never need to look at it. This page is for the curious, and for your AI.

#Example

A website with a separate backend:

switchboard.toml
stack = "sveltekit-fastapi"

[frontend]
dir = "frontend"
install = "npm ci"
build = "npm run build"
start = "node build"
port = 3000

[backend]
dir = "backend"
install = "uv sync --frozen --no-dev"
start = "uv run --no-sync uvicorn app.main:app --host 0.0.0.0 --port 8000"
release = "uv run --no-sync alembic upgrade head"
port = 8000
prefixes = ["/api"]

[health]
path = "/healthz"

A website without a separate backend only has a [frontend] part, with dir = ".".

#All fields

Field Meaning
stack The template: sveltekit, nextjs, sveltekit-fastapi or nextjs-fastapi.
[frontend] The website itself (with a single part: the whole website).
[backend] Only with a separate backend: the second program.
dir Which folder this part is in. "." is the main folder.
install Command that installs what's needed.
build Command that builds the website.
start Command that starts the website.
release (optional) Command that runs before every start, for example to update the database.
port The "house number" this part listens on. Your website must use the PORT variable.
prefixes For a backend: which addresses go to the backend, like ["/api"].
[health] path An address that must answer "OK" within 60 seconds of starting. That's how we know your website started properly.

If the file or a field is missing, we use your template's default. Unknown fields are skipped, with a warning in the build log.

#Good to know

  • Your website runs in a sealed-off environment. Only the /data folder is kept between restarts; that's where your database lives, for example. See database and backups.
  • Settings don't go in this file, but in settings and secrets.
  • Which variables Switchboard gives your website is described under platform variables.

Was this helpful?

Guide

Search the guide

Type a word or a question. Tip: press Ctrl K to open this anywhere.