docs(sandbox): document bring your own deps

[Coleary005]

Adds bring your own deps (BYOD) to Custom Dependencies, and reframes the page around the three ways to get tooling into the sandbox instead of just two.

What changed

• Comparison table up top — setup script vs. tembo.nix vs. bring your own deps, with what you write, the scope, and what each is best for.
• New "Bring your own deps" section covering:
  • what the agent reads (Dockerfile/compose, devcontainer.json, .tool-versions/.nvmrc/.python-version/etc., language manifests and lockfiles, existing Nix files)
  • how to generate an environment: Settings > Projects > New project > Install dependencies > Advanced setup > BYOD environment > Generate environment
  • the Bring Your Own Deps: <name> generation session and the building / ready / failed statuses, plus the note that the badge doesn't auto-refresh
  • the environment being workspace-wide rather than per-project
  • needing to build/rebuild the project environment for it to take effect, and that the full dev shell is captured (not just PATH)
  • reviewing/editing the flake, with a warning that a manual edit clears the pinned flake.lock
• New "How the approaches combine" section — the most important correction for readers: BYOD does not replace tembo.nix. Each selected repo's tembo.nix is merged into the generated dev shell and wins on conflicts, and setup scripts still run on top, inside the environment.
• Existing tembo.nix content is unchanged, just nested under its own heading.

Availability framing

BYOD is currently gated to internal users, org admins, and the Max/Enterprise entitlement, so it is not reachable in production yet. I documented it as early access, not yet enabled for every workspace, with a book-a-call link — matching how tembo.nix and Projects are already framed on the site. Happy to soften it to internal-only, or hold the section behind a follow-up, if you'd rather it not be public until the feature ships.

Verification

mint broken-links passes with no broken links.

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

      

---

Note

^{Cursor Bugbot is generating a summary for commit 96c4a3d. Configure here.}

[mintlify]

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

Project	Status	Preview	Updated (UTC)
tembo	🟢 Ready	View Preview	Aug 18, 2026, 3:52 PM

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

[tembo]

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

• features/sandbox/custom-dependencies.mdx

[tembo]

Holding this PR for two blockers:

1. The feature has not shipped. The implementation is still open in tembo/monorepo#10109, currently has changes requested, and its lint check is failing. The BYOD API, UI, and database model are absent from main and the latest published release, v0.2.828, so there is no successful production release/deployment supporting these instructions yet.

2. The documented architecture no longer matches the implementation branch. This PR says BYOD is one workspace-wide environment and that regenerating from any project replaces it. The current implementation defines one Environment per project (projectId @unique) and the UI says it is used by that project’s sessions. This PR also tells users to build/rebuild after generation, while finalizeEnvironment now automatically enqueues and auto-promotes the project’s golden builds. On project creation, the current UI uses a BYOD checkbox and starts generation after the project is created rather than asking the user to click Generate environment in the creation flow.

Recommendation: do not merge yet. Update the docs to the final product behavior after monorepo#10109 merges, appears in a published Tembo release, and that release is successfully deployed to production.