> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tensorlake.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Restore Sandbox

> Restore a sandbox from a previously created snapshot by calling the create endpoint with a `snapshot_id`.

Restore a new sandbox from a previously created snapshot.

## Endpoint

```http theme={null}
POST /sandboxes
```

To restore from a snapshot, call the standard create sandbox endpoint and include `snapshot_id` in the request body.

* If the snapshot type is filesystem (default), the new sandbox restores the captured filesystem. You can override launch settings (including resources).
* If the snapshot type is memory, the new sandbox restores filesystem, memory, and running processes exactly as they were. Image, resources (CPUs, memory), entrypoint, and secrets come from the snapshot and cannot be changed at restore time.

## Example Request

```bash theme={null}
curl -X POST https://api.tensorlake.ai/sandboxes \
  -H "Authorization: Bearer $TENSORLAKE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "snapshot_id": "<snapshot-id>"
  }'
```

For filesystem snapshots, `resources.disk_mb` can be used at restore time to grow the root disk (growth-only).

For the full request and response schema of `POST /sandboxes`, see [Create Sandbox](/api-reference/v2/sandboxes/create). For the end-to-end snapshot workflow, see [Snapshots](/sandboxes/snapshots).


## OpenAPI

````yaml post /sandboxes
openapi: 3.1.0
info:
  title: Tensorlake API
  description: >-
    Tensorlake Cloud APIs for Sandboxes, Document Ingestion, and Serverless
    Workflows
  license:
    name: ''
  version: 0.1.0
servers:
  - url: https://api.tensorlake.ai/
security:
  - bearerAuth: []
tags:
  - name: Tensorlake Cloud API
    description: >-
      Tensorlake Cloud APIs for Sandboxes, Document Ingestion, and Serverless
      Workflows
paths:
  /sandboxes:
    post:
      tags:
        - sandboxes
      summary: Create a sandbox
      description: Create an ephemeral or named sandbox.
      operationId: create_sandbox
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSandboxRequest'
        required: true
      responses:
        '200':
          description: Sandbox created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateSandboxResponse'
        '400':
          description: Invalid sandbox creation request
          content:
            text/plain: {}
        '401':
          description: Unauthorized. Invalid or missing credentials
        '403':
          description: Forbidden. You do not have permission to access this resource
        '404':
          description: Referenced snapshot was not found
          content:
            text/plain: {}
        '409':
          description: A sandbox with the requested name already exists in this namespace
          content:
            text/plain: {}
        '422':
          description: Invalid properties in request body
          content:
            text/plain: {}
        '500':
          description: Internal server error
          content:
            text/plain: {}
