Docs menu

Deploy and run

Variables and configuration

Set your app's variables, connect services with references, keep settings in your repo, and add staging environments.

Explain it

Apps read their settings (passwords, API keys, options) from variables. On CLI you set them per app or for the whole project, and one app can point at another's address or database without copying values around.

How to do it: open an app and go to Variables. Paste a whole .env file at once if you have one. Secret values are hidden after you save them. To change one, press Edit next to it, type the new value and save, then press Redeploy now so the app starts using it.

"Set STRIPE_KEY on my web app and redeploy."

You can also keep build and run settings in a cli.json file in your repository.

Your app reads its settings from environment variables. On CLI you can set them per service or for the whole project, point one service at another with references instead of copying values, and keep build and run settings in a cli.json in your repo.

Set variables

Variables belong to a service. Changes take effect on the next deploy.

In the dashboard: open the service and go to Variables. Add keys one at a time, or paste a whole .env file. Edit changes a value in place: plain values open with the current value, secrets open empty (leave it empty to keep the old one). After saving, Redeploy now deploys with the new values. Shared variables work the same way, and Redeploy the apps that use it redeploys only the apps whose variables refer to that shared value.

From your terminal:

Terminal
cli env set STRIPE_KEY=sk_live_… SESSION_SECRET=…
cli env import .env
cli env unset OLD_FLAG
cli env

Values are hidden unless you add --plain. cli env lists the variables on the linked service.

Ask your agent:

"Set LOG_LEVEL=debug on api and redeploy it."

With the API:

API
PUT /v1/services/:id/env
JSON
{ "vars": { "LOG_LEVEL": "debug", "OLD_FLAG": null } }

You can also send a whole file as {"dotenv": "A=1\nB=2"}. A null value deletes the key.

Secrets are write-only

Values are secret by default: once set, they're masked in the dashboard, in logs and in log drains. Reading a value back needs a person or a key with the secrets scope, and every read is recorded in the project's activity log. If you have a second factor turned on, revealing values asks for it again.

Reference other services

A value can point at another service instead of copying it. References are resolved on every deploy, so they keep working when a domain is renamed or a password is rotated.

JSON
{
  "vars": {
    "DATABASE_URL": "${{postgres.DATABASE_URL}}",
    "API_URL": "${{api.URL}}/v1",
    "INTERNAL_API": "${{api.PRIVATE_URL}}",
    "STRIPE_KEY": "${{shared.STRIPE_KEY}}"
  }
}

The form is ${{service.KEY}}, and you can mix references with text. Any variable set on the other service works, plus these special ones:

ReferenceGives you
${{postgres.DATABASE_URL}}A database's connection URL (also MYSQL_URL, REDIS_URL, MONGO_URL, HOST, PORT)
${{api.URL}}The service's public https address
${{api.PRIVATE_URL}}Its private address, http://api.internal:<port>
${{api.PRIVATE_HOST}}Its private host name
${{api.DOMAIN}}Its public domain, without https://
${{api.PORT}}Its port
${{postgres.READ_URL}}Postgres read replicas, or the primary if there are none (see /docs/databases)
${{shared.KEY}}A project-wide shared variable

In the dashboard: the Variables tab offers a reference list, so you can pick another service's value instead of typing it.

Check your references

A reference to a service or key that doesn't exist fails the deploy before it builds, with VARIABLE_REFERENCE_MISSING and a list of what didn't resolve. To check ahead of time:

From your terminal:

Terminal
cli env check

With the API:

API
GET /v1/services/:id/env/check

Shared variables

Shared variables belong to the project, not one service. Use them for values several services need, such as a Stripe key, and refer to them as ${{shared.KEY}}.

In the dashboard: open the project and choose Shared variables.

From your terminal:

Terminal
cli vars set STRIPE_KEY=sk_live_…
cli vars unset STRIPE_KEY
cli vars

With the API:

API
PUT /v1/projects/:id/variables
JSON
{ "vars": { "STRIPE_KEY": "sk_live_…" } }

Variables CLI sets for you

  • PORT: always, the port your app should listen on.
  • DATABASE_URL, MYSQL_URL, REDIS_URL or MONGO_URL: when you link a database.
  • BUCKET_URL and BUCKET_TOKEN, QUEUE_URL and QUEUE_TOKEN: when you link a bucket or queue (see /docs/storage-and-secrets).
  • OTEL_EXPORTER_OTLP_*: always, so any OpenTelemetry SDK reports to CLI (see /docs/monitoring).

Config as code with cli.json

Put a cli.json in your repo's root (or the service's root directory) to set how the service builds and runs. It's reviewed with your code and wins over dashboard settings.

JSON
{
  "build": { "command": "npm run build", "dockerfile": "Dockerfile" },
  "deploy": {
    "startCommand": "node dist/server.js",
    "healthcheckPath": "/healthz",
    "port": 8080,
    "replicas": 2,
    "sleepAfterMinutes": 30
  },
  "watchPaths": ["apps/web/**", "packages/**", "!**/*.md"],
  "cron": [{ "name": "nightly", "schedule": "0 3 * * *", "command": "node scripts/cleanup.js" }]
}

Those are all the keys it accepts. A bad file fails the deploy with CONFIG_INVALID, listing every problem and the field it's in. Each deploy shows the settings it used from cli.json. Delete the file to go back to dashboard settings.

Monorepos

If one repo holds several apps, give each service a root directory, such as apps/web. CLI builds from that folder, and a push only redeploys a service when it changes files under its folder or under its watch paths: globs like packages/**, or !**/*.md to ignore files.

In the dashboard: open the service's Settings and fill in Root directory and Redeploy on changes to.

With the API:

API
PATCH /v1/services/:id
JSON
{ "rootDir": "apps/web", "watchPaths": ["apps/web/**", "packages/**"] }

Environments

A project is its production environment. You can add copies, such as staging or dev. A new environment has the same services and variables, but fresh empty databases, no domains, and nothing running until you deploy. References point at the environment's own services, so ${{postgres.DATABASE_URL}} in staging means staging's database.

Environments share the project's people, balance and rules. Each has its own project id, and API keys made in an environment only work there.

In the dashboard: use the environment switcher at the top of the project.

From your terminal:

Terminal
cli environments create staging
cli up -e staging
cli environments rm staging

Add -e <name> to any command to run it against an environment.

Ask your agent:

"Make a staging environment where web deploys from the staging branch."

With the API:

API
POST /v1/projects/:id/environments
JSON
{ "name": "staging" }

To deploy a GitHub service in staging from another branch, set {"branch": "staging", "autoDeploy": true} on that service with PATCH /v1/services/:id.

Compare environments

When staging works and production doesn't, the difference is usually a variable. Compare two environments to see every difference: variables by name (secret values are compared without being shown), plans, copies and the version each one runs. Copy any variable across with one click; it applies on the next deploy.

In the dashboard: the project's Map tab, Compare environments.

Ask your agent:

"What's different between staging and production?"

With the API:

API
GET /v1/projects/:id/compare?with=<other environment's id>
POST /v1/projects/:id/compare/copy
JSON
{ "from": "<other environment's id>", "service": "web", "keys": ["STRIPE_KEY", "LOG_LEVEL"] }

The copy goes into the environment in the URL, from the same-named service in from.