joppa.toml

joppa.toml, at the root of a project, describes the processes Joppa runs. Commit it: your teammates get the same configuration as soon as they add the project. When it exists, it takes precedence over the local configuration.

Joppa writes it for you when you check Write joppa.toml in the repository for the team in the processes analysis. You can also write it by hand.

Example

[[procs]]
name = "postgres"
kind = "compose"
service = "db"

[[procs]]
name = "api"
kind = "script"
dir = "apps/api"
command = "bun run dev"
port = 8000
dependsOn = ["postgres"]

[procs.env]
PORT = "8000"

[[procs]]
name = "web"
kind = "script"
dir = "apps/web"
command = "bun run dev"
port = 5173
dependsOn = ["api"]

[[procs]]
name = "worker"
kind = "script"
command = "bun run queue"
enabled = false

Fields

Each [[procs]] is a process.

Field	Type	Role
name	string	Unique name within the project: web, api, postgres
kind	"script" or "compose"	A command, or a service from the project’s Docker Compose file
port	number	The port it responds on once ready. Omitted for a background task
dependsOn	list	Processes started (and ready) before this one
enabled	boolean	Started by “Start all” (true by default). At false, it’s started on its own

kind = "script"

Field	Role
command	The command, run in a shell
dir	The folder, relative to the project root (empty: the root)
env	Added environment variables ([procs.env])

kind = "compose"

Field	Role
service	The service name in the Docker Compose file

What isn’t in it

Start when Joppa opens and Relaunch after a crash are per-machine preferences: they stay in Joppa and are never written to joppa.toml.