> ## Documentation Index > Fetch the complete documentation index at: https://docs.archil.com/llms.txt > Use this file to discover all available pages before exploring further. # Fork Sandbox > Checkpoints a running source sandbox and creates an isolated writable disk branch. Forks from running or paused sources resume from the source's CPU, memory, and disk state. Forks from stopped sources cold-boot from the saved disk checkpoint. A running source is resumed after its checkpoint; paused and stopped sources remain inactive. Forked sandboxes may themselves be forked. Passing `checkpoint` forks that saved state without touching the source, so clients can pause once, wait for the checkpoint, and fork it from any number of places. Without `checkpoint` the server pauses a running source inside the request and resumes it afterwards; that path is kept for older clients and is bounded by the request timeout. Sandboxes with additional disk mounts must be stopped before forking. The fork inherits mounts of the same external disks; only the internal root disk is branched, so external disk contents are not isolated. ## OpenAPI ````yaml POST /api/sandboxes/{sid}/fork openapi: 3.1.0 info: title: Archil Control Plane API description: > The Archil Control Plane API provides programmatic access to manage disks, persistent sandboxes, mounts, and API keys in the Archil distributed filesystem platform. API keys authenticate requests to this control plane and are scoped to your account. They are distinct from *disk tokens*, which are per-disk credentials used by clients when mounting a disk. ## Authentication All endpoints require an API key: ``` Authorization: {API_KEY} ``` Create API keys in the [Archil Console](https://console.archil.com) or via the API. ## Response Format All responses use a consistent envelope: ```json { "success": true, "data": { ... } } ``` Or on error: ```json { "success": false, "error": "Error message" } ``` version: 1.0.0 contact: email: support@archil.com url: https://archil.com servers: - url: https://control.green.us-east-1.aws.prod.archil.com description: AWS US East (N. Virginia) — aws-us-east-1 - url: https://control.green.eu-west-1.aws.prod.archil.com description: AWS EU West (Ireland) — aws-eu-west-1 - url: https://control.green.us-west-2.aws.prod.archil.com description: AWS US West (Oregon) — aws-us-west-2 - url: https://control.blue.us-central1.gcp.prod.archil.com description: GCP US Central (Iowa) — gcp-us-central1 security: - ApiKeyAuth: [] tags: - name: Disks description: Create, read, update, and delete disks - name: Serverless Execution description: Run commands on a disk without provisioning compute - name: Sandboxes description: Manage persistent sandbox virtual machines - name: Disk Users description: Manage authorized users on disks - name: API Tokens description: >- Manage API keys (also called API tokens) used to authenticate Control Plane API requests. Distinct from disk tokens. paths: /api/sandboxes/{sid}/fork: post: tags: - Sandboxes summary: Fork a sandbox description: | Checkpoints a running source sandbox and creates an isolated writable disk branch. Forks from running or paused sources resume from the source's CPU, memory, and disk state. Forks from stopped sources cold-boot from the saved disk checkpoint. A running source is resumed after its checkpoint; paused and stopped sources remain inactive. Forked sandboxes may themselves be forked. Passing `checkpoint` forks that saved state without touching the source, so clients can pause once, wait for the checkpoint, and fork it from any number of places. Without `checkpoint` the server pauses a running source inside the request and resumes it afterwards; that path is kept for older clients and is bounded by the request timeout. Sandboxes with additional disk mounts must be stopped before forking. The fork inherits mounts of the same external disks; only the internal root disk is branched, so external disk contents are not isolated. operationId: forkSandbox parameters: - $ref: '#/components/parameters/SandboxId' - $ref: '#/components/parameters/Wait' requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/ForkSandboxRequest' example: name: agent-fork responses: '202': description: >- The fork was created; status is pending or running when wait=true completes startup content: application/json: schema: $ref: '#/components/schemas/ApiResponse_Sandbox' example: success: true data: sandbox_id: 019d158f-5b60-7000-8000-0123456789ab name: agent-fork status: pending vcpu_count: 2 mem_size_mib: 4096 max_ttl_seconds: 86400 idle_ttl_seconds: 0 max_concurrent_execs: 32 enable_service_ingress: false base_image: python:3.13 mounts: - disk_id: dsk-0123456789abcdef path: /mnt/data created_at: '2026-10-06T12:00:00Z' last_active_at: '2026-10-06T12:00:00Z' '400': $ref: '#/components/responses/SandboxValidationError' '401': $ref: '#/components/responses/PlainTextUnauthorized' '404': $ref: '#/components/responses/SandboxNotFound' '409': description: >- Source state or mounted disks prevent the fork, the checkpoint is unavailable, or the name is already in use content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: mountedSource: summary: Stop the source before forking mounted disks value: success: false error: >- sandbox has mounted disks: disk dsk-0123456789abcdef is mounted at /mnt/data; stop the sandbox before forking it code: sandbox_fork_mounted checkpointUnavailable: summary: Checkpoint unavailable value: success: false error: The sandbox fork checkpoint is unavailable code: sandbox_fork_checkpoint notForkable: summary: Source cannot be forked value: success: false error: Only a running, paused, or stopped sandbox can be forked code: sandbox_not_forkable nameConflict: summary: Name already in use value: success: false error: A sandbox with this name already exists code: sandbox_name_conflict '500': $ref: '#/components/responses/SandboxInternalError' '503': $ref: '#/components/responses/SandboxUnavailable' '504': $ref: '#/components/responses/SandboxTimeout' components: parameters: SandboxId: name: sid in: path required: true description: Sandbox UUID schema: type: string format: uuid Wait: name: wait in: query required: false description: Hold the request for a completed sandbox lifecycle transition schema: type: boolean default: false schemas: ForkSandboxRequest: type: object properties: name: type: string minLength: 1 maxLength: 63 pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$ description: >- Name for the fork. A random word-list name is generated when omitted. checkpoint: type: string description: | Fork this checkpoint of the source, as returned by pause, stop, or describe, instead of the source's live state. The source is neither paused nor resumed. Only the current session's checkpoint and the one before it are accepted; an uncommitted or superseded checkpoint is rejected with 409. ApiResponse_Sandbox: type: object required: - success - data properties: success: type: boolean example: true data: $ref: '#/components/schemas/Sandbox' ErrorResponse: type: object required: - success - error properties: success: type: boolean example: false error: type: string example: Invalid request parameters code: type: string description: Stable machine-readable error code. Sandbox: type: object required: - sandbox_id - name - status - vcpu_count - mem_size_mib - max_ttl_seconds - idle_ttl_seconds - max_concurrent_execs - base_image - created_at - last_active_at properties: sandbox_id: type: string format: uuid name: type: string minLength: 1 maxLength: 63 pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$ description: Sandbox name. status: $ref: '#/components/schemas/SandboxState' vcpu_count: type: integer mem_size_mib: type: integer max_ttl_seconds: type: integer description: >- Lifetime budget applied independently to each powered-on session. Expiry pauses the sandbox, preserving memory and processes for resume. Defaults to 24 hours. Timeout resets cannot extend a session beyond 24 hours. idle_ttl_seconds: type: integer description: >- Seconds without a direct process connection before the sandbox pauses, preserving memory and processes for resume. Zero disables idle expiry. max_concurrent_execs: type: integer description: >- Maximum number of concurrently attached process sessions. Detached processes and one-shot process controls do not count. base_image: type: string description: >- OCI reference requested when the sandbox was created. Empty for a sandbox created from `image_id`. image_digest: type: string description: Image digest the sandbox was created from, if any. platform: type: string enum: - arm64 - amd64 description: Sandbox CPU architecture. endpoints: type: array description: Public hostnames published by enabled sandbox services. items: $ref: '#/components/schemas/SandboxEndpoint' enable_service_ingress: type: boolean default: false description: >- Whether services inside the sandbox can expose ingress. Explicit API port exposure remains available regardless of this setting. mounts: type: array items: $ref: '#/components/schemas/SandboxMount' created_at: type: string format: date-time running_at: type: string format: date-time finished_at: type: string format: date-time last_active_at: type: string format: date-time exit_reason: type: string checkpoint: type: string description: | Disk checkpoint the current session leaves behind. Present while pausing, paused, stopping, or stopped, and committed once the sandbox is paused or stopped. Pass it to the fork endpoint to fork exactly this state. SandboxState: type: string enum: - pending - running - pausing - paused - stopping - stopped - exited - failed - deleting - deleted SandboxEndpoint: type: object required: - port - hostname properties: port: type: integer minimum: 1 maximum: 65535 hostname: type: string SandboxMount: type: object required: - disk_id properties: disk_id: type: string pattern: ^dsk-[0-9a-f]{16}$ description: >- Existing disk owned by your account in the sandbox's region. A sandbox's internal root disk cannot be used here. path: type: string description: >- Absolute guest directory to mount at. Required when more than one disk is mounted; a sole mount defaults to /mnt/archil. Paths cannot overlap or contain whitespace, control characters, empty components, . or .. components, or a trailing slash. The root directory and guest system directories (/usr, /etc, /var, /opt, /dev, ...) and their descendants are reserved. A disk can be mounted once per sandbox. subdirectory: type: string description: Relative subdirectory of the disk to expose instead of its root. read_only: type: boolean default: false conditional: type: boolean default: false description: >- Send mutating operations directly to the server without a delegation checkout, allowing concurrent writers. queue_ms: type: integer minimum: 1 description: >- Milliseconds to wait for the disk's exclusive root delegation before the mount fails. Not allowed with read_only or conditional. responses: SandboxValidationError: description: Invalid request body or parameters content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: Invalid request body code: bad_request PlainTextUnauthorized: description: Missing or invalid authentication credentials content: text/plain: schema: type: string examples: missingAuthorization: summary: Missing Authorization header value: Must provide an Authorization header invalidCredentials: summary: Invalid credentials value: Unauthorized SandboxNotFound: description: Sandbox not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: Sandbox not found code: not_found SandboxInternalError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: Internal error processing sandbox request code: internal_server_error SandboxUnavailable: description: >- Sandbox capacity or runtime temporarily unavailable, or sandboxes are disabled content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: noCapacity: summary: No capacity value: success: false error: No sandbox capacity is available; retry code: no_capacity runtimeRetryable: summary: Retryable runtime failure value: success: false error: Sandbox lifecycle request is temporarily blocked; retry code: runtime_retryable notEnabled: summary: Sandboxes disabled value: success: false error: Sandboxes are not enabled on this controlplane code: not_enabled SandboxTimeout: description: Request timed out; retry content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: success: false error: Sandbox request timed out; retry code: timeout securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: API key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.