docs(sandbox): document tembo.nix loading, project caching, and troubleshooting

[tembo]

Summary

Documents how Tembo actually loads tembo.nix, how project environments cache the resulting toolchain, and the two failure modes that currently produce silent "my dependencies are missing" reports. All claims were verified against tembo/monorepo source — no behavior was inferred.

Docs updated

features/sandbox/custom-dependencies.mdx (+24 lines, one file, no navigation changes):

• How Tembo loads tembo.nix — Tembo temporarily replaces the repo's flake.nix with tembo.nix, evaluates the default dev shell, then restores the original. Adds the four consequences that follow: tembo.nix must be a self-contained flake (no merging), an existing flake.nix is never used for the dev shell, flake.lock is never written (so pin nixpkgs yourself), only the repo root is read, and unfree packages are permitted.
• Dependencies in projects — the toolchain is evaluated once at build time and cached, so edits to tembo.nix don't reach project sessions until a rebuild or the daily refresh.
• Troubleshooting — a tembo.nix that fails to evaluate does not fail the project build; the build succeeds without the dependencies. Points readers at the nix develop step in the build log.

Codepaths covered

Documented behavior	Source
flake swap + restore in finally	apps/api/src/agent/sandbox/temboConfig.ts:109-134, apps/api/src/services/hypervisor/qemu/prepare.ts:305-350
Unfree allowed; no attr path passed to nix develop	apps/api/src/agent/sandbox/sandboxExecWrapper.ts:22-33
--no-write-lock-file everywhere	sandboxExecWrapper.ts:32, prepare.ts:311-313
Toolchain baked at build time, PATH frozen into the snapshot	prepare.ts:284-354, apps/api/src/services/hypervisor/constants.ts:28,36-45
Cached PATH reused by session commands (incl. subdirectories)	apps/api/src/agent/sandbox/exec.ts:208-209, apps/api/src/services/hypervisor/utils.ts:11-25
Nix eval failure is warn-and-continue; build still succeeds	prepare.ts:330-341
includeDeps defaults on in project setup	apps/web/components/projects/project-setup.tsx:117

Knowledge gaps addressed

The page previously described how to write a tembo.nix but nothing about how Tembo consumes it. That left three questions unanswerable from the docs: why a repo's own flake.nix is ignored, why tembo.nix edits appear to do nothing in project sessions, and why dependencies can be missing from an environment whose build reported success.

Verified separately — needs an engineering decision, not documented here

While tracing .tembo.json I found two divergences between features/hooks.mdx and current main. I deliberately left the page unchanged rather than document what look like regressions from chore(api): disable legacy sandbox tasks (#9032).

1. prePush never runs. features/hooks.mdx documents it as running before Tembo pushes and opens a PR. runHook('prePush') has zero live call sites — the only two are commented out in solve_issue/index.ts:742 and feedback_loop/index.ts:771, both in tasks disabled by #9032 (2026-06-26). The Zod schema still accepts the key, so a prePush block is silently ignored. (Unrelated: the guest CLI does run git's own pre-push hook in agent/guest/cli/commands/commit.ts:171-259, which is a different mechanism.)

2. Repo-root .tembo.json is not read during sessions. The page says to put the file at your repository root. In agent_run, TemboConfig.loadFromSandbox reads .tembo.json relative to sandbox.getCwd() (temboConfig.ts:60-61), which is still the default /workspace — refreshRepos never calls setCwd, unlike cloneRepo (git/index.ts:369). Repos are cloned to /workspace/<repo-name> (nix/sandbox/tembo-refresh-repos.nix:160), so /workspace/.tembo.json does not exist and session setupScript hooks are a no-op. The golden/project build path does set cwd per repo (prepare.ts:264), so hooks work correctly there.

Happy to follow up with a docs PR once you decide whether these are fixed in code or documented as-is.

Two smaller hooks.mdx gaps that are intentional and safe to document whenever the above is settled: postClone is a supported legacy alias for setupScript (temboConfig.ts:9-20), and setupScript is deliberately skipped when a session resumes from a snapshot or prepared project environment (sandboxTask.ts:216-229).

Validation

npx mint broken-links → no broken links found.

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

      

---

Note

Low Risk
Documentation-only change to sandbox custom-dependencies docs; no code or runtime behavior is modified.

Overview
Documents how Tembo actually consumes tembo.nix, not just how to write one.

Adds that Tembo temporarily swaps flake.nix with tembo.nix (no merge, no flake.lock, root-only, unfree allowed), that project builds cache the toolchain so edits need a rebuild, and that a failed Nix eval still succeeds the project build without dependencies.

^{Reviewed by Cursor Bugbot for commit 62a65ba. 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	Aug 21, 2026, 8:15 AM

💡 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