From 9bbd9c8c78c6dbeaf183292ebe55e75d4a4069d8 Mon Sep 17 00:00:00 2001 From: "tembo[bot]" <208362400+tembo[bot]@users.noreply.github.com> Date: Fri, 31 Jul 2026 08:06:43 +0000 Subject: [PATCH 1/2] docs(sandbox): document sandbox environment variables Add a dedicated page covering workspace environment variables/secrets: how to add them (single and bulk .env import) in Settings > Sandbox, where they're injected (agent commands, hooks, snapshot setup scripts, MCP servers and integrations), security (encrypted at rest, write-only in the dashboard, workspace-scoped), constraints (unique keys, reserved TEMBO_ variables), and how to remove them. Also link the new page from custom-dependencies and snapshots, which already referenced sandbox environment variables without a target. --- docs.json | 1 + features/sandbox/custom-dependencies.mdx | 2 +- features/sandbox/environment-variables.mdx | 80 ++++++++++++++++++++++ features/snapshots.mdx | 2 +- 4 files changed, 83 insertions(+), 2 deletions(-) create mode 100644 features/sandbox/environment-variables.mdx diff --git a/docs.json b/docs.json index 5efaba3..43cfaf5 100644 --- a/docs.json +++ b/docs.json @@ -58,6 +58,7 @@ "pages": [ "features/sandbox/overview", "features/sandbox/custom-dependencies", + "features/sandbox/environment-variables", "features/snapshots" ] }, diff --git a/features/sandbox/custom-dependencies.mdx b/features/sandbox/custom-dependencies.mdx index 9aa6e46..306371e 100644 --- a/features/sandbox/custom-dependencies.mdx +++ b/features/sandbox/custom-dependencies.mdx @@ -106,7 +106,7 @@ Use `shellHook` when the sandbox needs environment variables for local commands: } ``` -Keep secrets out of `tembo.nix`. Add secrets through your sandbox environment variables instead. +Keep secrets out of `tembo.nix`. Add secrets through your sandbox [environment variables](/features/sandbox/environment-variables) instead. ## Tips diff --git a/features/sandbox/environment-variables.mdx b/features/sandbox/environment-variables.mdx new file mode 100644 index 0000000..53f6387 --- /dev/null +++ b/features/sandbox/environment-variables.mdx @@ -0,0 +1,80 @@ +--- +title: 'Environment Variables' +description: '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](/features/sandbox/overview). They're the recommended way to pass API keys, tokens, and other configuration to agent commands, [hooks](/features/hooks), MCP servers, and connected integrations — without committing secrets to your repository. + + + Environment variables are workspace-wide. Every session your workspace runs — agent runs and interactive terminal sessions — receives them in its sandbox environment. + + +## 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 +DEPLOY_TOKEN=abc123 +DATABASE_URL=postgres://user:pass@host:5432/db +SENTRY_DSN=https://examplePublicKey@o0.ingest.sentry.io/0 +``` + +## 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](/features/hooks)** — `postClone` and `prePush` commands run with the variables set. +- **[Snapshot](/features/snapshots) setup scripts** — variables are available while a snapshot is built and are baked into anything the setup script writes to disk. +- **[MCP servers](/integrations/mcp) 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 +{ + "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. 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](/features/agents#triggers), `TRIGGER_PAYLOAD`. Avoid using these names for your own variables, as Tembo's values take precedence. +- Keep secrets out of [`tembo.nix`](/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. diff --git a/features/snapshots.mdx b/features/snapshots.mdx index 4efa959..5ff8335 100644 --- a/features/snapshots.mdx +++ b/features/snapshots.mdx @@ -52,7 +52,7 @@ Tembo uses the latest successful snapshot for matching new sessions. Use the setup script to add project-specific tooling, dependencies, or other environment setup to your snapshot. Tembo runs the script while the snapshot is being built, after all selected repositories have been cloned to disk. -The script has access to all environment variables configured in **Settings** > **Sandbox**, including secrets your setup commands need. Anything the script installs or writes to disk becomes part of the snapshot and is available to sessions that start from it. +The script has access to all [environment variables](/features/sandbox/environment-variables) configured in **Settings** > **Sandbox**, including secrets your setup commands need. Anything the script installs or writes to disk becomes part of the snapshot and is available to sessions that start from it. ## Sizes and schedules From e0205c9dcd0924390d101df3c78e85422a260d0a Mon Sep 17 00:00:00 2001 From: "tembo[bot]" <208362400+tembo[bot]@users.noreply.github.com> Date: Fri, 31 Jul 2026 08:16:36 +0000 Subject: [PATCH 2/2] docs(sandbox): remove em dashes from environment variables page Replace em dashes with colons, commas, and periods per review feedback. Co-authored-by: Benjamin <16625915+benja@users.noreply.github.com> --- features/sandbox/environment-variables.mdx | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/features/sandbox/environment-variables.mdx b/features/sandbox/environment-variables.mdx index 53f6387..99e5406 100644 --- a/features/sandbox/environment-variables.mdx +++ b/features/sandbox/environment-variables.mdx @@ -3,10 +3,10 @@ title: 'Environment Variables' description: '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](/features/sandbox/overview). They're the recommended way to pass API keys, tokens, and other configuration to agent commands, [hooks](/features/hooks), MCP servers, and connected integrations — without committing secrets to your repository. +Environment variables let you store secrets and configuration once and have Tembo inject them into every session's [sandbox](/features/sandbox/overview). They're the recommended way to pass API keys, tokens, and other configuration to agent commands, [hooks](/features/hooks), MCP servers, and connected integrations, without committing secrets to your repository. - Environment variables are workspace-wide. Every session your workspace runs — agent runs and interactive terminal sessions — receives them in its sandbox environment. + Environment variables are workspace-wide. Every session your workspace runs, including agent runs and interactive terminal sessions, receives them in its sandbox environment. ## Prerequisites @@ -20,8 +20,8 @@ Environment variables let you store secrets and configuration once and have Temb 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. + - **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: @@ -36,10 +36,10 @@ SENTRY_DSN=https://examplePublicKey@o0.ingest.sentry.io/0 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](/features/hooks)** — `postClone` and `prePush` commands run with the variables set. -- **[Snapshot](/features/snapshots) setup scripts** — variables are available while a snapshot is built and are baked into anything the setup script writes to disk. -- **[MCP servers](/integrations/mcp) and integrations** — reference a variable so a server or integration can authenticate. +- **Agent commands**: the agent can read the variable when it runs builds, tests, or scripts. +- **[Hooks](/features/hooks)**: `postClone` and `prePush` commands run with the variables set. +- **[Snapshot](/features/snapshots) setup scripts**: variables are available while a snapshot is built and are baked into anything the setup script writes to disk. +- **[MCP servers](/integrations/mcp) 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: @@ -61,19 +61,19 @@ For example, reference a variable in a `globalMcpServers` definition instead of ## 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. There is no way to reveal a stored value. +- **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. +- 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](/features/agents#triggers), `TRIGGER_PAYLOAD`. Avoid using these names for your own variables, as Tembo's values take precedence. - Keep secrets out of [`tembo.nix`](/features/sandbox/custom-dependencies) and out of your repository. Store them here instead. ## Remove a variable -1. Open **Settings** → **Sandbox**. +1. Open **Settings** > **Sandbox**. 2. Find the variable in the **Environment Variables** table. 3. Open the row menu and select **Delete**.