Filesystem

Each Sailbox has a writable state disk. Runtime filesystem APIs operate on that writable disk; checkpoints preserve it across pause, sleep, resume, cloned children, and recovery. The examples below assume a running Sailbox sb.

Write files

Upload bytes or strings into the Sailbox filesystem. Paths must be absolute. Missing parent directories are created by default.

sb.fs.write("/workspace/input.txt", "hello\n")

await sb.fs.write("/workspace/input.txt", "hello\n");

use sail::WriteOptions;

sb.fs().write(
    "/workspace/input.txt",
    b"hello\n",
    WriteOptions {
        create_parents: true,
        mode: 0o644,
        ..Default::default()
    },
)
.await?;

Write several complete files in one call when startup code has many small inputs. write writes one file and can stream a file-like source in Python; write_files holds every file’s contents in memory.

sb.fs.write_files({
    "/workspace/a.txt": "first\n",
    "/workspace/b.txt": b"second\n",
})

await sb.fs.writeFiles({
  "/workspace/a.txt": "first\n",
  "/workspace/b.txt": Buffer.from("second\n"),
});

use sail::WriteOptions;

sb.fs()
    .write_files(
        [
            ("/workspace/a.txt", &b"first\n"[..]),
            ("/workspace/b.txt", &b"second\n"[..]),
        ],
        WriteOptions::default(),
    )
    .await?;

Each file is its own request, up to eight at a time, and every file gets the same options. A batch is not atomic across paths: the first failure stops the batch, files that already completed stay written, writes already in flight finish on their own, and the error names the file that failed. A path may appear only once. Contents are held in memory; use the streaming API for a large source. Pass a mode to set POSIX permission bits. When omitted, writes default to 0o644.

sb.fs.write("/workspace/private.txt", "secret\n", mode=0o600)

await sb.fs.write("/workspace/private.txt", "secret\n", { mode: 0o600 });

use sail::WriteOptions;

sb.fs().write(
    "/workspace/private.txt",
    b"secret\n",
    WriteOptions {
        create_parents: true,
        mode: 0o600,
        ..Default::default()
    },
)
.await?;

Disable parent creation if you want writes to fail when parent directories are missing:

sb.fs.write("/workspace/data/input.txt", "hello\n", create_parents=False)

await sb.fs.write("/workspace/data/input.txt", "hello\n", {
  createParents: false,
});

use sail::WriteOptions;

sb.fs().write(
    "/workspace/data/input.txt",
    b"hello\n",
    WriteOptions {
        create_parents: false,
        mode: 0o644,
        ..Default::default()
    },
)
.await?;

Read files

Fetch a regular file back as bytes:

data = sb.fs.read("/workspace/input.txt")
print(data.decode())

const data = await sb.fs.read("/workspace/input.txt");
console.log(data.toString());

let data = sb.fs().read("/workspace/input.txt").await?;
println!("{}", String::from_utf8_lossy(&data));

Whole-file reads buffer the full file in memory. For larger files, stream chunks instead:

with open("output.bin", "wb") as out:
    for chunk in sb.fs.read_stream("/workspace/output.bin"):
        out.write(chunk)

import { createWriteStream } from "node:fs";
import { pipeline } from "node:stream/promises";

await pipeline(
  (await sb.fs.readStream("/workspace/output.bin")).toReadable(),
  createWriteStream("output.bin"),
);

use std::io::Write;

let mut out = std::fs::File::create("output.bin")?;
let reader = sb.fs().read_stream("/workspace/output.bin").await?;
while let Some(chunk) = reader.next().await {
    out.write_all(&chunk?)?;
}

Work with directories

The fs namespace also covers directory work. mkdir creates a directory and any missing parents, ls lists a directory’s immediate entries as structured records (name, type, size, modified time, mode), exists checks a path, and remove deletes a file or directory tree:

sb.fs.mkdir("/workspace/results")
sb.fs.write("/workspace/results/input.txt", "hello\n")
for entry in sb.fs.ls("/workspace/results"):
    print(entry.name, entry.type, entry.size)
