Sandbox / Dev Mode

Live development environments with hot reload.

Sandboxes are live development environments with hot reload. Changes apply instantly without a full rebuild — much faster for iterating.

CLI: berth dev

berth dev              # Start dev sandbox with file watcher
berth dev App.jsx      # Single-file dev with hot reload
berth dev --attach id  # Reattach to existing sandbox

The CLI watches your local files and pushes changes to the sandbox as you edit. For Node/Vite projects, changes appear via HMR (Hot Module Replacement). For Go, the sandbox automatically rebuilds the binary.

MCP: sandbox tools

AI tools use these MCP tools for the same workflow:

  1. berth_sandbox_create — create the sandbox with initial files
  2. berth_sandbox_push — push file changes (instant, no rebuild)
  3. berth_sandbox_install — add or remove packages
  4. berth_sandbox_exec — run commands inside the container
  5. berth_sandbox_logs — check logs for errors
  6. berth_sandbox_promote — ship it to production when ready

HTTP API

Endpoint Description
POST /api/sandbox Create a sandbox (JSON body with files)
POST /api/sandbox/{id}/push Push file changes
POST /api/sandbox/{id}/install Install packages
POST /api/sandbox/{id}/exec Run a command
GET /api/sandbox/{id}/logs Get logs
DELETE /api/sandbox/{id} Destroy sandbox
POST /api/sandbox/{id}/promote Promote to production

Promote to production

When you’re happy with your sandbox, promote it. This stops the dev server, runs a full optimized build, and starts a production runtime. The URL stays the same.

berth promote abc123