Sandboxes

A sandbox is a PVC (the durable workspace) plus a Pod (compute attached to it). State is fully derivable from the cluster — there is no separate sandbox-state database.

PVC absent                  → does not exist
PVC present, no Pod         → stopped
PVC + Pod (Pending)         → creating
PVC + Pod (Ready)           → running
PVC or Pod with deletion TS → deleting

Lifecycle

POST   /v1/sandboxes
GET    /v1/sandboxes
GET    /v1/sandboxes/{id}
PATCH  /v1/sandboxes/{id}        # rename
POST   /v1/sandboxes/{id}/start
POST   /v1/sandboxes/{id}/stop
DELETE /v1/sandboxes/{id}

{id} accepts either the server-assigned UUIDv7 (sb-01J6…) or the human slug (fragrant-bird-7x2). Slugs are scoped to the caller — different users can share a slug, the API resolves yours.

Create

POST /v1/sandboxes
Content-Type: application/json
Authorization: Bearer <jwt>

{
  "image":            "ghcr.io/latere-ai/sandbox-base:main",
  "name":             "my-workspace",
  "tier":             "persistent",
  "disk_gb":          5,
  "auto_stop_minutes": 15,
  "auto_delete_hours": 24,
  "env":              { "MY_VAR": "value" },
  "policy":           "default"
}

Field	Default	Notes
`image`	required	OCI ref; digests preferred over tags.
`name`	server-generated	`fragrant-bird-7x2` style slug.
`tier`	`ephemeral`	`ephemeral` (auto-stop + auto-delete) or `persistent`.
`disk_gb`	`5`	Capped per-deployment (default `20`).
`auto_stop_minutes`	`15`	`0` disables idle stop.
`auto_delete_hours`	`24` (ephemeral)	Wall-clock lifetime; ignored for `persistent`.
`policy`	none	Named `NetworkPolicy` for egress control.

The response is the Sandbox shape:

{
  "id":               "sb-01J6...",
  "name":             "fragrant-bird-7x2",
  "state":            "running",
  "tier":             "persistent",
  "disk_gb":          5,
  "auto_stop_minutes": 15,
  "deadline":         "2026-04-25T14:00:00Z",
  "created_at":       "2026-04-24T14:00:00Z"
}

Tiers

Ephemeral. Auto-stops on idle. Auto-deletes after auto_delete_hours wall-clock. Right for fire-and-forget background work; the default for MCP clients.
Persistent. No auto-delete. Idle auto-stop still applies; explicitly disable it with "auto_stop_minutes": 0. Right for ongoing developer workspaces.

Switching tiers after create is not supported. Delete and recreate (or copy your workspace via files/export + files/import).

Quotas

Quotas live on auth.latere.ai. Resolution order at create time is principal → org → platform default. Defaults today:

1 concurrent persistent sandbox.
3 concurrent ephemeral sandboxes.
20 GiB PVC ceiling (per-tier).

Plan upgrades raise these via per-principal rows. A blocked create returns 429 quota_exceeded with a Retry-After header.

Reaping

A controller loop sweeps every 30 s. It performs two transitions:

Idle stop. A running sandbox whose last-activity-at is older than its auto-stop-minutes flips to stopped. The Pod is deleted; the PVC is preserved.
Deadline reap. Anything whose Deadline has passed (with a 60 s grace) is fully deleted.

The reaper emits lifecycle.idle-stop and lifecycle.deadline audit events; a separate billing.sandbox-hour event captures the leg's duration for downstream metering.