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: None,
    },
)
.await?;

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: Some(0o600),
    },
)
.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: None,
    },
)
.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?;
}

Archives and shell-native workflows still go through exec(). For many small files, create an archive locally, upload it, and unpack it inside the Sailbox:

sb.fs.write("/workspace/project.tar.gz", open("project.tar.gz", "rb"))
sb.exec("mkdir -p /workspace/project && tar -xzf /workspace/project.tar.gz -C /workspace/project").wait()

import { readFileSync } from "node:fs";

await sb.fs.write("/workspace/project.tar.gz", readFileSync("project.tar.gz"));
const untar = await sb.exec(
  "mkdir -p /workspace/project && tar -xzf /workspace/project.tar.gz -C /workspace/project",
);
await untar.wait();

use sail::{ExecOptions, WriteOptions};

let bytes = std::fs::read("project.tar.gz")?;
sb.fs().write(
    "/workspace/project.tar.gz",
    &bytes,
    WriteOptions {
        create_parents: true,
        mode: None,
    },
)
.await?;
let untar = sb.exec(vec![
        "sh".to_string(),
        "-lc".to_string(),
        "mkdir -p /workspace/project && tar -xzf /workspace/project.tar.gz -C /workspace/project".to_string(),
    ],
    ExecOptions::default(),
)
.await?;
untar.wait().await?;

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: None,
    },
)
.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

Guides

Sailbox

Voyages

Write files

Read files

Work with directories

Persist state with checkpoints

Runtime files vs image files

​Write files

​Read files

​Work with directories

​Persist state with checkpoints

​Runtime files vs image files

Write files

Read files

Work with directories

Persist state with checkpoints

Runtime files vs image files