> ## 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.

# Update Sandbox

> Update proxy-visible sandbox settings such as public exposed ports and whether ingress can skip authentication checks.

Update settings of a running sandbox.

This endpoint controls the sandbox proxy allowlist (`exposed_ports` and `allow_unauthenticated_access`), the sandbox `name`, and the egress `network` policy. The `network` field is tri-state: omit it to leave the policy unchanged, send an object to replace it, or send `null` to clear it. See [Networking](/sandboxes/networking#update-the-policy-on-a-running-sandbox) for details.


## OpenAPI

````yaml patch /sandboxes/{sandbox_id}
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/{sandbox_id}:
    parameters:
      - name: sandbox_id
        in: path
        description: The ID of the sandbox.
        required: true
        schema:
          type: string
    patch:
      tags:
        - sandboxes
      summary: Update a sandbox
      description: >-
        Update proxy-visible sandbox settings such as public exposed ports and
        whether ingress can skip authentication checks.
      operationId: update_sandbox
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchSandboxRequest'
        required: true
      responses:
        '200':
          description: Sandbox updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SandboxInfo'
        '401':
          description: Unauthorized. Invalid or missing credentials
        '403':
          description: Forbidden. You do not have permission to access this resource
        '404':
          description: Sandbox not found
          content:
            text/plain: {}
        '409':
          description: Sandbox is terminated and cannot be updated
          content:
            text/plain: {}
        '422':
          description: Invalid properties in request body
          content:
            text/plain: {}
        '500':
          description: Internal server error
          content:
            text/plain: {}
components:
  schemas:
    PatchSandboxRequest:
      type: object
      properties:
        allow_unauthenticated_access:
          type: boolean
          description: Set or clear unauthenticated ingress routing for this sandbox.
        exposed_ports:
          type: array
          description: >-
            Replace the exposed port allowlist. Pass an empty array to clear it
            and revert to the default management port only.
          items:
            type: integer
            format: int32
            minimum: 1
            maximum: 65535
        network:
          allOf:
            - $ref: '#/components/schemas/SandboxNetworkAccessControl'
          description: >-
            Update the egress network policy of the running sandbox. This field
            is tri-state: omit it to leave the current policy unchanged, send an
            object to replace the whole policy, or send an explicit null to
            clear it (unrestricted egress). The change is applied to the live
            sandbox firewall as one atomic swap with no enforcement gap;
            already-established connections are not revoked. If a hostname in
            the new policy fails to resolve, the update is rejected and the
            previous policy stays enforced.
    SandboxInfo:
      type: object
      required:
        - id
        - namespace
        - status
        - created_at
        - resources
        - timeout_secs
        - allow_unauthenticated_access
      properties:
        id:
          type: string
        namespace:
          type: string
        image:
          type: string
        status:
          $ref: '#/components/schemas/SandboxStatus'
        pending_reason:
          type:
            - string
            - 'null'
          description: Present when `status` is `pending`.
        outcome:
          type:
            - string
            - 'null'
          description: >-
            Platform-specific termination outcome string returned for completed
            sandboxes.
        termination_reason:
          type:
            - string
            - 'null'
          description: >-
            Typed reason the sandbox terminated (e.g. `FileSystemNotFound`,
            `FileSystemSnapshotNotFound`, `ImageNotFound`). Present on failed
            terminations.
        error_details:
          type:
            - string
            - 'null'
          description: Human-readable detail accompanying `termination_reason`.
        created_at:
          type: integer
          format: int64
          description: Milliseconds since Unix epoch.
        container_id:
          type:
            - string
            - 'null'
        executor_id:
          type:
            - string
            - 'null'
        resources:
          $ref: '#/components/schemas/ContainerResourcesInfo'
        timeout_secs:
          type: integer
          format: int64
        ingress_endpoint:
          type:
            - string
            - 'null'
          description: Canonical server-provided base for sandbox-specific ingress.
        sandbox_url:
          type:
            - string
            - 'null'
          description: Sandbox-specific management URL derived from `ingress_endpoint`.
        pool_id:
          type:
            - string
            - 'null'
        network_policy:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/SandboxNetworkAccessControl'
        allow_unauthenticated_access:
          type: boolean
          description: Whether sandbox ingress may route requests without auth validation.
        exposed_ports:
          type:
            - array
            - 'null'
          items:
            type: integer
            format: int32
            minimum: 1
            maximum: 65535
          description: >-
            Additional routable ingress ports. When `null`, only the management
            port `9501` is routable.
        template_id:
          type:
            - string
            - 'null'
        name:
          type:
            - string
            - 'null'
        file_systems:
          type: array
          description: Filesystems currently mounted into the sandbox.
          items:
            $ref: '#/components/schemas/FileSystemMount'
    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
    SandboxStatus:
      type: string
      enum:
        - pending
        - running
        - snapshotting
        - suspending
        - suspended
        - terminated
    ContainerResourcesInfo:
      type: object
      required:
        - cpus
        - memory_mb
        - disk_mb
      properties:
        cpus:
          type: number
          format: double
          description: CPU allocation in cores.
        memory_mb:
          type: integer
          format: int64
          description: Memory allocation in MiB.
        disk_mb:
          type: integer
          format: int64
          description: Ephemeral root filesystem size in MiB.
    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.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````