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:
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.txtUse --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:
tilebox variable create SERVICE_API_URL \
https://sandbox.example.com --cluster dev-clusterNow 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:
tilebox runner start --cluster dev-clusterThe runner picks up the cluster’s variables automatically. Read them inside your tasks:
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:
tilebox variable list --cluster dev-cluster
tilebox variable update SERVICE_API_KEY --cluster dev-cluster \
--value-file ./rotated-service-api-key.txtSecrets 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.