> ## Documentation Index > Fetch the complete documentation index at: https://docs.runtools.ai/llms.txt > Use this file to discover all available pages before exploring further. # List sandboxes > DB-paginated. Defaults to active statuses (excludes destroyed/orphaned). Pass `?all=true` to view all members' sandboxes (admin only). Use `?cursor=` for pagination. ## OpenAPI ````yaml /api-reference/openapi.yaml get /v1/sandboxes openapi: 3.1.0 info: title: RunTools API version: 1.0.0 description: | The RunTools platform API for cloud sandboxes, agents, workspaces, tools, threads, billing, and credentials. This document covers the customer-facing surface across six services: - api.runtools.ai — orchestrator (control plane) - auth.runtools.ai — auth service (API keys, SSH keys, OAuth, secrets) - tools.runtools.ai — tool marketplace + execution - billing.runtools.ai — credits, top-up, auto-top-up - storage.runtools.ai — workspace file APIs Internal-only routes (`/internal/*`, admin routes, webhooks), as well as deferred/gated surfaces (workflows, snapshots, rollback, code-exec), are deliberately excluded. ## Authentication Two auth schemes are supported on the public surface: - **WorkOS session token** — Bearer token from interactive login, used by dashboard, mobile, CLI `login`, Mac app, and any browser-driven flow. - **API key** — `rt_live_*` or `rt_test_*` keys created via `POST /v1/api-keys`. Scope-checked at each handler. Either may be passed in `Authorization: Bearer ` or, for API keys, in `X-API-Key`. ## Response envelope Most successful JSON responses wrap data in `{ "data": ... }`. Paginated responses additionally carry `hasMore` and `nextCursor`. Error responses use `{ "error": { "code": "...", "message": "..." } }`. ## Versioning header Every public response includes an `X-API-Version: v1` header. This is the contract for clients that want to assert the surface version they were written against. A future `/v2/*` rollout will set `X-API-Version: v2` on matching responses while `/v1/*` continues to return `v1`. contact: name: RunTools url: https://runtools.ai license: name: Proprietary servers: - url: https://api.runtools.ai description: Orchestrator (control plane) - url: https://auth.runtools.ai description: Auth service - url: https://tools.runtools.ai description: Tools service - url: https://billing.runtools.ai description: Billing service - url: https://storage.runtools.ai description: Storage service (workspace files) security: - bearer: [] - apiKey: [] tags: - name: Health description: Liveness and readiness probes. - name: Profile description: Current user profile. - name: Organizations description: Organization CRUD, members, tool-install policy. - name: Projects description: Org-scoped projects and resource pins. - name: Sandboxes description: Firecracker microVM lifecycle, exec, URLs, SSH/VNC. - name: Agents description: Agent definitions and CRUD. - name: Agent marketplace description: Public marketplace listing and install. - name: Agent runs description: Dispatch and observe agent runs. - name: Channels description: External messaging channels and channel privacy. - name: Threads description: Public thread storage (JSONL-backed). - name: Workspaces description: Workspace metadata and usage (control plane). - name: Workspace files description: NFS-backed workspace file APIs (storage service). - name: Installable agents description: Hermes catalog and install lifecycle. - name: Attachments description: Agent message attachments (uploaded files). - name: Tools (marketplace) description: Public tool marketplace and schemas. - name: Tools (installed) description: Org tool installs and credentials. - name: Tools (custom) description: Org-private custom tool CRUD and publishing. - name: Tool execution description: Server-side tool invocation. - name: Secrets description: Encrypted secrets (org-scoped). - name: SSH keys description: SSH key CRUD for sandbox access. - name: API keys description: API key issuance and revocation. - name: OAuth connections description: User OAuth connections to providers. - name: BYOA configs description: Bring-your-own-app OAuth client configuration. - name: LangTerm description: LangTerm SSH connection profiles. - name: Models description: Available model registry. - name: Model proxy description: Platform-tier model invocation. - name: Calendar description: Google Calendar connections. - name: RunMesh description: RunMesh device pairing and management. - name: Terminal description: Browser terminal session minting. - name: Activity description: Customer-facing activity event log. - name: Billing description: Credits, top-up, auto-top-up, usage pricing. - name: Auth description: Token verification and logout URLs. paths: /v1/sandboxes: get: tags: - Sandboxes summary: List sandboxes description: | DB-paginated. Defaults to active statuses (excludes destroyed/orphaned). Pass `?all=true` to view all members' sandboxes (admin only). Use `?cursor=` for pagination. operationId: listSandboxes parameters: - name: status in: query schema: $ref: '#/components/schemas/SandboxStatus' - name: tag in: query schema: type: string - name: template in: query schema: type: string - name: exclude_template in: query schema: type: string - $ref: '#/components/parameters/LimitQuery' - $ref: '#/components/parameters/CursorQuery' - $ref: '#/components/parameters/AllOrgQuery' responses: '200': description: Page of sandboxes. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/Sandbox' hasMore: type: boolean nextCursor: type: string nullable: true '403': description: Admin required for `?all=true`. servers: - url: https://api.runtools.ai components: schemas: SandboxStatus: type: string enum: - pending - creating - running - pausing - paused - resuming - destroying - destroyed - stopped - failed - error - orphaned - suspected_missing Sandbox: type: object properties: id: type: string example: sandbox-abc123def456 name: type: string nullable: true status: $ref: '#/components/schemas/SandboxStatus' tags: type: array items: type: string template: type: string nullable: true description: Template slug (e.g. `base-ubuntu`, `desktop-ubuntu`). ownerUserId: type: string format: uuid nullable: true ownerDisplayName: type: string nullable: true ownerEmail: type: string nullable: true projectId: type: string format: uuid nullable: true mounts: type: array items: $ref: '#/components/schemas/WorkspaceMount' hasWritableWorkspaceMount: type: boolean sshReady: type: boolean vncReady: type: boolean ip: type: string nullable: true publicIp: type: string nullable: true sshAccessConfigured: type: boolean sshAuthMethod: type: string enum: - key - password - none vncUrl: type: string nullable: true description: Capability-protected desktop URL (desktop template only). resources: $ref: '#/components/schemas/SandboxResources' createdAt: type: string format: date-time WorkspaceMount: allOf: - $ref: '#/components/schemas/WorkspaceMountInput' - type: object properties: readOnly: type: boolean SandboxResources: type: object properties: vcpus: type: integer minimum: 1 example: 2 memory: type: string example: 4GB disk: type: string example: 10GB WorkspaceMountInput: type: object properties: workspaceId: type: string format: uuid path: type: string description: Guest mount path; must be `/workspace` or a safe subpath. example: /workspace required: - workspaceId - path parameters: LimitQuery: name: limit in: query description: Maximum number of rows to return. required: false schema: type: integer minimum: 1 maximum: 500 CursorQuery: name: cursor in: query description: Opaque pagination cursor returned by a prior page. required: false schema: type: string AllOrgQuery: name: all in: query description: Include resources for all members of the org (admin only). required: false schema: type: boolean securitySchemes: bearer: type: http scheme: bearer description: | WorkOS session token or RunTools API key (`rt_live_*` / `rt_test_*`). Used in `Authorization: Bearer ` header. apiKey: type: apiKey in: header name: X-API-Key description: Alternative location for a RunTools API key (`rt_live_*` / `rt_test_*`). ````