---
title: "Environment variables & secrets"
description: "Manage API keys, tokens, and workflow settings per cluster."
image: "https://tilebox.com/images/tilebox-docs-social-preview.png"
---

> Documentation Index
> Fetch the complete documentation index at: https://tilebox.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Environment variables & secrets

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](https://console.tilebox.com/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](/docs/workflows/concepts/runners#release-runners) 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](/docs/workflows/concepts/runners#direct-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.

Source: https://tilebox.com/docs/workflows/build-and-deploy/environment-variables/index.mdx
