trellis

WebContainer sandbox

Run the Trellis CLI in the browser via StackBlitz WebContainer — local dev host and static Vercel deploy.

4.0.1+: Trellis ships a WebContainer path for trying the CLI in the browser without provisioning a cloud VM. This is not the same product as Trellis Cloud (E2B sandboxes + Studio on studio.trellis.computer).

SurfaceWhat it is
WebContainer sandboxStackBlitz WebContainer in your browser; host vendored dist/ + deps
Trellis CloudBroker-provisioned E2B VM with Studio, OpenCode, and optional AI proxy

Local dev

From a trellis checkout (or after npm install trellis with a built dist/):

npm run build
trellis sandbox serve
# → http://127.0.0.1:4321

The host sets Cross-Origin-Opener-Policy and Cross-Origin-Embedder-Policy so WebContainer can spawn. The page loads a terminal that boots Trellis inside the browser runtime.

Options:

trellis sandbox serve --port 4321 --host 127.0.0.1
trellis sandbox serve -P /path/to/trellis/package/root

Requires npm run build — serve reads from dist/ on disk.

Static deploy (Vercel)

For a static host (no Node server at runtime), pack bootstrap JSON at build time:

npm run build
trellis sandbox pack -o public/bootstrap.json

Deploy apps/wc-sandbox/ (or your own static shell) with the same COOP/COEP headers. The Vercel config in the kernel repo rewrites /api/bootstrap to bootstrap.json.

# From trellis-node repo root (operator path)
cd apps/wc-sandbox && bash scripts/vercel-prebuilt.sh

How packing works

trellis sandbox pack serializes:

  • Trellis dist/ JS (and maps)
  • A minimal runtime package.json (CLI launcher + sql.js, commander, etc.)
  • Native-module stubs so WebContainer never runs npm install in-browser

SQLite in the browser uses sql.js (WASM), not better-sqlite3.

CI verification

Kernel maintainers can gate WebContainer boot with Playwright (opt-in):

WC_E2E=1 npm run test:wc:e2e

Legacy alias for the local host: npm run test:wc.

Related

Cloud hosting

How Trellis Cloud provisions E2B sandboxes, starts Studio, and common provisioning errors.

Vision

The thesis behind Trellis: one graph, projections instead of apps, reasoning as data, and seven design principles each with a test that keeps it honest.

PrivacyCookiesWhich Trellis?