percher.toml — full reference

[app]
name = "my-app"            # 3-40 chars, lowercase, a-z 0-9 and hyphens
runtime = "node"           # node | bun | python | static | docker
framework = "nextjs"       # optional: nextjs, sveltekit, astro, remix,
                           # nuxt, vite, preact, solid, express, fastify,
                           # hono, elysia, fastapi, flask, django, eleventy,
                           # hugo, laravel, rails, phoenix, go, rust, dotnet,
                           # java, docker

[build]
command = "bun run build"  # custom build command (optional)
output = ".next"           # build output directory (optional)
pass_env = [               # opt-in: expose these env vars at BUILD time
  "NEXT_PUBLIC_API_URL",   # (Vite/Next/Astro/Expo bake *_PUBLIC_* into
  "VITE_PB_URL",           # the bundle, so they need build-time access)
]                          # Values come from "percher env set", never
                           # from this TOML — only key names live here.

[web]
port = 3000                # port your app listens on (1024-65535)
health = "/health"         # health check endpoint (default: /)
command = "npm start"      # optional start command; bind servers to 0.0.0.0
visibility = "password"    # "public" (default) | "password" | "private"
                           #   "private" = Percher-login gate (owner + invitees)
password = true            # legacy alias for visibility = "password"
spa = false                # static only: deep links fall back to index.html
rate_limit = { rps = 10, burst = 50 }
                           # optional per-app rate limit, keyed by client IP
                           # (default: unlimited). rps 1-100, burst 1-1000,
                           # rps <= burst <= rps*10. Over the ceiling -> 429.
                           # Needs the platform's rate-limit module (operator).

[resources]                # recommended sizing — see "Pools are measured" below
memory = "512mb"           # 256mb | 512mb | 1gb | 2gb
cpu = 0.5                  # 0.25 - 2.0
instances = 2              # static N containers; plan-gated
                           # (free=1, starter=1, maker=2, max=4).
                           # Mutually exclusive with [resources.autoscale].

# Or: CPU-based autoscaling instead of a static count
[resources.autoscale]
min = 1                    # initial + floor (plan-clamped)
max = 4                    # ceiling (plan-clamped)
# Optional fine-tuning. Most users leave these at defaults:
# scale_up_cpu_percent = 80
# scale_up_sustain_seconds = 120
# scale_down_cpu_percent = 20
# scale_down_sustain_seconds = 600
# cooldown_seconds = 180

[data]
mode = "pocketbase"        # pocketbase | postgres | sqlite | convex | supabase | external | none
# mode = "convex"
# convex.deployment_url = "https://your-project.convex.cloud"
# mode = "supabase"
# supabase.url = "https://your-project.supabase.co"
# supabase.anon_key = "eyJ..."
# mode = "sqlite"
# file = "data.db"          # required when mode = "sqlite"

[domain]                   # parsed but not applied today:
subdomain = "my-app"       # the app name sets name.percher.run
custom = "myapp.com"       # use "percher domains add" for a custom domain

[env]                           # legacy KEY=VALUE shape (still supported)
STRIPE_KEY = "sk_live_..."      # environment variables
API_SECRET = "..."

# Or the env contract (preferred for new projects):
# [env]
# required = ["OPENAI_API_KEY"] # must exist before deploy queues
# optional = ["SENTRY_DSN"]     # may be referenced; not required
# ignore   = ["NODE_ENV"]       # explicitly ignored by the env scanner

[crons]
# description is optional — it's shown on the dashboard so anyone can see what the job is for
cleanup = { schedule = "0 3 * * *", command = "node cleanup.js", description = "Delete records older than 90 days" }
report  = { schedule = "*/15 * * * *", command = "python report.py" }

[[redirects]]              # up to 32 — served at the edge, before your app
from = "/old-path"         # exact path, or a prefix ending in "/*"
to = "/new-path"           # relative path or absolute https:// URL
status = 308               # 301 | 302 | 307 | 308 (default 308)

[headers."/*"]             # response headers per path (16 paths x 16 headers)
X-Custom-Header = "value"  # platform security headers can't be overridden

[dev]
ignore = ["*.log", "tmp/"] # files to ignore in dev mode
debounce = 300             # ms to wait before rebuilding (100-10000)
auto_open = true            # automatically open the dev URL

[required_env]             # older typed requirement map (still supported)
STRIPE_KEY = "secret"      # must be set before deploy
DATABASE_URL = "url"       # validates URL format
APP_NAME = "string"        # any non-empty string

# [addons.*] is reserved and has no effect today: use [data] mode and [crons]

[checks.health]            # the only checks name Percher reads
path = "/health"           # required by the parser, not used (see [web] health)
timeout = 90               # seconds to wait for healthy (default 30, max 300)
initial_delay = 20         # seconds before failed probes count (default 5, max 120)