llms.txt
Compare with other sites' llms.txt files →# Spunto
> A platform to run isolated, devcontainer-compatible sandboxes — for yourself or for AI agents — on machines you control (BYOC) or on Spunto Cloud, and to delegate whole tasks to a coding agent inside them.
Spunto is your own GitHub Codespaces and agent sandbox combined. It is organized around a **project** (a devcontainer-compatible config: base image, devcontainer features, IDE extensions, repositories, secrets, lifecycle commands — versioned on every change) and what you run from it:
- **Sandboxes** — an isolated Linux machine per environment, built from the project and run by a provider app: Spunto Cloud, your own machines connected to the BYOC app (one install line per machine, outbound-only WebSocket, no inbound port), or a Google Cloud VM per sandbox. Each one has Docker inside, a persistent disk, an IDE in the browser, persistent terminals, and every port on its own HTTPS URL. Driven the same way by humans (dashboard) or code (REST API with scoped API keys).
- **Tasks** — a prompt handed to Claude Code (or any command-line agent): it gets a sandbox of its own, a branch and a session you watch live; nothing merges until a human presses Accept.
Multi-tenant with organizations and role-based access (owner / admin / member).
## Docs
- [Introduction](https://spunto.net/documentation): What Spunto is.
- [Quick Start](https://spunto.net/documentation/getting-started): Sign in, create a project, start your first sandbox or task.
## Build
- [Tasks](https://spunto.net/documentation/build/tasks): Delegate work to an agent — a sandbox, a branch, a live session, Accept or Drop.
- [Sandboxes](https://spunto.net/documentation/build/sandboxes): Isolated machines built from a project, on the provider of your choice.
- [Skills](https://spunto.net/documentation/build/skills): Skill repositories offered to every agent of the organization.
- [Projects](https://spunto.net/documentation/build/projects): Devcontainer-compatible templates — image, features, IDE extensions, repos, lifecycle commands; versioned on every change.
## Reference
- [API Reference](https://spunto.net/documentation/reference/api): The full REST API; Bearer token auth (session or API key) on all endpoints except public auth routes. OpenAPI at https://spunto.net/openapi.json.
- [API Keys](https://spunto.net/documentation/reference/api-keys): Generate scoped Bearer tokens for headless access — scripts, CI, and AI agents.
- [MCP Server](https://spunto.net/documentation/reference/mcp): Connect an MCP client to your organization.
## Guides
- [AI Agents](https://spunto.net/documentation/guides/ai-agents): Use sandboxes as isolated machines for AI coding agents via a clean REST API, or hand them tasks.
## Sandbox API (key capability for AI agents)
- Create: `POST /api/orgs/{orgId}/sandboxes` with `{"projectId": "...", "appId": "<provider>"}` (providers: `GET /api/orgs/{orgId}/sandboxes/providers`).
- Run a command: `POST /api/orgs/{orgId}/sandboxes/{sandboxId}/exec` with `{"command": "npm test"}` — synchronous, through the agent inside the sandbox (up to 30 minutes).
- Ports: `GET /api/orgs/{orgId}/sandboxes/{sandboxId}/ports` — every listening port and the IDE on their own HTTPS URLs.
- Auth: `Authorization: Bearer spk_...` (scopes `workers:read` / `workers:write` / `workers:exec`, which cover sandboxes).
## Terminal WebSocket (interactive shell)
The sandbox terminal (`GET /api/sandboxes/{sandboxId}/terminal`) is a **WebSocket-based PTY** that accepts `Authorization: Bearer <api key>` (scope `workers:exec` or `*`) — no browser session required.
**Connect:**
```
wss://spunto.net/api/sandboxes/{sandboxId}/terminal?mode=terminal&cols=220&rows=50&session=<name>
```
**Protocol (JSON frames):**
- Server → client: `{"type":"ready"}` — PTY attached, send commands now
- Client → server: `{"type":"input","data":"<base64>"}` — raw keystrokes; append `\r` to submit a line
- Server → client: `{"type":"output","data":"<base64>"}` — raw PTY output (ANSI sequences included)
- Client → server: `{"type":"resize","cols":N,"rows":M}` — resize PTY
**Session persistence:** use the same `?session=<name>` on reconnect to reattach — the shell and any running process survive disconnects. `mode=logs` follows the sandbox's logs read-only.
**Node.js minimal example:**
```typescript
import WebSocket from "ws"
import { Buffer } from "node:buffer"
const ws = new WebSocket(
`wss://spunto.net/api/sandboxes/${sandboxId}/terminal?mode=terminal&cols=220&rows=50`,
{ headers: { Authorization: `Bearer ${apiKey}` } }
)
ws.once("message", raw => {
if (JSON.parse(raw.toString()).type !== "ready") return
ws.send(JSON.stringify({ type: "input", data: Buffer.from("ls /workspace\r").toString("base64") }))
})
ws.on("message", raw => {
const m = JSON.parse(raw.toString())
if (m.type === "output") process.stdout.write(Buffer.from(m.data, "base64"))
})
```