Skip to content

Environment variables & secrets

Manage API keys, tokens, and workflow settings per cluster.

Store credentials and settings in Tilebox and assign them to clusters. Your workflows read them from Python’s os.environ, so the same release can use different API keys or settings in development and production.

Add variables

In the Console

Open Workflows → Environment and choose Add variable. Enter a name and value, keep Secret enabled for credentials, and choose All clusters or Selected clusters.

You can also import a .env file with Bulk import, or manage variables from a cluster’s details page.

With the CLI

Create a shared setting and a secret for an existing cluster:

bash
tilebox variable create SERVICE_API_URL \
  https://api.example.com --all-clusters
tilebox variable create SERVICE_API_KEY \
  --secret --cluster dev-cluster \
  --value-file ./service-api-key.txt

Use --secret for credentials and read their values from a file instead of putting them in shell arguments. The file should contain only the credential; keep it out of source control.

Inheritance and overrides

Variables assigned to All clusters apply to current and future clusters. A value assigned to specific clusters overrides the shared value with the same name:

bash
tilebox variable create SERVICE_API_URL \
  https://sandbox.example.com --cluster dev-cluster

Now dev-cluster uses https://sandbox.example.com, while other clusters use https://api.example.com. Deleting the override restores the shared value.

Repeat --cluster to share an entry across several clusters. Editing that entry changes it for every assigned cluster. Use --cluster '' to select only the default cluster; omitting scope flags on create means all clusters.

Use variables in a workflow

Start a release runner for the cluster where your workflow is deployed:

bash
tilebox runner start --cluster dev-cluster

The runner picks up the cluster’s variables automatically. Read them inside your tasks:

python
import os

api_url = os.environ["SERVICE_API_URL"]
api_key = os.environ["SERVICE_API_KEY"]

When the environment changes, the runner automatically restarts the Python workflow processes with the new values. You can leave the runner running; no new release or manual restart is needed.

This applies to release runners started with the CLI. For direct SDK runners, configure the environment through your own deployment system.

View and update variables

Inspect the variables for a cluster or replace a secret:

bash
tilebox variable list --cluster dev-cluster
tilebox variable update SERVICE_API_KEY --cluster dev-cluster \
  --value-file ./rotated-service-api-key.txt

Secrets stay hidden unless you reveal them in the Console or pass --reveal to tilebox variable get. Workflow code receives the full value, so avoid logging secrets or dumping os.environ.

Run tilebox variable --help for all commands and options.

Type to search…