Skip to main content
Environment variables let you store secrets and configuration once and have Tembo inject them into every session’s sandbox. They’re the recommended way to pass API keys, tokens, and other configuration to agent commands, hooks, MCP servers, and connected integrations, without committing secrets to your repository.
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 that are only injected into sessions you start, and project-level 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:

​
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: setupScript and prePush commands run with the variables set.
  • Project 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 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:

​
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, TRIGGER_PAYLOAD. Avoid using these names for your own variables, as Tembo’s values take precedence.
  • Keep secrets out of tembo.nix 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.