OrbitsDocs
esc
    Open Orbits
    API reference · In your appSandboxes

    Sandboxes

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

    Sandboxes need the Pro plan: on Free, creating or starting one answers 402. The guide is 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.

    The sandbox object

    Fields

    • namestringrequired
    • runtimestringrequired

      One of node22, python312, go123.

    • sizestringrequired

      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.

    • sourcestring or nullrequired

      What was cloned (e.g. "storefront · main"); null for an empty machine.

    • statestringrequired

      stopped is suspended: the disk is kept and start resumes it.

      One of starting, running, stopped.

    • started_atstringrequired
    • stopped_atstring or nullrequired
    • started_byFlagPersonrequired
      Show 4 child fields
      • idstringrequired
      • namestringrequired
      • emailstringrequired
      • avatar_urlstring or nullrequired
    • stop_afterintegerrequired

      Idle minutes before it suspends itself.

      One of 10, 30, 60, 120.

    • urlstringrequired

      The sandbox's preview URL (port 3000), reachable by team members only.

    • terminalarray of SandboxTerminalLinerequired

      The boot and run output so far; live output streams over the terminal WebSocket.

      Show 2 child fields
      • kindstringrequired

        One of cmd, out, ok, err.

      • textstringrequired
    • usageSandboxUsagerequired
      Show 4 child fields
      • cpuintegerrequired

        Percent of the size's vCPU in use.

      • memory_gbnumberrequired
      • disk_gbnumberrequired
      • idle_minutesintegerrequired

        Minutes since the last activity; drives the idle suspend.

    A project's 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.

    GET/v1/teams/{team}/projects/{project}/sandboxes
    Read or full tokenReturns200OK

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project slug or prj_ id.

    Response 200

    The sandboxes.
    • itemsarray of Sandboxrequired
      Show 12 child fields
      • namestringrequired
      • runtimestringrequired

        One of node22, python312, go123.

      • sizestringrequired

        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.

      • sourcestring or nullrequired

        What was cloned (e.g. "storefront · main"); null for an empty machine.

      • statestringrequired

        stopped is suspended: the disk is kept and start resumes it.

        One of starting, running, stopped.

      • started_atstringrequired
      • stopped_atstring or nullrequired
      • started_byFlagPersonrequired
        Show 4 child fields
        • idstringrequired
        • namestringrequired
        • emailstringrequired
        • avatar_urlstring or nullrequired
      • stop_afterintegerrequired

        Idle minutes before it suspends itself.

        One of 10, 30, 60, 120.

      • urlstringrequired

        The sandbox's preview URL (port 3000), reachable by team members only.

      • terminalarray of SandboxTerminalLinerequired

        The boot and run output so far; live output streams over the terminal WebSocket.

        Show 2 child fields
        • kindstringrequired

          One of cmd, out, ok, err.

        • textstringrequired
      • usageSandboxUsagerequired
        Show 4 child fields
        • cpuintegerrequired

          Percent of the size's vCPU in use.

        • memory_gbnumberrequired
        • disk_gbnumberrequired
        • idle_minutesintegerrequired

          Minutes since the last activity; drives the idle suspend.

    • runningintegerrequired

      Live sandboxes (starting or running).

    • limitintegerrequired

      The most a team may run at once.

    • as_ofstringrequired

      The server's clock, for the page's relative times.

    Errors

    • 404Not found, or not visible to the caller (the two are indistinguishable on purpose).

    Every code is explained in Errors.

    curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/sandboxes" \
      -H "Authorization: Bearer $ORBITS_TOKEN"
    Response 200
    {
      "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"
    }

    Start a sandbox

    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.

    POST/v1/teams/{team}/projects/{project}/sandboxes
    Full tokenNeeds Idempotency-KeyReturns201Created

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    • Idempotency-Keystringrequired

      A new value, such as a UUID, for each change. Resend with the same value and body to retry safely.

      From 8 to 128 characters.

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project slug or prj_ id.

    Body

    application/json
    • namestringrequired

      At most 40 characters.

    • runtimestringrequired

      One of node22, python312, go123.

    • sizestringrequired

      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.

    • cloneboolean

      Check out the project's repository at main.

      Defaults to false.

    • envboolean

      Copy the Preview environment variables in.

      Defaults to false.

    • stop_afterinteger

      Idle minutes before it suspends itself.

      One of 10, 30, 60, 120. Defaults to 30.

    Response 201

    The new sandbox, starting.
    • namestringrequired
    • runtimestringrequired

      One of node22, python312, go123.

    • sizestringrequired

      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.

    • sourcestring or nullrequired

      What was cloned (e.g. "storefront · main"); null for an empty machine.

    • statestringrequired

      stopped is suspended: the disk is kept and start resumes it.

      One of starting, running, stopped.

    • started_atstringrequired
    • stopped_atstring or nullrequired
    • started_byFlagPersonrequired
      Show 4 child fields
      • idstringrequired
      • namestringrequired
      • emailstringrequired
      • avatar_urlstring or nullrequired
    • stop_afterintegerrequired

      Idle minutes before it suspends itself.

      One of 10, 30, 60, 120.

    • urlstringrequired

      The sandbox's preview URL (port 3000), reachable by team members only.

    • terminalarray of SandboxTerminalLinerequired

      The boot and run output so far; live output streams over the terminal WebSocket.

      Show 2 child fields
      • kindstringrequired

        One of cmd, out, ok, err.

      • textstringrequired
    • usageSandboxUsagerequired
      Show 4 child fields
      • cpuintegerrequired

        Percent of the size's vCPU in use.

      • memory_gbnumberrequired
      • disk_gbnumberrequired
      • idle_minutesintegerrequired

        Minutes since the last activity; drives the idle suspend.

    Errors

    • 402The 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.
    • 403Authenticated but not allowed in this team.
    • 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
    • 409The request conflicts with current state.
    • 422Validation failed, or the Idempotency-Key was reused with a different body.

    Every code is explained in Errors.

    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
    {
      "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
      }
    }

    A sandbox, its usage and open ports

    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.

    GET/v1/teams/{team}/projects/{project}/sandboxes/{sandbox}
    Read or full tokenReturns200OK

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project slug or prj_ id.

    • sandboxstringrequired

      The sandbox's name.

    Response 200

    The sandbox.
    • namestringrequired
    • runtimestringrequired

      One of node22, python312, go123.

    • sizestringrequired

      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.

    • sourcestring or nullrequired

      What was cloned (e.g. "storefront · main"); null for an empty machine.

    • statestringrequired

      stopped is suspended: the disk is kept and start resumes it.

      One of starting, running, stopped.

    • started_atstringrequired
    • stopped_atstring or nullrequired
    • started_byFlagPersonrequired
      Show 4 child fields
      • idstringrequired
      • namestringrequired
      • emailstringrequired
      • avatar_urlstring or nullrequired
    • stop_afterintegerrequired

      Idle minutes before it suspends itself.

      One of 10, 30, 60, 120.

    • urlstringrequired

      The sandbox's preview URL (port 3000), reachable by team members only.

    • terminalarray of SandboxTerminalLinerequired

      The boot and run output so far; live output streams over the terminal WebSocket.

      Show 2 child fields
      • kindstringrequired

        One of cmd, out, ok, err.

      • textstringrequired
    • usageSandboxUsagerequired
      Show 4 child fields
      • cpuintegerrequired

        Percent of the size's vCPU in use.

      • memory_gbnumberrequired
      • disk_gbnumberrequired
      • idle_minutesintegerrequired

        Minutes since the last activity; drives the idle suspend.

    • portsarray of SandboxPortrequired
      Show 3 child fields
      • portintegerrequired
      • urlstringrequired
      • accessstringrequired

        v1 exposes ports to team members only.

        One of team, public.

    Errors

    • 404Not found, or not visible to the caller (the two are indistinguishable on purpose).

    Every code is explained in Errors.

    curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/sandboxes/sbx_01jc8x6e4mq2v7r9y3t5b0zp8w" \
      -H "Authorization: Bearer $ORBITS_TOKEN"
    Response 200
    {
      "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"
        }
      ]
    }

    Delete a sandbox

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

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

    DELETE/v1/teams/{team}/projects/{project}/sandboxes/{sandbox}
    Full tokenReturns204No Content

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project slug or prj_ id.

    • sandboxstringrequired

      The sandbox's name.

    Response 204

    Deleted. No body.

    Errors

    • 403Authenticated but not allowed in this team.
    • 404Not found, or not visible to the caller (the two are indistinguishable on purpose).

    Every code is explained in Errors.

    curl -X DELETE "https://api.theorbits.app/v1/teams/my-team/projects/my-app/sandboxes/sbx_01jc8x6e4mq2v7r9y3t5b0zp8w" \
      -H "Authorization: Bearer $ORBITS_TOKEN"
    HTTP/1.1 204 No Content

    Suspend a sandbox

    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.

    POST/v1/teams/{team}/projects/{project}/sandboxes/{sandbox}/stop
    Full tokenNeeds Idempotency-KeyReturns200OK

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    • Idempotency-Keystringrequired

      A new value, such as a UUID, for each change. Resend with the same value and body to retry safely.

      From 8 to 128 characters.

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project slug or prj_ id.

    • sandboxstringrequired

      The sandbox's name.

    Response 200

    The suspended sandbox.
    • namestringrequired
    • runtimestringrequired

      One of node22, python312, go123.

    • sizestringrequired

      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.

    • sourcestring or nullrequired

      What was cloned (e.g. "storefront · main"); null for an empty machine.

    • statestringrequired

      stopped is suspended: the disk is kept and start resumes it.

      One of starting, running, stopped.

    • started_atstringrequired
    • stopped_atstring or nullrequired
    • started_byFlagPersonrequired
      Show 4 child fields
      • idstringrequired
      • namestringrequired
      • emailstringrequired
      • avatar_urlstring or nullrequired
    • stop_afterintegerrequired

      Idle minutes before it suspends itself.

      One of 10, 30, 60, 120.

    • urlstringrequired

      The sandbox's preview URL (port 3000), reachable by team members only.

    • terminalarray of SandboxTerminalLinerequired

      The boot and run output so far; live output streams over the terminal WebSocket.

      Show 2 child fields
      • kindstringrequired

        One of cmd, out, ok, err.

      • textstringrequired
    • usageSandboxUsagerequired
      Show 4 child fields
      • cpuintegerrequired

        Percent of the size's vCPU in use.

      • memory_gbnumberrequired
      • disk_gbnumberrequired
      • idle_minutesintegerrequired

        Minutes since the last activity; drives the idle suspend.

    Errors

    • 403Authenticated but not allowed in this team.
    • 404Not found, or not visible to the caller (the two are indistinguishable on purpose).

    Every code is explained in Errors.

    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
    {
      "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
      }
    }

    Resume a sandbox

    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.

    POST/v1/teams/{team}/projects/{project}/sandboxes/{sandbox}/start
    Full tokenNeeds Idempotency-KeyReturns200OK

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    • Idempotency-Keystringrequired

      A new value, such as a UUID, for each change. Resend with the same value and body to retry safely.

      From 8 to 128 characters.

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project slug or prj_ id.

    • sandboxstringrequired

      The sandbox's name.

    Response 200

    The sandbox, starting.
    • namestringrequired
    • runtimestringrequired

      One of node22, python312, go123.

    • sizestringrequired

      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.

    • sourcestring or nullrequired

      What was cloned (e.g. "storefront · main"); null for an empty machine.

    • statestringrequired

      stopped is suspended: the disk is kept and start resumes it.

      One of starting, running, stopped.

    • started_atstringrequired
    • stopped_atstring or nullrequired
    • started_byFlagPersonrequired
      Show 4 child fields
      • idstringrequired
      • namestringrequired
      • emailstringrequired
      • avatar_urlstring or nullrequired
    • stop_afterintegerrequired

      Idle minutes before it suspends itself.

      One of 10, 30, 60, 120.

    • urlstringrequired

      The sandbox's preview URL (port 3000), reachable by team members only.

    • terminalarray of SandboxTerminalLinerequired

      The boot and run output so far; live output streams over the terminal WebSocket.

      Show 2 child fields
      • kindstringrequired

        One of cmd, out, ok, err.

      • textstringrequired
    • usageSandboxUsagerequired
      Show 4 child fields
      • cpuintegerrequired

        Percent of the size's vCPU in use.

      • memory_gbnumberrequired
      • disk_gbnumberrequired
      • idle_minutesintegerrequired

        Minutes since the last activity; drives the idle suspend.

    Errors

    • 402The 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.
    • 403Authenticated but not allowed in this team.
    • 404Not found, or not visible to the caller (the two are indistinguishable on purpose).
    • 409The request conflicts with current state.

    Every code is explained in Errors.

    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
    {
      "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
      }
    }

    A ticket to open the sandbox's terminal

    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.

    POST/v1/teams/{team}/projects/{project}/sandboxes/{sandbox}/terminal-ticket
    Full tokenReturns200OK

    Headers

    • Authorizationstringrequired

      Bearer and your API token: Bearer orb_live_….

    Path parameters

    • teamstringrequired

      Team slug or team_ id.

    • projectstringrequired

      Project slug or prj_ id.

    • sandboxstringrequired

      The sandbox's name.

    Response 200

    The ticket.
    • ticketstringrequired

      Admits the caller to this sandbox's terminal for 60 seconds: the ticket query parameter of GET .../sandboxes/{sandbox}/terminal.

    Errors

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

    Every code is explained in Errors.

    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
    {
      "ticket": "sbt_eyJzIjoic2J4XzEifQ.c2lnbmF0dXJl"
    }

    Was this page helpful?

    Updated