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.
  • If the mount later cannot converge — including a filesystem that does not exist — 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) before attaching.
  • Tensorlake returns 400 Bad Request when the sandbox runs on an executor fleet without filesystem 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.

Response

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