Sandboxes
An isolated machine per environment, started from a project on the provider of your choice.
A sandbox is an isolated Linux machine built from a project (or from a bare image), started by a provider app installed in your organization. It belongs to the member who created it.
Every provider implements the same contract, so a sandbox looks the same wherever it runs. The ones available to your organization are listed in Settings → Integrations (category Sandboxes), and over the API:
GET /api/orgs/:orgId/sandboxes/providers- Spunto Cloud — Spunto's machines, on a plan of your organization (Settings → Billing): credits spent per running minute, a paused sandbox costs nothing.
- BYOC — your own machines — machines you connect to the BYOC app: each one runs a small daemon, installed with one line from the app's page, that connects outbound to the app. A machine belongs to one organization.
- Google Cloud — one VM per sandbox, in a project and zone of your own Google Cloud account.
A provider may offer sizes, locations or a catalog of machine types; pick one when creating the sandbox, or let the provider choose.
From a project page, New sandbox — or over the API:
curl -X POST https://spunto.net/api/orgs/$ORG/sandboxes \
-H "Authorization: Bearer $SPUNTO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"projectId": "'$PROJECT'", "appId": "spunto-cloud"}'The answer comes back as soon as the provider accepted, with status starting; it becomes running once the agent inside the sandbox has connected. A project is built once per version and the build is shared by the sandboxes that wait for it, so the next one starts from it.
- Docker inside the box, compose included
/workspace— your repositories, on the branch you asked for, kept when the sandbox is stopped- Secrets of the organization, the project and the member, as environment variables
- An IDE in the browser, on its own URL behind your login
- Persistent terminals — sessions that survive a dropped connection
| Status | Meaning |
|---|---|
building, creating, starting | Being prepared — nothing else can be asked of it yet |
running | The in-sandbox agent is connected: exec, terminals and ports work |
stopped | Its memory dropped, /workspace kept — a start boots it |
paused | Stopped with its memory kept — a start resumes it, processes included (providers that support it) |
error | Something failed; statusReason says what |
POST .../sandboxes/:id/start, /stop, /pause, /rebuild (at the project's current version), and DELETE .../sandboxes/:id to destroy it and its storage.
curl -X POST https://spunto.net/api/orgs/$ORG/sandboxes/$SANDBOX/exec \
-H "Authorization: Bearer $SPUNTO_API_KEY" \
-H "Content-Type: application/json" \
-d '{"command": "npm test"}'Synchronous: the command runs with the sandbox's shell through its agent (up to 30 minutes, timeoutMs) and the answer carries its exit code and output. For an interactive shell, attach to a terminal over a WebSocket — wss://spunto.net/api/sandboxes/:sandboxId/terminal?session=main (see the API reference).
Every port the sandbox listens on is reachable from its own HTTPS URL, behind your login — nothing to declare:
GET /api/orgs/:orgId/sandboxes/:sandboxId/portsreturns the IDE's URL and each port, merged with what the project declares in forwardPorts.
Where the provider supports it, a running sandbox can be snapshotted (POST .../sandboxes/:id/snapshots) and new sandboxes — or tasks — started from that snapshot in seconds, with its processes and work included. A snapshot is personal: it holds its member's secrets.