# Sandboxes

Short-lived development machines for a project, with a terminal and a team-only preview address. Pro plan.

Source: https://docs.orbits.africa/api/sandboxes

Sandboxes need the Pro plan: on Free, creating or starting one answers 402. The guide is [Sandboxes](https://docs.orbits.africa/features/sandboxes). The terminal itself is a WebSocket, opened with a 60-second ticket from the terminal-ticket call, so it is not listed here as a JSON endpoint.

Endpoints:

- `GET /v1/teams/{team}/projects/{project}/sandboxes`: A project's sandboxes
- `POST /v1/teams/{team}/projects/{project}/sandboxes`: Start a sandbox
- `GET /v1/teams/{team}/projects/{project}/sandboxes/{sandbox}`: A sandbox, its usage and open ports
- `DELETE /v1/teams/{team}/projects/{project}/sandboxes/{sandbox}`: Delete a sandbox
- `POST /v1/teams/{team}/projects/{project}/sandboxes/{sandbox}/stop`: Suspend a sandbox
- `POST /v1/teams/{team}/projects/{project}/sandboxes/{sandbox}/start`: Resume a sandbox
- `POST /v1/teams/{team}/projects/{project}/sandboxes/{sandbox}/terminal-ticket`: A ticket to open the sandbox's terminal

## The sandbox object



- `name` (string, required)
- `runtime` (string, required): One of `node22`, `python312`, `go123`.
- `size` (string, required): small = 0.5 vCPU, 512 MB, 2 GB disk; large = 1 vCPU, 2 GB, 4 GB disk. Several pack onto one node. One of `small`, `large`.
- `source` (string or null, required): What was cloned (e.g. "storefront · main"); null for an empty machine.
- `state` (string, required): `stopped` is suspended: the disk is kept and `start` resumes it. One of `starting`, `running`, `stopped`.
- `started_at` (string, required)
- `stopped_at` (string or null, required)
- `started_by` (FlagPerson, required)
  - `id` (string, required)
  - `name` (string, required)
  - `email` (string, required)
  - `avatar_url` (string or null, required)
- `stop_after` (integer, required): Idle minutes before it suspends itself. One of `10`, `30`, `60`, `120`.
- `url` (string, required): The sandbox's preview URL (port 3000), reachable by team members only.
- `terminal` (array of SandboxTerminalLine, required): The boot and run output so far; live output streams over the terminal WebSocket.
  - `kind` (string, required): One of `cmd`, `out`, `ok`, `err`.
  - `text` (string, required)
- `usage` (SandboxUsage, required)
  - `cpu` (integer, required): Percent of the size's vCPU in use.
  - `memory_gb` (number, required)
  - `disk_gb` (number, required)
  - `idle_minutes` (integer, required): Minutes since the last activity; drives the idle suspend.
## A project's sandboxes

```http
GET /v1/teams/{team}/projects/{project}/sandboxes
```

The Sandboxes page: every sandbox, the live ones first and then by most recently started. `running` counts the live ones (starting or running) and `limit` is the most a team may run at once, for "2 of 3 running" and to disable Create at the cap. `as_of` is the server's clock, for the page's relative times. The page polls this while any sandbox is `starting`.

**Permissions:** Any team member. A non-member gets 404.

Token: any API token (`read` or `full`).

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.

Example:

```sh
curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/sandboxes" \
  -H "Authorization: Bearer $ORBITS_TOKEN"
```

Response `200`:

```json
{
  "items": [
    {
      "name": "seed-test-data",
      "runtime": "node22",
      "size": "small",
      "source": null,
      "state": "starting",
      "started_at": "2026-11-10T09:30:00Z",
      "stopped_at": "2026-11-10T09:30:00Z",
      "started_by": {
        "id": "id",
        "name": "my-app",
        "email": "ada@example.com",
        "avatar_url": "https://my-app.theorbits.app"
      },
      "stop_after": 10,
      "url": "https://my-app.theorbits.app",
      "terminal": [
        {
          "kind": "cmd",
          "text": "text"
        }
      ],
      "usage": {
        "cpu": 1,
        "memory_gb": 1,
        "disk_gb": 1,
        "idle_minutes": 1
      }
    }
  ],
  "running": 1,
  "limit": 1,
  "as_of": "2026-11-10T09:30:00Z"
}
```

Errors:

- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
## Start a sandbox

```http
POST /v1/teams/{team}/projects/{project}/sandboxes
```

Provisions a machine and boots it: `state` is `starting`, then `running` once it is up (poll `GET .../sandboxes`). `clone` checks out the project's repository at `main`; `env` copies the Preview environment variables in. `size` caps CPU, memory and disk; `stop_after` is the idle minutes before it suspends itself. Names are lowercase letters, digits and single dashes, unique among the project's live sandboxes.

A team runs at most `SandboxPage.limit` sandboxes at once; past that this returns 409 and the page offers to stop one first.

**Runtime (v1):** a sandbox is a Docker container on the build host, capped by cgroups, with the terminal backed by `docker exec`. Stronger isolation (Firecracker microVMs) is a later swap that does not change this contract.

**Permissions:** Owners, admins and members. Viewers get 403.

Token: a `full` API token. Send an `Idempotency-Key` header.

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.

Body:

- `name` (string, required): At most 40 characters.
- `runtime` (string, required): One of `node22`, `python312`, `go123`.
- `size` (string, required): small = 0.5 vCPU, 512 MB, 2 GB disk; large = 1 vCPU, 2 GB, 4 GB disk. Several pack onto one node. One of `small`, `large`.
- `clone` (boolean): Check out the project's repository at main. Defaults to `false`.
- `env` (boolean): Copy the Preview environment variables in. Defaults to `false`.
- `stop_after` (integer): Idle minutes before it suspends itself. One of `10`, `30`, `60`, `120`. Defaults to `30`.

Example:

```sh
curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/sandboxes" \
  -H "Authorization: Bearer $ORBITS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "seed-test-data",
    "runtime": "node22",
    "size": "small"
  }'
```

Response `201`:

```json
{
  "name": "seed-test-data",
  "runtime": "node22",
  "size": "small",
  "source": null,
  "state": "starting",
  "started_at": "2026-11-10T09:30:00Z",
  "stopped_at": "2026-11-10T09:30:00Z",
  "started_by": {
    "id": "id",
    "name": "my-app",
    "email": "ada@example.com",
    "avatar_url": "https://my-app.theorbits.app"
  },
  "stop_after": 10,
  "url": "https://my-app.theorbits.app",
  "terminal": [
    {
      "kind": "cmd",
      "text": "text"
    }
  ],
  "usage": {
    "cpu": 1,
    "memory_gb": 1,
    "disk_gb": 1,
    "idle_minutes": 1
  }
}
```

Errors:

- `402`: The team's plan doesn't include this (see `GET /v1/plans`). `code` is `plan_required`, `required_plan` is `pro` and `feature` names what is missing; show the upgrade dialog.
- `403`: Authenticated but not allowed in this team.
- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
- `409`: The request conflicts with current state.
- `422`: Validation failed, or the Idempotency-Key was reused with a different body.
## A sandbox, its usage and open ports

```http
GET /v1/teams/{team}/projects/{project}/sandboxes/{sandbox}
```

The sandbox's page: its `usage` against the size's ceiling, the `terminal` output so far, and the `ports` it listens on (port 3000, team-only, in v1). Use `{sandbox}` from `GET .../sandboxes`.

**Permissions:** Any team member. A non-member gets 404.

Token: any API token (`read` or `full`).

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.
- `sandbox`: The sandbox's name.

Example:

```sh
curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/sandboxes/sbx_01jc8x6e4mq2v7r9y3t5b0zp8w" \
  -H "Authorization: Bearer $ORBITS_TOKEN"
```

Response `200`:

```json
{
  "name": "seed-test-data",
  "runtime": "node22",
  "size": "small",
  "source": null,
  "state": "starting",
  "started_at": "2026-11-10T09:30:00Z",
  "stopped_at": "2026-11-10T09:30:00Z",
  "started_by": {
    "id": "id",
    "name": "my-app",
    "email": "ada@example.com",
    "avatar_url": "https://my-app.theorbits.app"
  },
  "stop_after": 10,
  "url": "https://my-app.theorbits.app",
  "terminal": [
    {
      "kind": "cmd",
      "text": "text"
    }
  ],
  "usage": {
    "cpu": 1,
    "memory_gb": 1,
    "disk_gb": 1,
    "idle_minutes": 1
  },
  "ports": [
    {
      "port": 3000,
      "url": "https://my-app.theorbits.app",
      "access": "team"
    }
  ]
}
```

Errors:

- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
## Delete a sandbox

```http
DELETE /v1/teams/{team}/projects/{project}/sandboxes/{sandbox}
```

Terminates the machine and frees its disk. Irreversible; unlike stop, nothing is kept.

**Permissions:** Owners, admins and members. Viewers get 403.

Token: a `full` API token.

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.
- `sandbox`: The sandbox's name.

Example:

```sh
curl -X DELETE "https://api.theorbits.app/v1/teams/my-team/projects/my-app/sandboxes/sbx_01jc8x6e4mq2v7r9y3t5b0zp8w" \
  -H "Authorization: Bearer $ORBITS_TOKEN"
```

Response `204`: Deleted.

Errors:

- `403`: Authenticated but not allowed in this team.
- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
## Suspend a sandbox

```http
POST /v1/teams/{team}/projects/{project}/sandboxes/{sandbox}/stop
```

Suspends the sandbox: CPU and memory are released, the disk is kept, and `start` resumes it with the work intact. The idle auto-stop does the same, so a timeout never loses work. `state` becomes `stopped`. Already stopped is a no-op 200.

**Permissions:** Owners, admins and members. Viewers get 403.

Token: a `full` API token. Send an `Idempotency-Key` header.

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.
- `sandbox`: The sandbox's name.

Example:

```sh
curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/sandboxes/sbx_01jc8x6e4mq2v7r9y3t5b0zp8w/stop" \
  -H "Authorization: Bearer $ORBITS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
```

Response `200`:

```json
{
  "name": "seed-test-data",
  "runtime": "node22",
  "size": "small",
  "source": null,
  "state": "starting",
  "started_at": "2026-11-10T09:30:00Z",
  "stopped_at": "2026-11-10T09:30:00Z",
  "started_by": {
    "id": "id",
    "name": "my-app",
    "email": "ada@example.com",
    "avatar_url": "https://my-app.theorbits.app"
  },
  "stop_after": 10,
  "url": "https://my-app.theorbits.app",
  "terminal": [
    {
      "kind": "cmd",
      "text": "text"
    }
  ],
  "usage": {
    "cpu": 1,
    "memory_gb": 1,
    "disk_gb": 1,
    "idle_minutes": 1
  }
}
```

Errors:

- `403`: Authenticated but not allowed in this team.
- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
## Resume a sandbox

```http
POST /v1/teams/{team}/projects/{project}/sandboxes/{sandbox}/start
```

Resumes a stopped sandbox from its kept disk: `state` is `starting`, then `running` (poll `GET .../sandboxes`). Counts against the team's live limit, so this returns 409 when the team is already at `SandboxPage.limit`. Already running is a no-op 200.

**Permissions:** Owners, admins and members. Viewers get 403.

Token: a `full` API token. Send an `Idempotency-Key` header.

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.
- `sandbox`: The sandbox's name.

Example:

```sh
curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/sandboxes/sbx_01jc8x6e4mq2v7r9y3t5b0zp8w/start" \
  -H "Authorization: Bearer $ORBITS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
```

Response `200`:

```json
{
  "name": "seed-test-data",
  "runtime": "node22",
  "size": "small",
  "source": null,
  "state": "starting",
  "started_at": "2026-11-10T09:30:00Z",
  "stopped_at": "2026-11-10T09:30:00Z",
  "started_by": {
    "id": "id",
    "name": "my-app",
    "email": "ada@example.com",
    "avatar_url": "https://my-app.theorbits.app"
  },
  "stop_after": 10,
  "url": "https://my-app.theorbits.app",
  "terminal": [
    {
      "kind": "cmd",
      "text": "text"
    }
  ],
  "usage": {
    "cpu": 1,
    "memory_gb": 1,
    "disk_gb": 1,
    "idle_minutes": 1
  }
}
```

Errors:

- `402`: The team's plan doesn't include this (see `GET /v1/plans`). `code` is `plan_required`, `required_plan` is `pro` and `feature` names what is missing; show the upgrade dialog.
- `403`: Authenticated but not allowed in this team.
- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
- `409`: The request conflicts with current state.
## A ticket to open the sandbox's terminal

```http
POST /v1/teams/{team}/projects/{project}/sandboxes/{sandbox}/terminal-ticket
```

A WebSocket opened by a browser can't carry the session or a bearer, so the terminal (`GET .../sandboxes/{sandbox}/terminal`) takes this ticket in its `ticket` query parameter instead. The ticket (`sbt_…`) admits the caller to this one sandbox's terminal for 60 seconds: get one right before opening the socket. It is signed, not stored, so it can't be revoked before it expires. Takes no body. The answer is never cached and the call ignores `Idempotency-Key`, so every call mints a new ticket.

No plan check of its own: the sandbox must be `running` (else 409), and only Pro can start one.

**Permissions:** Any team member, viewers included. A session or a `full` API token may call it (a token limited to one project only for that project); a `read` token gets 403, because this is a POST. A non-member gets 404.

Token: a `full` API token.

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.
- `sandbox`: The sandbox's name.

Example:

```sh
curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/sandboxes/sbx_01jc8x6e4mq2v7r9y3t5b0zp8w/terminal-ticket" \
  -H "Authorization: Bearer $ORBITS_TOKEN"
```

Response `200`:

```json
{
  "ticket": "sbt_eyJzIjoic2J4XzEifQ.c2lnbmF0dXJl"
}
```

Errors:

- `401`: Missing or invalid credentials.
- `403`: Authenticated but not allowed in this team.
- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
- `409`: The request conflicts with current state.
