beamup.toml Reference

beamup.toml describes build and runtime behavior for a supported Gleam app. It is not a secrets file and does not require a BeamUp SDK.

Example

app = "hello-gleam"
runtime = "erlang"
app_root = "."
start = ["./build/erlang-shipment/entrypoint.sh", "run"]
health = "/healthz"

[build]
target = "erlang"
env = "prod"

[deploy]
strategy = "blue_green"

Fields

Field	Type	Default	Rules
`app`	string	Derived from `gleam.toml` package name	DNS-safe slug, 3-63 characters, lowercase letters, numbers, and single hyphens, starting and ending with a letter or number.
`runtime`	string	`erlang`	Must be exactly `erlang` in SLC v1.
`app_root`	relative path	`.`	Must stay inside the project and point to a directory containing `gleam.toml`. No absolute paths, `..`, NUL bytes, globs, or symlink escape.
`start`	array of strings	`["./build/erlang-shipment/entrypoint.sh", "run"]`	Non-empty argv array executed directly without a shell. The command must rely on runtime-provided `PORT`.
`health`	string path	`/healthz`	Path only. Must start with `/`; no URL, query string, fragment, whitespace/control characters, `..`, or empty path. Maximum 256 bytes.
`build.target`	string	`erlang`	Must be exactly `erlang` and maps to `gleam export erlang-shipment`.
`build.env`	string	`prod`	Short build-environment label using letters, numbers, underscores, or hyphens. It is not a place for env vars or secrets.
`deploy.strategy`	string	`blue_green`	Must be exactly `blue_green` when present. Rolling, canary, multi-region, and custom routing strategies are not supported in SLC v1.

Unknown fields are errors. This prevents misspellings and accidental secret blocks from being ignored.

Rules

beamup init creates or validates beamup.toml.
beamup deploy validates beamup.toml before source upload.
start is argv, not a shell string.
Runtime always provides PORT.
beamup.toml must not contain plaintext secrets, auth tokens, provider credentials, .env contents, or committed runtime env values.
Runtime configuration belongs in beamup env set, beamup env delete, and the dashboard env/secrets forms.

Invalid Examples

Invalid app slug and health path:

app = "Bad Name!"
runtime = "erlang"
start = ["./build/erlang-shipment/entrypoint.sh", "run"]
health = "healthz"

Unsupported runtime:

app = "hello-gleam"
runtime = "javascript"
start = ["./build/erlang-shipment/entrypoint.sh", "run"]
health = "/healthz"

Secret block:

app = "hello-gleam"
runtime = "erlang"
health = "/healthz"

[secrets]
DATABASE_URL = "<database-url>"

Move the secret to BeamUp instead:

beamup --app hello-gleam env set DATABASE_URL=<database-url> --secret