Filesystem

Read, write, and stream files in a running Sailbox

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.

Python

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

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 loads every file’s contents into memory.

Python

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

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 remain written, and writes already in flight finish on their own. The error identifies 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.

Python

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

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

Python

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

Read files

Fetch a regular file back as bytes:

Python

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

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

Python

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

Share a file by URL

Mint a URL that serves one file over HTTPS with no API key. Anyone who holds it can fetch the file with a browser, curl, or a CDN:

Python

url = sb.fs.download_url("/workspace/render.png")

The URL authorizes reading that one file and nothing else on the Sailbox, and it serves whatever the file holds when it is fetched. A file the Sailbox replaces is served in its new form, and one it deletes answers 404. The URL expires an hour after it is minted, or after expires_in_seconds, up to seven days. Expiry stops new fetches only; the file stays where it is, and a copy already downloaded or cached is unaffected. An older Sailbox rejects the call until you upgrade it.

The file is served inline with a content type from its extension, so an <img> or <video> tag, or a fetch() from any page, can point straight at the URL. Pass attachment to serve it as a download instead:

Python

url = sb.fs.download_url(
    "/workspace/report.pdf", expires_in_seconds=600, attachment=True
)

Caching, ranges, and sleeping or paused Sailboxes

• Responses carry an ETag that changes whenever the file is written or replaced, and a Last-Modified time. By default a cache must check back before reusing a copy. It gets a 304 while the file is unchanged, so a file that changes now and then is safe to share.
• Do not rewrite a file in place while a download URL for it is live: a download can contain bytes from more than one version. Write the new version to a separate path and rename it into place, or give each version its own path. A download in progress when the file is replaced ends short of its Content-Length; fetching the URL again gets the new version.
• immutable marks the response cacheable for a year. Use it only for a path you never overwrite, such as a render written once under a unique name. Sail keeps no copy of the old version, so if the file is rewritten anyway, caches keep serving what they hold while a fresh client gets the new bytes.
• HEAD returns the headers without reading the file. Byte ranges are supported, so a browser can seek in a video and an interrupted download can resume. Send If-Range with the ETag so a resume starts over when the file has changed in between.
• A fetch wakes a sleeping Sailbox before the first byte. A paused Sailbox answers 409 until it is resumed, and a terminated one answers 404.

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:

Python

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")

Uploading and downloading directories

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

Python

# 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")

Existing entries that the transfer does not include 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 contain 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 are stored on the Sailbox state disk. Checkpoint after important writes if you want recovery and future resumes to start from that point:

Python

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

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.