if sb.fs.exists("/workspace/results/input.txt"):
    sb.fs.remove("/workspace/results/input.txt")

await sb.fs.mkdir("/workspace/results");
await sb.fs.write("/workspace/results/input.txt", "hello\n");
for (const entry of await sb.fs.ls("/workspace/results")) {
  console.log(entry.name, entry.type, entry.size);
}
if (await sb.fs.exists("/workspace/results/input.txt")) {
  await sb.fs.remove("/workspace/results/input.txt");
}

sb.fs().mkdir("/workspace/results").await?;
sb.fs()
    .write("/workspace/results/input.txt", b"hello\n", Default::default())
    .await?;
for entry in sb.fs().ls("/workspace/results").await? {
    println!("{} {:?} {}", entry.name, entry.entry_type, entry.size);
}
if sb.fs().exists("/workspace/results/input.txt").await? {
    sb.fs().remove("/workspace/results/input.txt").await?;
}

Uploading and downloading directories

Every SDK provides directory transfer methods that move whole trees in one call. They ship one compressed archive instead of one call per file, so a tree of many small files transfers quickly:

# Upload a local directory's contents
sb.fs.upload_dir("./local_data", "/workspace/data")

# Download a Sailbox directory to local filesystem
sb.fs.download_dir("/workspace/results", "./local_results")

// Upload a local directory's contents
await sb.fs.uploadDir({
  localDir: "./local_data",
  guestDir: "/workspace/data",
});

// Download a Sailbox directory to local filesystem
await sb.fs.downloadDir({
  guestDir: "/workspace/results",
  localDir: "./local_results",
});

use std::path::Path;

// Upload a local directory's contents
sb.fs().upload_dir(Path::new("./local_data"), "/workspace/data").await?;

// Download a Sailbox directory to local filesystem
sb.fs().download_dir("/workspace/results", Path::new("./local_results")).await?;

Entries the transfer does not name are left in place, and a same-named file is replaced; uploaded files preserve their permission bits (the setuid, setgid, and sticky bits are cleared). Only download directories of ordinary files: system trees like /proc or /sys hold files that cannot be read as plain data, and downloading them fails. A file that is being written while the download runs is captured as it is at that moment, the way copying a live file would; download after writers finish for a consistent copy. On Windows, a directory that contains symbolic links cannot be downloaded, since Windows restricts creating them. The Sailbox image must provide tar and gzip, which the default images do.

Persist state with checkpoints

Runtime writes live on the Sailbox state disk. Checkpoint after important writes if you want recovery and future resumes to start from that point:

sb.fs.write("/workspace/config.json", '{"ready": true}\n')
sb.checkpoint()

await sb.fs.write("/workspace/config.json", '{"ready": true}\n');
await sb.checkpoint();

use sail::CheckpointOptions;

use sail::WriteOptions;

sb.fs().write(
    "/workspace/config.json",
    b"{\"ready\": true}\n",
    WriteOptions {
        create_parents: true,
        mode: 0o644,
        ..Default::default()
    },
)
.await?;
sb.checkpoint(CheckpointOptions::default()).await?;

See Lifecycle for checkpoint, start-from-checkpoint, pause, sleep, and resume behavior.

Runtime files vs image files

Use runtime filesystem APIs for inputs, outputs, logs, generated artifacts, and data that changes per Sailbox. Use Images for packages, source files, and static assets that should be present before the VM boots.

Getting started

Inference

Sailboxes

Guides

Voyages

Security & compliance

Write files

Read files

Work with directories

Uploading and downloading directories

Persist state with checkpoints

Runtime files vs image files

​Write files

​Read files

​Work with directories

​Uploading and downloading directories

​Persist state with checkpoints

​Runtime files vs image files

Write files

Read files

Work with directories

Uploading and downloading directories

Persist state with checkpoints

Runtime files vs image files