components:
  schemas:
    CreateSandboxRequest:
      type: object
      properties:
        image:
          type: string
          description: >-
            Optional sandbox image name to boot from. When omitted, Tensorlake
            uses the default managed environment. This can also be a registered
            Sandbox Image name.
        resources:
          $ref: '#/components/schemas/SandboxResourceOverrides'
        secret_names:
          type: array
          description: Secret names to inject into the sandbox.
          items:
            type: string
        timeout_secs:
          type: integer
          format: int64
          minimum: 0
          description: >
            Sandbox timeout in seconds. `0` requests the maximum allowed by your
            plan.

            Plan maximums: Free unverified 3600 (1h), Free verified 7200 (2h),

            On-Demand 86400 (24h). See
            [tensorlake.ai/pricing](https://www.tensorlake.ai/pricing) for
            higher limits on committed plans.
        entrypoint:
          type: array
          description: Optional command to run when the sandbox starts.
          items:
            type: string
        network:
          $ref: '#/components/schemas/SandboxNetworkAccessControl'
        snapshot_id:
          type: string
          description: Snapshot to restore from.
        allow_unauthenticated_access:
          type: boolean
          description: >-
            Allow sandbox ingress to route requests without validating auth
            credentials. The legacy request alias
            `allow_unauthenticated_proxy_access` is also accepted.
        exposed_ports:
          type: array
          description: >-
            Additional sandbox ports that public ingress may route to. When
            omitted, only the management port `9501` is routable.
          items:
            type: integer
            format: int32
            minimum: 1
            maximum: 65535
        template_id:
          type: string
          description: Template identifier to associate with the launched sandbox.
        name:
          type: string
          description: >-
            Optional user-provided sandbox name. When set, the sandbox is named
            and supports suspend/resume. When omitted, the sandbox is ephemeral.
        file_systems:
          type: array
          description: >-
            Filesystems to mount into the sandbox, each at its own absolute,
            unique, non-nested guest mount path. At most 8 per sandbox. Mounts
            are ready before the sandbox is reported as running; a filesystem
            that does not exist fails the create with `422` and reason
            `FileSystemNotFound`, and a pinned `snapshot_id` that is not a
            permanent snapshot fails it with reason
            `FileSystemSnapshotNotFound`.
          items:
            $ref: '#/components/schemas/FileSystemMount'
    CreateSandboxResponse:
      type: object
      required:
        - sandbox_id
        - status
      properties:
        sandbox_id:
          type: string
        status:
          $ref: '#/components/schemas/SandboxStatus'
        pending_reason:
          $ref: '#/components/schemas/SandboxPendingReason'
        ingress_endpoint:
          type:
            - string
            - 'null'
          description: Base ingress origin for this sandbox's current placement.
    SandboxResourceOverrides:
      type: object
      properties:
        cpus:
          type: number
          format: double
          description: CPU allocation override in cores.
        memory_mb:
          type: integer
          format: int64
          description: Memory allocation override in MiB.
        disk_mb:
          type: integer
          format: int64
          minimum: 10240
          maximum: 102400
          description: >
            Ephemeral root filesystem size in MiB. Defaults to 10240 (10 GiB).

            Must be between 10240 and 102400 inclusive. For filesystem
            snapshots,

            this can be used with snapshot_id to grow root disk size
            (growth-only).
        gpus:
          type: array
          items:
            $ref: '#/components/schemas/GPUResources'
          description: Optional GPU allocation override.
    SandboxNetworkAccessControl:
      type: object
      properties:
        allow_internet_access:
          type: boolean
          default: true
          description: >-
            Allows internet access, including DNS requests. If false, all
            outbound traffic except destinations in allow_out is blocked,
            including DNS requests. If allow_out is non-empty and this is true,
            only the listed destinations and DNS requests are allowed.
        allow_out:
          type: array
          description: >-
            Allowed domains, IPv4 addresses, or IPv4 CIDRs. A non-empty list
            allows the listed destinations and DNS requests when
            allow_internet_access is true. Hostname rules are followed across
            DNS changes. A destination also matched by deny_out is blocked.
          items:
            type: string
        deny_out:
          type: array
          description: >-
            Denied domains, IPv4 addresses, or IPv4 CIDRs. Takes precedence over
            allow_out; a destination matched by both is blocked.
          items:
            type: string
    FileSystemMount:
      type: object
      required:
        - file_system_id
        - mount_path
      properties:
        file_system_id:
          type: string
          description: >-
            Filesystem name within the project — the name created with `tl fs
            create <name>`. ASCII letters, digits, `_`, and `-` only.
        mount_path:
          type: string
          description: >-
            Absolute guest mount path (e.g. `/mnt/skills`). Must not be `/` or
            contain `..`; paths are normalized, and mount paths must be unique
            and non-nested within the sandbox.
        read_only:
          type: boolean
          default: false
          description: >-
            Mount the filesystem read-only. Writes inside the guest fail with
            `EROFS`; the mount's storage credential carries no write scope.
            Fail-closed — sandboxes requesting read-only mounts are only placed
            on fleets that can enforce them.
        prefetch:
          type: boolean
          default: false
          description: >-
            Download the filesystem's full tree in the background after the
            mount is ready. The mount is usable immediately with lazy reads
            meanwhile. Best-effort — never blocks or fails the sandbox, and
            older fleets skip it silently.
        snapshot_id:
          type: string
          description: >-
            Pin the mount to a permanent snapshot of the filesystem (created
            with `tl fs snapshot` or a message-bearing `tl fs push`; ids listed
            by `tl fs history`). A pinned mount serves exactly that snapshot and
            never follows the live filesystem head. Requires `read_only` to be
            `true` — a `snapshot_id` without `read_only` is rejected with `400`.
            Pinning an id that is not a permanent snapshot of the filesystem
            fails the sandbox with `termination_reason`
            `FileSystemSnapshotNotFound`. Omit for an unpinned mount that
            follows the live filesystem; responses omit the field for unpinned
            mounts.
    SandboxStatus:
      type: string
      enum:
        - pending
        - running
        - snapshotting
        - suspending
        - suspended
        - terminated
    SandboxPendingReason:
      type: string
      enum:
        - scheduling
        - waiting_for_container
        - no_executors_available
        - no_resources_available
        - pool_at_capacity
    GPUResources:
      type: object
      required:
        - count
        - model
      properties:
        count:
          type: integer
          format: int32
          minimum: 1
        model:
          type: string
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````