> ## Documentation Index > Fetch the complete documentation index at: https://docs.hiloop.ai/llms.txt > Use this file to discover all available pages before exploring further. # Post v1sandboxes > Create a sandbox from an OCI image, a snapshot, or the platform default image when neither is named. A required Idempotency-Key makes retries replay the original accepted sandbox instead of creating another. The operation is asynchronous and returns 202 with Location and Retry-After; poll or long-poll GetSandbox for observed state. A supplied name is unique within the project; a duplicate returns 409 name_conflict. ## OpenAPI ````yaml /api-reference/openapi.yaml post /v1/sandboxes openapi: 3.0.3 info: title: '' version: 0.0.1 servers: [] security: - bearerAuth: [] tags: - name: AnnotationSchemaService description: |- Org-scoped annotation-schema registry CRUD. Every RPC scopes to the caller's organization, derived from their credential; a request with no org scope is UNAUTHENTICATED. Registration runs a backward-compatibility check against the latest live version and REJECTS an incompatible change (FAILED_PRECONDITION). These endpoints are what the generated OpenAPI, SDKs, and CLI consume. - name: AnnotationService description: >- Typed annotation surface over the telemetry store: the annotate writes plus the one served annotation read every consumer shares. Organization scoping is enforced from request identity, not from the request body. Ingest of ordinary telemetry lives in TelemetryIngestService (telemetry.proto); the general event read surface lives in TelemetryQueryService (query.proto). - name: FeedbackService description: |- Product-feedback intake. The organization is derived from the caller's credential, never from the request body; a request with no org scope is UNAUTHENTICATED. Any org-scoped caller — a user session, a service key, or a sandbox-scoped credential — may submit feedback. - name: IdentityService description: Identity/health surface for the control-plane API. - name: MetaService description: Unauthenticated discovery surface for client-visible sibling service URLs. - name: ProjectService description: |- Org-scoped project CRUD. Every RPC scopes to the caller's organization, derived from their credential; a request with no org scope is UNAUTHENTICATED. These endpoints are what the generated OpenAPI, SDKs, and CLI consume. - name: RunService description: |- Org-scoped access to runs and their lineage. Every RPC scopes to the caller's organization, derived from their credential; a request with no org scope is UNAUTHENTICATED. These endpoints are what the generated OpenAPI, SDKs, and CLI consume. - name: SandboxService description: |- Org-scoped sandbox runtime API. The organization comes from the caller's credential. Org-scoped human and service credentials may use every route in their organization. A sandbox-scoped, lineage-confined credential may read its own sandbox and snapshot lineage and may exec or snapshot only that sandbox; it may not create, update, or delete sandboxes, delete snapshots, or exec into a sibling sandbox. State and verb rules are closed. Get and list serve every visible state. Failed and terminated rows remain available through GetSandbox for a server retention window, then return 404 not_found. Update to stopped is accepted from ready or running and is idempotent from stopped; update to running wakes stopped and is idempotent from running. A wake racing an in-flight stop waits for stop to win before wake proceeds. Workspace growth is accepted only for a stable durable sandbox and is idempotent for the same target; lifecycle mutation and growth never overlap. An undurable snapshot, including one whose request timed out, fences growth and cannot be deleted because its seal may still publish a late receipt; repeat the same snapshot request (and idempotency key, if supplied) to resolve its outcome. Delete is accepted once for a nonterminal sandbox; a second delete returns 404 not_found. Exec requires running and never wakes implicitly; any other non-quarantined state returns 409 sandbox_not_running. Snapshot is accepted from ready, running, or stopped; other non-quarantined states return 409 sandbox_not_ready. Every mutating verb on a quarantined sandbox returns 409 quarantined. A concurrent snapshot returns 409 snapshot_in_progress. Every error uses the flat {code, message, request_id} envelope. Stable route codes are invalid_argument (400), not_found (404), idempotency_conflict, name_conflict, sandbox_not_running, sandbox_not_ready, quarantined, snapshot_in_progress, snapshot_in_use, and snapshot_not_restorable, workspace_shrink_unsupported, and operation_conflict (409), unsupported_capability (422), quota_exceeded (429; details.quota.metric names the limit — sandboxes.running, sandboxes.total, or sandboxes.workspace_capacity_gib), and unavailable (503). Exec transport failures use spawn_failed or sandbox_stopped and discard any partial output; both mean the command did not run. A command that WAS dispatched but whose outcome could not be read is never an error: it returns 200 with the indeterminate outcome, alongside whatever partial output was collected, as a timeout does. Capability-receipt observation has no route in this version and is explicitly NOTIMPL; it is not inferred from Sandbox fields. - name: SecretService description: |- Org-scoped sandbox-secret management. Every RPC scopes to the caller's organization, derived from their credential; a request with no org scope is UNAUTHENTICATED. Create/revoke/rotate require an owner/admin in the organization; these management RPCs never return the secret value. - name: TelemetryViewService description: >- Typed data-view surface over the telemetry store. Organization scoping is enforced from request identity, not from the request body. A data view's spec is the engine's `DataViewSpec` — a raw `Sql` `SELECT` — re-validated and compiled fresh on every run under the forced-organization safe-SQL gateway. The untrusted raw-SQL escape hatch is a separate `POST /v1/telemetry/sql` endpoint, intentionally kept off this typed wire. - name: UsageService description: Org-scoped product quota reads. - name: VolumeService description: |- Org-scoped volume CRUD. Every RPC scopes to the caller's organization, derived from their credential; a request with no org scope is UNAUTHENTICATED. These endpoints are what the generated OpenAPI, SDKs, and CLI consume. - name: WorkloadService description: |- Org-scoped workload registry management. The organization is derived from the caller's credential; a request with no org scope is UNAUTHENTICATED. Registering and reading workloads is open to any org member. Setting a launch ACL and deleting a workload are operator actions and require an owner or admin in the organization. A sandbox-scoped credential may not register, delete, or manage workloads. paths: /v1/sandboxes: post: tags: - SandboxService description: >- Create a sandbox from an OCI image, a snapshot, or the platform default image when neither is named. A required Idempotency-Key makes retries replay the original accepted sandbox instead of creating another. The operation is asynchronous and returns 202 with Location and Retry-After; poll or long-poll GetSandbox for observed state. A supplied name is unique within the project; a duplicate returns 409 name_conflict. operationId: SandboxService_CreateSandbox parameters: - name: idempotency-key in: header required: true description: >- Required idempotency key for this mutation. The server records the result from execution start. For at least 72 hours, reuse by the same organization and route replays the original status and body. A matching request still in flight or reuse for different input returns 409 idempotency_conflict. Keys are scoped by organization and route and contain 1-255 characters. schema: type: string minLength: 1 maxLength: 255 requestBody: content: application/json: schema: oneOf: - $ref: '#/components/schemas/CreateSandboxFromImageRequest' - $ref: '#/components/schemas/CreateSandboxFromSnapshotRequest' required: true responses: '202': description: Accepted content: application/json: schema: $ref: '#/components/schemas/CreateSandboxResponse' headers: Location: description: Canonical GetSandbox URL for the accepted sandbox. schema: type: string format: uri Retry-After: description: Minimum seconds to wait before reading observed state again. schema: type: integer format: uint32 minimum: 1 '429': $ref: '#/components/responses/SandboxRateLimited' default: $ref: '#/components/responses/SandboxError' components: schemas: CreateSandboxFromImageRequest: type: object properties: image: type: string description: The unmodified OCI image reference to start from. minLength: 1 ttl_seconds: type: integer description: Sandbox lifetime in seconds. Omit it to use the deployment default. format: uint32 minimum: 1 storage_class: enum: - standard - durable type: string description: >- Storage behavior for the sandbox. Omit it to use durable storage when restoring a snapshot, or standard storage for an image/platform-default create. format: enum default: standard ports: type: array items: type: integer format: uint32 minimum: 1 maximum: 65535 description: >- Unique guest TCP ports in the range 1-65535. Returned endpoints are authenticated private session-plane connections, not public preview URLs. uniqueItems: true volumes: type: array items: $ref: '#/components/schemas/SandboxVolumeMount' description: >- Pre-registered volumes to mount, each pinned to its current version at admission. secrets: type: array items: $ref: '#/components/schemas/SandboxSecretBinding' description: >- Pre-registered secrets to bind for proof-bound request-time delivery. metadata: type: object additionalProperties: type: string description: >- Caller-owned metadata: at most 50 entries, keys at most 128 characters, and at most 4096 bytes of total value content. maxProperties: 50 name: type: string description: >- Optional customer-supplied name, unique among the project's sandboxes that have not finished deleting. It must be 1-63 characters: lowercase letters or digits, with interior hyphens allowed. Omit it to leave the sandbox unnamed; the server never generates a name. A duplicate returns 409 name_conflict; a terminated sandbox's name is free to reuse, and its record keeps the name for history. minLength: 1 maxLength: 63 pattern: ^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$ resources: allOf: - $ref: '#/components/schemas/ResourceSpec' description: >- Requested compute resources. Omitted fields resolve to deployment defaults at admission, and the resolved shape is echoed on every Sandbox response. A GPU request is rejected with 422 unsupported_capability when the deployment cannot schedule accelerators. command: type: array items: type: string description: >- Argv that replaces the image's own entrypoint as the sandbox's first process. Omit it to run the image's ENTRYPOINT/CMD unchanged, which is what an image built to hold itself open wants. Supply it for an image whose entrypoint runs a task and exits, such as a base OS image or a build tool: a sandbox is something you attach to, and it lives only as long as its first process. The argv is executed directly rather than through a shell, so pipes and redirection belong inside a command you name explicitly. The executable must not be empty; at most 256 entries, each at most 4096 characters. workspace_capacity_gib: type: integer description: >- Durable workspace capacity in whole GiB. A root create may omit it to use the deployment default; a snapshot create inherits the snapshot-time value. A legacy snapshot whose capacity predates stamping requires an explicit value. This field is valid only with durable storage; standard storage has no persistent workspace claim. format: uint32 minimum: 1 placement_class: enum: - standard - non_preemptible type: string description: >- Capacity posture for this sandbox. Omit it to use standard placement. format: enum idle_timeout_seconds: type: integer description: >- Idle duration in seconds after which a running sandbox is stopped. Omit it to use the deployment default; when the deployment has no default, idle stopping is disabled. Values are from 60 through 86400. format: uint32 minimum: 60 maximum: 86400 shared_filesystems: type: array items: $ref: '#/components/schemas/SandboxSharedFilesystemMount' description: >- Deployment-registered shared filesystems to mount. Shared filesystems are external to this sandbox's snapshots; durable storage is required for the sandbox's private runtime state. network_access: enum: - public - gateway_only - none type: string description: Outbound-network posture. Omit it to use public access. format: enum additionalProperties: false description: >- Create a root sandbox from an OCI image; omitting image starts from the platform default image. CreateSandboxFromSnapshotRequest: type: object properties: snapshot_id: type: string description: The snapshot to restore as a new child sandbox. minLength: 1 ttl_seconds: type: integer description: Sandbox lifetime in seconds. Omit it to use the deployment default. format: uint32 minimum: 1 storage_class: enum: - standard - durable type: string description: >- Storage behavior for the sandbox. Omit it to use durable storage when restoring a snapshot, or standard storage for an image/platform-default create. format: enum default: durable ports: type: array items: type: integer format: uint32 minimum: 1 maximum: 65535 description: >- Unique guest TCP ports in the range 1-65535. Returned endpoints are authenticated private session-plane connections, not public preview URLs. uniqueItems: true volumes: type: array items: $ref: '#/components/schemas/SandboxVolumeMount' description: >- Pre-registered volumes to mount, each pinned to its current version at admission. secrets: type: array items: $ref: '#/components/schemas/SandboxSecretBinding' description: >- Pre-registered secrets to bind for proof-bound request-time delivery. image_override: type: string description: >- The image to run the restored workspace on, when it should not be the one the snapshot recorded. Only meaningful with snapshot_id: a snapshot carries workspace bytes, and this names the runtime they are materialized onto, which is how a sandbox takes a newer base image without losing what is in its workspace. Omit it to run the image the snapshot recorded. metadata: type: object additionalProperties: type: string description: >- Caller-owned metadata: at most 50 entries, keys at most 128 characters, and at most 4096 bytes of total value content. maxProperties: 50 name: type: string description: >- Optional customer-supplied name, unique among the project's sandboxes that have not finished deleting. It must be 1-63 characters: lowercase letters or digits, with interior hyphens allowed. Omit it to leave the sandbox unnamed; the server never generates a name. A duplicate returns 409 name_conflict; a terminated sandbox's name is free to reuse, and its record keeps the name for history. minLength: 1 maxLength: 63 pattern: ^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$ resources: allOf: - $ref: '#/components/schemas/ResourceSpec' description: >- Requested compute resources. Omitted fields resolve to deployment defaults at admission, and the resolved shape is echoed on every Sandbox response. A GPU request is rejected with 422 unsupported_capability when the deployment cannot schedule accelerators. command: type: array items: type: string description: >- Argv that replaces the image's own entrypoint as the sandbox's first process. Omit it to run the image's ENTRYPOINT/CMD unchanged, which is what an image built to hold itself open wants. Supply it for an image whose entrypoint runs a task and exits, such as a base OS image or a build tool: a sandbox is something you attach to, and it lives only as long as its first process. The argv is executed directly rather than through a shell, so pipes and redirection belong inside a command you name explicitly. The executable must not be empty; at most 256 entries, each at most 4096 characters. workspace_capacity_gib: type: integer description: >- Durable workspace capacity in whole GiB. A root create may omit it to use the deployment default; a snapshot create inherits the snapshot-time value. A legacy snapshot whose capacity predates stamping requires an explicit value. This field is valid only with durable storage; standard storage has no persistent workspace claim. format: uint32 minimum: 1 placement_class: enum: - standard - non_preemptible type: string description: >- Capacity posture for this sandbox. Omit it to use standard placement. format: enum idle_timeout_seconds: type: integer description: >- Idle duration in seconds after which a running sandbox is stopped. Omit it to use the deployment default; when the deployment has no default, idle stopping is disabled. Values are from 60 through 86400. format: uint32 minimum: 60 maximum: 86400 shared_filesystems: type: array items: $ref: '#/components/schemas/SandboxSharedFilesystemMount' description: >- Deployment-registered shared filesystems to mount. Shared filesystems are external to this sandbox's snapshots; durable storage is required for the sandbox's private runtime state. network_access: enum: - public - gateway_only - none type: string description: Outbound-network posture. Omit it to use public access. format: enum required: - snapshot_id additionalProperties: false description: Create a child sandbox from an existing snapshot. CreateSandboxResponse: type: object properties: id: type: string description: >- The new sandbox id. Poll GetSandbox with this id for observed lifecycle state. request_state: enum: - requested type: string description: >- The accepted mutation-request state, distinct from observed sandbox lifecycle state. format: enum run_id: type: string description: >- The ambient run that receives telemetry captured for this sandbox. An idempotent create retry returns the same run id. required: - id - request_state - run_id SandboxVolumeMount: type: object properties: volume_id: type: string description: >- The volume id to mount. Its current immutable version is pinned at admission. minLength: 1 maxLength: 255 target_path: type: string description: The absolute path at which the volume is mounted inside the sandbox. minLength: 1 maxLength: 4096 pattern: ^/ description: A pre-registered volume mounted when the sandbox is created. required: - volume_id - target_path SandboxSecretBinding: type: object properties: name: type: string description: >- The registered secret name. Admission binds its exact proof-bound destination and use grant. minLength: 1 maxLength: 128 description: A pre-registered secret bound when the sandbox is created. required: - name ResourceSpec: type: object properties: memory_mb: type: integer description: >- Requested memory in MB (mebibytes: 1024 MB = 1 GiB), from 1 through 1048576. Omit it to use the deployment default. format: uint32 minimum: 1 maximum: 1048576 gpus: allOf: - $ref: '#/components/schemas/ResourceSpec_Gpus' description: Requested accelerators. Omit it to request none. cpu_millis: type: integer description: >- Requested CPU in milliCPU, from 50 through 128000. 1000 milliCPU is one vCPU. Omit it to use the deployment default. format: uint32 minimum: 50 maximum: 128000 description: >- Declarative compute resources for a sandbox. Requests are burstable: the sandbox is guaranteed its requested shape and may use idle node capacity beyond it. SandboxSharedFilesystemMount: type: object properties: filesystem_id: type: string description: Deployment-registered filesystem id. subdirectory: type: string description: >- Existing relative directory within the filesystem to mount. The directory must already exist when the sandbox pod starts. target_path: type: string description: >- Guest path at which the selected directory is mounted. It is either /workspace, which moves the sandbox's private durable workspace to /private, or a normalized path below /mnt, which leaves the private workspace at /workspace. Other paths are refused so shared storage cannot replace image executables, configuration, or platform-owned mounts. description: >- A deployment-registered shared filesystem mounted when the sandbox is created. The deployment resolves filesystem_id to its storage backend. Credentials and backend coordinates are never accepted from the sandbox caller or exposed inside the sandbox. SandboxQuotaErrorBody: type: object additionalProperties: false required: - code - message - request_id - metric - limit - retry_after_seconds properties: code: type: string description: Stable machine-readable error code in snake_case. message: type: string description: Human-readable description; clients must not parse it. request_id: type: string description: Correlation id for support and diagnostics. metric: type: string description: Stable name of the exhausted quota metric. limit: type: integer format: uint64 description: Configured limit for the caller's organization. retry_after_seconds: type: integer format: uint64 description: Seconds to wait before retrying. SandboxErrorBody: type: object additionalProperties: false required: - code - message - request_id properties: code: type: string description: Stable machine-readable error code in snake_case. message: type: string description: Human-readable description; clients must not parse it. request_id: type: string description: Correlation id for support and diagnostics. ResourceSpec_Gpus: type: object properties: count: type: integer description: Integral accelerator count. format: uint32 models: type: array items: type: string description: >- Ordered fallback list of acceptable accelerator models. An empty list accepts any advertised model. description: Requested accelerators. responses: SandboxRateLimited: description: Sandbox admission rejected by a quota limit. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer format: uint64 content: application/json: schema: $ref: '#/components/schemas/SandboxQuotaErrorBody' SandboxError: description: An error using the successor flat API error envelope. headers: Retry-After: description: Seconds to wait before retrying when the error is retryable. schema: type: integer format: uint64 content: application/json: schema: $ref: '#/components/schemas/SandboxErrorBody' securitySchemes: bearerAuth: type: http scheme: bearer description: Hiloop API key sent as an HTTP Bearer token. ````