Cloud hosting
How Trellis Cloud provisions E2B sandboxes, starts Studio, and common provisioning errors.
Cloud hosting
studio.trellis.computer runs your projects inside E2B sandboxes: one VM per user workspace, with each project as a subdirectory under /home/user/workspace. A broker (api.studio.trellis.computer in production) creates sandboxes, installs or verifies the trellis and turtlecode CLIs, starts Trellis Studio on port 3333, and materializes project folders with trellis init.
For agent LLM routing and metering, see Cloud AI proxy. For static publish URLs, see Publish to the web.
Architecture
| Layer | Role |
|---|---|
Cloud dashboard (cloud/web/) | Auth, project list, Studio iframe shell |
Broker (cloud/src/server.ts) | Workspace and project CRUD, background provisioning |
E2B template (cloud/template/) | Base image, global CLI packages, startCmd supervisor |
| Sandbox | One VM per workspace; projects are subdirectories |
When you create a workspace:
POST /workspacesets InstantDBstatus: provisioning.- The broker calls
provisionStudio()→Sandbox.create(templateId). - The template
startCmdrunstrellis initand a supervisor loop aroundtrellis studio --port 3333. - The broker probes the Studio HTTPS URL until ready or timeout.
- If Studio is not reachable,
startStudioInSandbox()verifies CLIs, may restart Studio, then marks the workspaceready.
When you create a project, the broker assumes the workspace sandbox is already ready, then runs trellis init inside the project subdirectory (scratch, GitHub clone, or starter template).
Studio stack inside the sandbox
Each workspace runs two cooperating processes:
| Port | Process | Role |
|---|---|---|
| 3333 | trellis studio / turtlecode | Serves the Studio UI and proxies API calls from the browser |
| 4096 | opencode serve | OpenCode backend (sessions, prompt_async, providers, tools) |
The browser talks to E2B on port 3333 (with a base64url workspace path prefix). turtlecode strips that prefix and forwards API traffic to 4096.
When the broker upgrades turtlecode after a sandbox has already booted, it must restart both ports. Restarting only 3333 leaves an old opencode serve on 4096 that may lack routes such as POST /session/{id}/prompt_async, which surfaces in the UI as Method Not Allowed before any LLM or gateway call runs.
killStudioStackCommand() in cloud/src/studio-shell.ts stops listeners on 4096 and 3333 (via lsof, not pkill -f) before startStudioInSandbox launches a fresh stack.
CLI on PATH inside sandboxes
Global CLIs are installed with npm install -g trellis turtlecode in the E2B template. The template startCmd runs in an environment where those binaries are usually available.
Broker-driven commands use E2B commands.run, which often starts a minimal non-login shell without npm's global bin directory on PATH. That produced trellis: command not found (exit status 127) during project provisioning even when Studio was already running from the template.
The broker now wraps sandbox shell commands with wrapSandboxShell() in cloud/src/studio-shell.ts, prepending:
export PATH="$(npm bin -g 2>/dev/null):/usr/local/bin:/root/.bun/bin:$PATH"
ensureStudioCli also checks command -v trellis before skipping reinstall when only turtlecode --version matches.
Troubleshooting
| Symptom | What to check |
|---|---|
Provisioning failed / trellis: command not found | Broker build includes the PATH wrap; restart the broker and use Reconnect sandbox on the project. Rebuild the E2B template after template changes (just template-build in cloud/). |
signal: terminated when opening a project | Stale broker using pkill -f plus E2B background mode; upgrade broker and see operator notes in cloud/docs/sandbox-provisioning.md. |
| Sandbox not ready in time | Workspace still provisioning or failed; check Activity and provision logs. |
| Studio did not respond | In the sandbox: tail /tmp/trellis-studio.log. |
GET /project/.../meta 404 in the browser console | Often harmless status-bar polling when the project id is stale or provisioning failed; fix provisioning first. Deploy latest broker for POST /workspace/meta/sync. |
Method Not Allowed when sending a chat | Stale OpenCode on port 4096 after a turtlecode upgrade; use Reconnect sandbox (broker must kill 4096 and 3333 on restart). Not an AI gateway failure — see Cloud AI proxy. |
POST .../prompt_async failed in DevTools | Same as above: fix the in-sandbox Studio stack before debugging trellis-cloud / Vercel AI Gateway. |
Event stream / global/event network errors | Usually follow-on noise when the sandbox or Studio is not healthy. |
Local development
cd cloud
bun run dev # broker :8787 + web :3838
bun run logs # tail .logs/provision.log
curl http://localhost:8787/health
Set TRELLIS_E2B_TEMPLATE in cloud/.env to your built template id. The web app uses VITE_BROKER_URL=http://localhost:8787.
Operator detail (sequence diagrams, E2B audit commands, template rebuild): cloud/docs/sandbox-provisioning.md in the trellis-cloud repo.