Sandbox apps

A Sandbox App is a disposable, containerized coding environment with a real terminal, a file editor, and a live preview URL — no local setup required. Pick a framework template and Shipyard scaffolds it with the official CLI, installs dependencies, and boots the dev server automatically. Or start from a blank Custom container and scaffold whatever you want by hand.

#Quick start

1. Inside a project, click New App and choose a Sandbox App
2. Pick a template — a framework (React, Vue, SvelteKit, Next.js, Nuxt, Astro), a basic runtime (Node, Python, Static), or Custom for a blank container
3. Give it a name — the slug is generated automatically — and click Create App
4. Open the app to reach the editor: on first boot, Shipyard scaffolds the template, installs dependencies, and starts the dev server
5. Edit files, use the terminal, and watch the Preview tab update live

#Basic templates

Four built-in starting points beyond the framework gallery below. Each resolves to a fully-declared runtime at creation time — nothing to detect.

#Framework gallery

Each framework template invokes that framework's own official, non-interactive scaffolder on first boot — the same command you'd run on your own machine. Dependencies install as a separate, explicit step, then the dev server starts bound to 0.0.0.0 and the sandbox's assigned port so the preview can actually reach it.

#Scaffold your own (Custom mode)

Choose the Custom template to skip the gallery entirely. It boots an empty, idle container — nothing installed, no dev server running — so you can scaffold exactly what you want by hand from the Terminal tab.

#The workflow

# Inside the sandbox's Terminal tab
npx create-react-app .
# or: npm create vite@latest . -- --template svelte
# or literally anything else — it's just a shell

# Then, from the app's canvas panel:
#   Stop  ->  Start
# Shipyard re-detects the real stack and boots its dev server.

Shipyard only re-checks what's in the container when the sandbox restarts — it never watches the filesystem while it's running. That's why the last step is always Stop, then Start, from the app's canvas panel: that recreates the container and re-runs stack detection against whatever you scaffolded.

#Prefer to declare it yourself?

A Custom sandbox starts with a starter file at /app/shipyard.json.example. Rename it to shipyard.json, fill in your own values, and restart — Shipyard trusts an explicit manifest over guessing from files on disk. See the manifest format below.

#shipyard.json manifest

Every sandbox — template-created or Custom — can be pointed at an explicit manifest instead of relying on auto-detection. Drop a shipyard.json file in the project root and restart the sandbox.

{
  "app": {
    "runtime": "node",
    "install": "npm install",
    "dev": "npm run dev",
    "port": 3000
  }
}

#Editor & files

Opening a sandbox app lands you on its editor page: a file tree on the left, a code editor in the center, and Preview / Terminal alongside it.

#File tree

• Click any file to open it in the editor
• Create new files directly from the tree — folders are created automatically from the path you type
• Changes autosave as you type; a save indicator confirms when a write completes

#Hot reload

Saving a file that the running dev server watches (which is every framework template — that's exactly what npm run dev is for) reflects in the Preview tab automatically, the same as running the dev server on your own machine.

#Preview sizing

The Preview tab includes desktop and mobile width presets, plus a free-drag handle, so you can sanity-check responsive layouts without leaving the editor.

#Terminal

A real shell into the running sandbox container, always available below the Editor/Preview panel — not a separate tab you have to switch to. Use it to run scaffolding CLIs, install extra packages, inspect logs, or debug directly.

#Live preview

Every sandbox gets its own preview URL, routed through Traefik straight to the running dev server:

https://preview-a1b2c3d4.shipyard-apps.dev

The preview link works for anyone with the URL — no Shipyard login required — so you can share a running sandbox with a teammate or a client directly.

#Idle timeout & quota

Sandboxes are meant to be disposable, not long-running services — Shipyard stops them automatically when nobody's using them, and caps how many can run at once per organization.

#Idle timeout

While the editor tab is open it sends a periodic heartbeat. A sandbox with no heartbeat for 20 minutes (the default; configurable per deployment) is automatically stopped — its files and data are untouched, only the running container and dev server are torn down. Opening the app again starts it right back up.

#Concurrent sandbox limit

Each plan sets a maximum number of sandboxes that may be running or starting at the same time across the whole organization. Stop an unused sandbox — or wait for one to idle out — to free up a slot.