Quick Start

Prerequisites:

• The BeamUp dashboard URL from your invitation.
• A one-time beta access code if this is your first registration.
• A Gleam HTTP app that targets Erlang and can build with gleam export erlang-shipment.
• A health path such as /healthz that returns HTTP 2xx without exposing secrets or debug state.

Install The CLI

Choose the command for your OS:

macOS with Homebrew:

brew install beamup-run/tap/beamup

Linux glibc 2.39+:

curl -fsSL https://beamup.run/install.sh | sh

Windows PowerShell:

pwsh -NoProfile -Command "irm https://beamup.run/install.ps1 | iex"

The shell installer writes to $HOME/.beamup/bin and prints PATH guidance if needed. The Windows installer writes to %LOCALAPPDATA%\BeamUp\bin, updates only the current user’s PATH, and may require a new shell before beamup is visible.

Verify the CLI is available:

beamup --version

See Install The BeamUp CLI for supported targets, the Windows PowerShell fallback, update commands, and the checksum trust boundary.

Register In The Browser

Create your browser account first. Open the dashboard URL from your invitation, sign in with GitHub, and redeem your one-time beta access code. Returning browser logins use the same GitHub identity and do not require another code.

Log In From The CLI

Then authenticate the CLI:

beamup login
beamup whoami

For a headless terminal:

beamup login --no-browser

From the root of your Gleam app:

beamup init

Review the generated beamup.toml. For most supported Erlang-targeted Gleam HTTP apps, the important defaults are:

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"

Run a local check before deploy:

PORT=8000 gleam run

In another terminal, check the health path:

curl -i http://127.0.0.1:8000/healthz

Deploy:

beamup deploy

Plain output creates a deployment, reports the compressed archive size and file count, and prints the build-log command for that deployment. BeamUp activates the deployment only after the worker starts the app and the configured health check passes.

Check status:

beamup status

When the deployment is active, the app URL is:

https://<app>.beamup.run

Fetch recent runtime logs:

beamup --app hello-gleam logs --no-follow

Fetch build logs for a specific deployment:

beamup --app hello-gleam logs --build --deployment <deployment-id> --no-follow

Set runtime configuration:

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

env set accepts values once and list output shows only key metadata. Secrets are never returned in plaintext after submit.

Open the dashboard and go to the app cockpit to inspect deploy state, build logs, runtime logs, env keys, secret metadata, rollback targets, and the safe BEAM runtime snapshot.

If a healthy replacement needs to be reverted:

beamup --app hello-gleam rollback

Or choose a specific eligible previous deployment:

beamup --app hello-gleam rollback --to <deployment-id>

Failure Recovery

• Missing gleam.toml: run from the Gleam project root or fix app_root.
• Unsupported target: use an Erlang-targeted Gleam project. JavaScript, Cloudflare Worker, Lustre/full-stack, Elixir, and Erlang applications are not SLC v1 runtimes.
• Invalid beamup.toml: fix the named field and retry before upload.
• Compile failure: read build logs, fix local compile errors, then redeploy.
• Missing runtime config: set the required key with beamup env set or beamup env set --secret, then redeploy.
• Port binding failure: read PORT, parse it as an integer, and bind HTTP traffic on 0.0.0.0:<PORT>.
• Health-check failure: make the configured health path return HTTP 2xx without depending on external services or secrets.
• Runtime snapshot unavailable: inspect the warning, but do not treat it as app downtime by itself. Deployment health is tracked separately.