Sandboxes

Running commands on another branch usually requires stashing uncommitted work or maintaining a separate git worktree with its own dependencies.

Tessera creates Copy-on-Write branch sandboxes that reuse your existing dependencies and assign each session its own port and test database.

Running Commands

With shell integration enabled (tes env --install), switch a terminal tab to any branch and run your test or build commands directly:

tes switch feat/pricing
npm test
npm run build

Open a second terminal tab, switch it to another branch, and run tests there at the same time:

tes switch feat/faq
npm test

Each terminal tab executes against its own branch's files and dependencies without interfering with other tabs.

Running Dev Servers

To preview two feature branches in your browser at the same time, switch each terminal tab to its branch and start your dev server:

Terminal 1:

tes switch feat/pricing
npm run dev
# TES_PORT=4100

Terminal 2:

tes switch feat/faq
npm run dev
# TES_PORT=4200

Or run them explicitly with tes exec -b <branch>:

# Terminal 1
tes exec -b feat/pricing -- npm run dev -- --port 4100

# Terminal 2
tes exec -b feat/faq -- npm run dev -- --port 4200

One-Off Commands

Use tes exec to run a command inside a branch's Copy-on-Write sandbox without switching your terminal tab:

# Run on the current session's branch
tes exec -- npm run build

# Run on a specific branch
tes exec -b feat/pricing -- npm run build
tes exec -b feat/faq -- ./node_modules/.bin/vue-tsc -b

When tes exec runs:

1. Tessera materializes the branch's committed files plus any uncommitted changes for that branch into its sandbox.
2. Dependency and build cache directories (node_modules, target, .venv, vendor) are cloned via Copy-on-Write.
3. <sandbox>/node_modules/.bin, <sandbox>/.venv/bin, and <sandbox>/vendor/bin are prepended to PATH.
4. Any new or modified source files generated by the command (such as codegen output or lockfile updates) are captured back into the branch state.

Dependency Caches

Tessera clones and synchronizes dependency and build caches across major ecosystems:

Ecosystem	Cached Directories
JavaScript / TypeScript	node_modules, .pnpm-store, .next, .nuxt, .svelte-kit, .turbo, .parcel-cache, .vite
Rust	target (plus shared CARGO_TARGET_DIR support)
Python	.venv, venv, .pytest_cache, .mypy_cache, .ruff_cache, .tox
Go / PHP / Ruby	vendor, .bundle
Elixir / Erlang	_build, deps
JVM / Swift / C++	.gradle, build, .build, cmake-build-debug, cmake-build-release
Zig / .NET / Dart	.zig-cache, zig-out, bin, obj, .dart_tool

Tip: If you run npm install in your project root after a branch sandbox was already created, Tessera syncs the newly installed node_modules into the branch sandbox on the next tes exec run.

Environment Variables

Each session slot (1, 2, 3, ...) receives non-overlapping environment variables:

Variable	Slot 1	Slot 2	Description
PORT / TES_PORT	4100	4200	Calculated as base_port + (slot * port_stride)
TES_BRANCH	feat/pricing	feat/faq	Target branch name for the session
TES_DB_NAME	tessera_slot_1	tessera_slot_2	Isolated database name for integration tests
DATABASE_URL	sqlite:///.../tessera_slot_1.db	sqlite:///.../tessera_slot_2.db	Isolated database connection URL

To customize base_port, port_stride, or custom environment variable templates, see the Configuration Guide.