docs(sandbox): document sandbox environment variables

[tembo]

Summary

Adds a dedicated Environment Variables page under Sandbox docs. Sandbox environment variables (workspace secrets) were referenced in several existing pages but had no page of their own explaining how to configure or use them — this closes that gap.

Docs added/updated

• New: features/sandbox/environment-variables.mdx — how to add variables (single + bulk .env import) in Settings > Sandbox, where they're injected, security posture, constraints, and how to remove them.
• Nav: added the new page to the Sandbox group in docs.json.
• Updated cross-links: features/sandbox/custom-dependencies.mdx and features/snapshots.mdx already mentioned sandbox environment variables — both now link to the new page instead of dangling.

Codepaths covered (verified against source in the monorepo)

• Storage/model: OrganizationSecret (packages/database/schema.zmodel) — value is @encrypted (encrypted at rest) and @omit (never returned in reads → write-only in UI); unique per (key, organizationId); scoped by @@allow('all', auth().orgId == organizationId).
• Encryption setup: apps/api/src/db/index.ts (getEncryptionKey, ZenStack encryption extension).
• UI: apps/web/components/sandbox/environment-variables/* (single + bulk KEY=value import, hidden values, delete) mounted on the Settings > Sandbox page (apps/web/app/[slug]/(sidebar)/settings/sandbox).
• Injection into sessions: envVarsForOrganization (apps/api/src/agent/sandbox/utils.ts) used by agent_run and start_terminal_session; envVarsForGoldenBuild (apps/api/src/services/hypervisor/goldenEnv.ts) for snapshot builds. Reserved TEMBO_* variables and TRIGGER_PAYLOAD take precedence over org secrets.
• Hooks context: apps/api/src/agent/sandbox/temboConfig.ts (postClone / prePush run with these env vars).

Key knowledge gaps addressed

• Where to set sandbox secrets and the single vs. bulk .env import flow.
• Which surfaces actually receive them (agent commands, hooks, snapshot setup scripts, MCP servers/integrations).
• Security guarantees (encrypted at rest, values hidden after saving, workspace-scoped).
• Constraints: unique keys, reserved TEMBO_/TRIGGER_PAYLOAD names, rotate-by-recreate.

Documentation-only change; no code paths modified. No merge conflicts with main.

Want tembo to make any changes? Add a comment with @tembo and i'll get back to work!

---

Note

Low Risk
Documentation-only change with no application code or runtime behavior modified.

Overview
Adds a dedicated Environment Variables doc under Sandbox and wires it into the docs nav.

The new page explains how to create workspace secrets in Settings > Sandbox (single key/value or bulk .env import), where Tembo injects them (agent runs, hooks, snapshot setup scripts, MCP/integrations), and the security/constraints model (encrypted at rest, write-only values, unique keys, rotate-by-recreate, reserved TEMBO_* / TRIGGER_PAYLOAD names).

custom-dependencies.mdx and snapshots.mdx now link to this page where they already told users to use sandbox env vars instead of committing secrets.

^{Reviewed by Cursor Bugbot for commit e0205c9. Bugbot is set up for automated code reviews on this repo. Configure here.}

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
tembo	🟢 Ready	View Preview	Jul 31, 2026, 8:08 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[tembo]

Requesting review from @benja who has experience with the following files modified in this PR:

• docs.json

[benja]

@tembo don't use em dash

[tembo]

@tembo don't use em dash

done, @benja. removed all em dashes from the environment variables page and pushed to the same branch, so pr #667 is updated.

what changed:

• swapped em dashes for colons in the bulleted lists and the "add a variable" steps
• used commas / "including ..." for the inline asides in the intro and note
• split the two sentences in the security and constraints sections into clean periods
• also normalized the one "→" arrow to ">" for consistency with the rest of the docs

verified there are no remaining em dashes across all files in the pr, docs.json is still valid json, and the branch has no merge conflicts with main.

#667