toupas.json
Lives in the app's folder and is committed with the code. toupas_make_live writes it the first time from what it detects; edit it only to change something. It says how to prepare and run the app, not which Toupas app it is (that's .toupas/project.json, which stays out of git).
{
"$schema": "https://toupas.com/schema/v1/toupas.json",
"type": "server",
"runtime": "node24",
"framework": "express",
"build": { "install": "npm ci", "command": "npm run build" },
"start": "node server.js",
"healthCheck": { "path": "/health" },
"memoryMb": 256
}{ "type": "static", "framework": "vite", "build": { "command": "npm run build", "output": "dist" }, "static": { "spa": true } }| Field | For | Notes |
|---|---|---|
type | all | static or server (required) |
runtime | server | node24, node22, python313 or python312 (toupas_list_runtimes). Without it: node22 / python312 when engines.node, .nvmrc, .node-version, .python-version or requires-python ask for exactly that version, else the newest |
framework | all | A preset that fills in the rest (toupas://docs/frameworks) |
build.install | server | Runs in the builder; default from the lockfile |
build.command | all | Runs in the builder (server) or on this computer (static) |
build.output | static | The folder that goes live, e.g. dist |
start | server | Run as /bin/sh -c "exec <start>", so $PORT works |
healthCheck.path / healthCheck.timeoutSeconds | server | Default / and 60 (at most 300) |
memoryMb | server | Multiple of 64, 128–2048; default 128. Counts toward the account's RAM |
include / exclude | all | Extra glob patterns. .env, .env.*, *.pem, *.key, .git, node_modules and .venv are always left out |
static.spa | static | Serve index.html for unknown paths |
static.cleanUrls | static | /about serves /about.html (default true) |
systemPackages | server | Debian 13 packages the app needs when it runs, e.g. ["ffmpeg", "poppler-utils"] (at most 30, names from https://packages.debian.org). The first time, Toupas builds them into the runtime's images (a few minutes); after that it's instant |
buildPackages | server | Debian packages only the build needs, e.g. ["libvips-dev"] |
Unknown fields are refused, so typos fail loudly. Use systemPackages only for software npm or pip can't install (ffmpeg, Chromium for Puppeteer, poppler, ImageMagick).