Skip to main content
POST
Attach a filesystem
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

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

auto_resume
boolean
required

Whether proxy traffic may wake the sandbox while suspended. Defaults to true on creation. Explicit resume does not change this setting, and copies inherit it. Check status separately to determine whether the sandbox is currently suspended.

id
string
required
namespace
string
required
status
enum<string>
required
Available options:
pending,
running,
snapshotting,
suspending,
suspended,
terminated,
resume_failed
created_at
integer<int64>
required

Milliseconds since Unix epoch.

resources
object
required
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, no_capacity when a max_pending_secs bound ran out while waiting for a host, cancelled when a pending sandbox was deleted). Present on failed terminations.

error_details
string | null

Optional diagnosis for termination or a recoverable resume failure. An accepted explicit resume clears the previous diagnosis. Inspect status rather than classifying failure from this text.

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

Egress network policy currently applied to the sandbox. null when egress is unrestricted.

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.

snapshot_id
string | null

Retained checkpoint ID. A recoverable resume failure preserves the original checkpoint for an explicit retry.