> ## Documentation Index > Fetch the complete documentation index at: https://docs.boat.dev/llms.txt > Use this file to discover all available pages before exploring further. # Share sandbox with the organization > Let every member of the organization that pays for this sandbox use it. Your personal logins (GitHub token, Claude and Codex logins, environment secrets, the sandbox's own CLI key) are never pushed to it again and are wiped off its disk at its next start, so a teammate never acts as you. Files you wrote stay. One-way: the sandbox stays like a `noEnv` sandbox from then on. A running sandbox stays `view` for the organization until you stop and resume it (`restartRequired`). Only the person who created the sandbox can share it, and only a sandbox billed to an organization. Sharing an already shared sandbox is a no-op. ## OpenAPI ````yaml openapi/boat-v1.yaml POST /sandboxes/{sandboxId}/share openapi: 3.1.0 info: title: Boat Public API v1 version: 1.0.0 description: > Public JSON API for creating, operating, prompting, observing, and exposing sandboxes from backend services, CI jobs, hosted workers, and Boat automation products. The v1 reference intentionally documents the developer integration surface only. Dashboard billing actions are not part of v1. servers: - url: https://boat.dev/api/v1 security: - BoatBearerAuth: [] tags: - name: Boat description: >- Unified Boat account, setup, lifecycle, prompting, event history, desktop access, and SSH operations. paths: /sandboxes/{sandboxId}/share: post: tags: - Boat summary: Share sandbox with the organization description: > Let every member of the organization that pays for this sandbox use it. Your personal logins (GitHub token, Claude and Codex logins, environment secrets, the sandbox's own CLI key) are never pushed to it again and are wiped off its disk at its next start, so a teammate never acts as you. Files you wrote stay. One-way: the sandbox stays like a `noEnv` sandbox from then on. A running sandbox stays `view` for the organization until you stop and resume it (`restartRequired`). Only the person who created the sandbox can share it, and only a sandbox billed to an organization. Sharing an already shared sandbox is a no-op. operationId: share parameters: - $ref: '#/components/parameters/SandboxId' responses: '200': description: The sandbox is shared. content: application/json: schema: type: object properties: sandbox: $ref: '#/components/schemas/Sandbox' restartRequired: type: boolean description: >- True when the sandbox was running: what runs on it still holds your logins in memory, so it stays `view` for the organization until you stop and resume it. message: type: string '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' components: parameters: SandboxId: name: sandboxId in: path required: true schema: type: string pattern: ^bx_[23456789abcdefghjkmnpqrstuvwxyz]{8}$ description: Public Sandbox id returned by create/list/get sandbox calls. schemas: Sandbox: type: object required: - id - name - state - desktopAvailable - snapshotAvailable properties: id: type: string pattern: ^bx_[23456789abcdefghjkmnpqrstuvwxyz]{8}$ examples: - bx_23456789 name: type: string examples: - Boat 2026-05-31 12:00 state: type: string enum: - init - provisioning - provisioned - cloning - ready - idle - running - archiving - archived - error - cancelled description: >- `cancelled` is terminal: a create or fork that could not get a machine was removed. `GET /sandboxes/{sandboxId}` reports it once, with only `id`, `state` and `error`, then answers 404. error: type: - string - 'null' description: Why the sandbox is stopped, failed or cancelled, or null. health: type: string enum: - ok - degraded description: >- `degraded` when the machine is alive but Boat cannot fully reach it (for example a firewall rule inside the sandbox blocks the tunnel). The sandbox keeps running. healthReason: type: - string - 'null' description: Why the sandbox is degraded, or null. degradedSince: type: - string - 'null' format: date-time description: When the sandbox became degraded, or null. type: type: string enum: - small - default - large description: >- Current machine size: what the sandbox was created with, or the size it was last resumed or forked onto. vcpu: type: integer description: vCPUs guaranteed by this sandbox's type. examples: - 4 memoryGB: type: integer description: RAM in GB guaranteed by this sandbox's type. examples: - 8 billingMultiplier: type: number description: >- Rate at which this sandbox consumes machine time. 0.5 for `small`, 1 for `default`, and 2 for `large`. examples: - 1 machineProvider: type: - string - 'null' enum: - hetzner - baremetal - null description: >- Machine provider of the machine the sandbox is on, or null when it has no machine. url: type: - string - 'null' format: uri description: Machine URL when assigned. ip: type: - string - 'null' description: Machine IPv6 or IPv4 address when assigned. sshEndpoint: type: - string - 'null' description: >- Public IPv4 `host:port` that forwards to the sandbox SSH server. Set only when the machine has no public IPv4 of its own; null otherwise. Connect with `ssh -p user@`. examples: - 203.0.113.10:22001 createdAt: type: - string - 'null' format: date-time updatedAt: type: - string - 'null' format: date-time archiveAfter: type: - string - 'null' format: date-time description: Automatic archival time, or null when auto-stop is disabled. desktopAvailable: type: boolean desktopUrl: type: - string - 'null' format: uri description: Secret-bearing desktop stream URL when available. Redact from logs. snapshots: type: boolean description: False when the sandbox was created with snapshots off. snapshotAvailable: type: boolean snapshotCompletedAt: type: - string - 'null' format: date-time description: >- Timestamp of the most recent successfully completed snapshot, or null. snapshotVerifiedAt: type: - string - 'null' format: date-time description: >- Last time a snapshot confirmed the sandbox's saved state, including checks that found nothing new to save. Falls back to `snapshotCompletedAt`; null if never. team: type: - object - 'null' description: >- The organization billed for this sandbox, or null when the owner is billed. required: - id - name properties: id: type: string name: type: string createdBy: type: - string - 'null' description: >- Display name (or email) of the person who created the sandbox. Organization members see every sandbox the organization pays for, so this says whose it is. createdById: type: - string - 'null' description: Account id of the person who created the sandbox. access: type: string enum: - owner - use - view description: >- What you may do with this sandbox. `owner`: you created it. `use`: a teammate's organization sandbox that is `noEnv` (created with it, or shared and restarted), so you can open, run commands in, prompt, resume and stop it. `view`: a teammate's organization sandbox that still holds their personal logins, so you can see it and stop it until they share it (`POST /sandboxes/{sandboxId}/share`). holdsCreatorLogins: type: boolean description: >- True while the sandbox still holds its creator's personal logins (GitHub token, model logins, secrets). Other members can only see such a sandbox. wipePendingUntilRestart: type: boolean description: >- True once the sandbox is shared but not restarted yet. Its creator's logins are wiped at its next start, and the organization can use it from then on. subdomain: type: - string - 'null' description: >- The sandbox's stable three-word subdomain slug (e.g. "frazil-pneuma-rallye"), or null before one is assigned. lastSnapshotAttemptAt: type: - string - 'null' format: date-time description: >- Timestamp of the most recent snapshot attempt of any status (queued, in_progress, completed, failed, cancelled), or null. Use with snapshotCompletedAt to detect snapshots that keep failing. lastSnapshotStatus: type: - string - 'null' enum: - queued - in_progress - completed - failed - cancelled - null description: >- Status of the most recent snapshot attempt, or null if none. A value other than completed while snapshotCompletedAt stays stale indicates failing snapshots. setupStatus: type: - string - 'null' enum: - pending - running - done - failed - null description: >- Outcome of the create-time `setupScript`: `pending` (stored, not yet started), `running` (executing on the sandbox in the background), `done` (exit code 0) or `failed` (non-zero exit, or the sandbox lost track of the process). Null when the sandbox was created without a setup script. setupError: type: - string - 'null' description: >- Short failure detail (exit code plus a stderr tail) when `setupStatus` is `failed`; while `pending`, may carry the last start/upload error from a retry in progress. Otherwise null. environment: type: - string - 'null' description: >- Name of the sandbox environment this sandbox is running, or null if it is attached to none (a `noEnv` sandbox, or one whose environment was deleted). A sandbox freezes onto one environment version when it starts and keeps it for life, so this is what the sandbox actually holds, not what the environment says today. examples: - base environmentVersion: type: - integer - 'null' description: >- Version number of `environment` that this sandbox is pinned to. Compare it against the environment's latest version to see whether an upgrade is pending: a sandbox below the latest is still running the older configuration until someone calls `POST /environments/{environmentId}/upgrade`. examples: - 3 ErrorEnvelope: type: object required: - ok - type - status - code - message - error - requestId properties: ok: type: boolean examples: - false type: type: string examples: - sandbox.error status: type: integer examples: - 409 code: type: string examples: - provider_not_configured message: type: string examples: - Prompting is locked until Codex is configured on the Agents page. requestId: type: string examples: - req_01HX... error: type: object required: - code - message - status properties: code: type: string message: type: string status: type: integer details: type: object additionalProperties: true responses: BadRequest: description: Invalid request body or parameters. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: invalid: value: ok: false type: sandbox.error status: 400 code: invalid_json message: Request body must be valid JSON. error: code: invalid_json message: Request body must be valid JSON. status: 400 requestId: req_01HX... Unauthorized: description: Missing or invalid bearer token. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: unauthorized: value: ok: false type: sandbox.error status: 401 code: unauthorized message: Unauthorized error: code: unauthorized message: Unauthorized status: 401 requestId: req_01HX... Forbidden: description: Authenticated token is not allowed to perform this action. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: forbidden: value: ok: false type: sandbox.error status: 403 code: forbidden message: Forbidden error: code: forbidden message: Forbidden status: 403 requestId: req_01HX... NotFound: description: Resource not found. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' securitySchemes: BoatBearerAuth: type: http scheme: bearer bearerFormat: sandbox_api_key description: >- Boat bearer token in the form `boat_...`. Service API keys authenticate sandbox operations. ````