Attach Filesystem

Attach a filesystem to a running sandbox at an absolute guest mount path. Returns 200 OK once the mount is persisted; the mount applies asynchronously on the live sandbox. If the mount later cannot converge — including a file_system_id that does not exist, or a pinned snapshot_id that is not a permanent snapshot of the filesystem — the sandbox is terminated fail-closed with termination_reason and error_details on the sandbox object, so verify the filesystem exists (for example with tl fs ls) and the snapshot is listed by tl fs history before attaching.

POST /sandboxes/{sandbox_id}/file_systems

Attach a filesystem

cURL

curl --request POST \
  --url https://api.tensorlake.ai/sandboxes/{sandbox_id}/file_systems \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "file_system_id": "<string>",
  "mount_path": "<string>",
  "read_only": false,
  "prefetch": false,
  "snapshot_id": "<string>"
}
'

200

{
  "id": "<string>",
  "namespace": "<string>",
  "status": "pending",
  "created_at": 123,
  "resources": {
    "cpus": 123,
    "memory_mb": 123,
    "disk_mb": 123
  },
  "timeout_secs": 123,
  "allow_unauthenticated_access": true,
  "image": "<string>",
  "pending_reason": "<string>",
  "outcome": "<string>",
  "termination_reason": "<string>",
  "error_details": "<string>",
  "container_id": "<string>",
  "executor_id": "<string>",
  "ingress_endpoint": "<string>",
  "sandbox_url": "<string>",
  "pool_id": "<string>",
  "network_policy": {
    "allow_internet_access": true,
    "allow_out": [
      "<string>"
    ],
    "deny_out": [
      "<string>"
    ]
  },
  "exposed_ports": [
    32768
  ],
  "template_id": "<string>",
  "name": "<string>",
  "file_systems": [
    {
      "file_system_id": "<string>",
      "mount_path": "<string>",
      "read_only": false,
      "prefetch": false,
      "snapshot_id": "<string>"
    }
  ]
}

Attach a filesystem to a running sandbox at an absolute guest mount path.

• This path accepts either the sandbox ID or the sandbox name.
• file_system_id is the filesystem’s name — the one created with tl fs create <name>.
• 200 OK means the mount is persisted; it applies asynchronously on the live sandbox moments later.
• snapshot_id pins the mount to a permanent snapshot (requires read_only: true); see Pinned mounts.
• If the mount later cannot converge — including a filesystem that does not exist, or a pinned snapshot that is not a permanent snapshot of the filesystem — the sandbox is terminated fail-closed with termination_reason and error_details on the sandbox object. Verify the filesystem exists (e.g. tl fs ls) and the snapshot is listed by tl fs history before attaching.
• Tensorlake returns 400 Bad Request for a snapshot_id without read_only, or when the sandbox runs on an executor fleet without filesystem or snapshot-pin support.
• Tensorlake returns 409 Conflict when the sandbox is not running, the mount path is already in use, the sandbox is at the 8-mount cap, or the sandbox’s executor is momentarily unresolvable. The last case is transient — retry shortly.

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

sandbox_id · string · required

The sandbox ID or sandbox name.

Body

application/json

file_system_id · string · required

Filesystem name within the project — the name created with tl fs create <name>. ASCII letters, digits, _, and - only.

mount_path · string · required

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 · boolean · default: false

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 · boolean · default: false

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 · string

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.

Response

200

application/json

Filesystem attach accepted and persisted; the returned sandbox already reflects the new file_systems entry

id · string · required

namespace · string · required

status · enum<string> · required

Available options: pending, running, snapshotting, suspending, suspended, terminated

created_at · integer<int64> · required

Milliseconds since Unix epoch.

resources · object · required

Show child attributes

timeout_secs · integer<int64> · required

allow_unauthenticated_access · boolean · required

Whether sandbox ingress may route requests without auth validation.

image · string

pending_reason · string | null

Present when status is pending.

outcome · string | null

Platform-specific termination outcome string returned for completed sandboxes.

termination_reason · string | null

Typed reason the sandbox terminated (e.g. FileSystemNotFound, FileSystemSnapshotNotFound, ImageNotFound). Present on failed terminations.

error_details · string | null

Human-readable detail accompanying termination_reason.

container_id · string | null

executor_id · string | null

ingress_endpoint · string | null

Canonical server-provided base for sandbox-specific ingress.

sandbox_url · string | null

Sandbox-specific management URL derived from ingress_endpoint.

pool_id · string | null

network_policy · null | object

Show child attributes

exposed_ports · integer<int32>[] | null

Additional routable ingress ports. When null, only the management port 9501 is routable.

Required range: 1 <= x <= 65535

template_id · string | null

name · string | null

file_systems · object[]

Filesystems currently mounted into the sandbox.

Show child attributes