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

# Environment Variables

> Store secrets and configuration that Tembo injects into every sandbox session.

Environment variables let you store secrets and configuration once and have Tembo inject them into every session's [sandbox](https://docs.tembo.io/features/sandbox/overview.md). They're the recommended way to pass API keys, tokens, and other configuration to agent commands, [hooks](https://docs.tembo.io/features/hooks.md), MCP servers, and connected integrations, without committing secrets to your repository.

> [!NOTE]
>
> Environment variables added in **Settings** > **Sandbox** are workspace-wide. Every session your workspace runs, including agent runs and interactive terminal sessions, receives them in its sandbox environment. You can also add [personal environment variables](#personal-environment-variables) that are only injected into sessions you start, and [project-level environment variables](https://docs.tembo.io/features/projects.md#project-environment-variables) that are only injected while that project's environments are built.

## Prerequisites

* You have access to your Tembo workspace settings.
* You know the keys and values your project needs at runtime.

## Add a variable

1. Open **Settings**.
2. Go to **Sandbox**.
3. Under **Environment Variables**, click **Create Secret**.
4. Add variables one of two ways:
   * **Single Variable**: enter a **Key** (for example `CLIENT_KEY`) and its **Value**.
   * **Bulk Import**: paste `.env`-style contents, one `KEY=value` per line.
5. Click **Create Secret**.

For bulk import, each line must use the `KEY=value` format. Blank lines and lines without a value are skipped:

```bash theme={null}
DEPLOY_TOKEN=abc123
DATABASE_URL=postgres://user:pass@host:5432/db
SENTRY_DSN=https://examplePublicKey@o0.ingest.sentry.io/0
```

## Personal environment variables

Add personal environment variables for credentials that belong to you alone, such as your own GitHub, npm, or Linear tokens. They're only injected into sessions you start, and other workspace members can't see or use them.

1. Open **Settings**.
2. Go to **Preferences**.
3. Under **Personal environment variables**, click **Create Secret**.
4. Add a **Single Variable** or use **Bulk Import**, then click **Create Secret**.

If a personal variable uses the same key as a workspace-wide variable, your personal value takes precedence in your sessions. Tembo's reserved variables still take precedence over both. Each user can have at most 100 personal environment variables per workspace. To remove one, open its row menu under **Personal environment variables** and select **Delete**.

## How variables are used

Once saved, a variable is available in the sandbox for the whole session. You can use it from:

* **Agent commands**: the agent can read the variable when it runs builds, tests, or scripts.
* **[Hooks](https://docs.tembo.io/features/hooks.md)**: `setupScript` and `prePush` commands run with the variables set.
* **[Project](https://docs.tembo.io/features/projects.md) setup scripts**: variables are available while a project's environments are built and are baked into anything the setup script writes to disk.
* **[MCP servers](https://docs.tembo.io/integrations/mcp.md) and integrations**: reference a variable so a server or integration can authenticate.

For example, reference a variable in a `globalMcpServers` definition instead of hardcoding the value:

```json theme={null}
{
  "mcpServers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "$GITHUB_TOKEN"
      }
    }
  }
}
```

## Security

* **Encrypted at rest.** Values are encrypted before they're stored.
* **Write-only in the dashboard.** After you save a variable, the value is hidden. The list shows only the key and when it was created, and there is no way to reveal a stored value.
* **Scoped to your workspace.** Variables are only injected into sessions that belong to the workspace where you created them.

## Constraints

* Keys are unique within a workspace.
* To rotate or change a value, delete the variable and create it again. Values can't be edited in place because they're hidden after saving.
* Tembo injects its own reserved variables into every session, including `TEMBO_`-prefixed variables and, for [triggered agents](https://docs.tembo.io/features/agents.md#triggers), `TRIGGER_PAYLOAD`. Avoid using these names for your own variables, as Tembo's values take precedence.
* Keep secrets out of [`tembo.nix`](https://docs.tembo.io/features/sandbox/custom-dependencies) and out of your repository. Store them here instead.

## Remove a variable

1. Open **Settings** > **Sandbox**.
2. Find the variable in the **Environment Variables** table.
3. Open the row menu and select **Delete**.

Deletion is immediate and can't be undone. New sessions will no longer receive the variable.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.