Skip to main content
Each Sailbox has a writable state disk. Runtime filesystem APIs operate on that writable disk; checkpoints preserve it across pause, sleep, resume, fork, and recovery.

​
Write files

Use write() to upload bytes, strings, or file-like objects into the Sailbox filesystem. Paths must be absolute. Missing parent directories are created by default. 
sb.write("/workspace/input.txt", "hello\n")
Pass mode to set POSIX permission bits. When omitted, writes default to 0o644. 
sb.write("/workspace/private.txt", "secret\n", mode=0o600)
Set create_parents=False if you want writes to fail when parent directories are missing: 
sb.write("/workspace/data/input.txt", "hello\n", create_parents=False)

​
Read files

Use read() to fetch a regular file back as bytes: 
data = sb.read("/workspace/input.txt")
print(data.decode())
read() buffers the full file in memory. For larger files, use read_stream() to iterate over chunks: 
with open("output.bin", "wb") as out:
    for chunk in sb.read_stream("/workspace/output.bin"):
        out.write(chunk)

​
Work with directories

The filesystem API reads and writes regular files. Use exec() for directory operations, archives, and shell-native workflows: 
sb.exec("mkdir -p /workspace/results").wait()
sb.write("/workspace/results/input.txt", "hello\n")
result = sb.exec("find /workspace/results -maxdepth 1 -type f -print").wait()
print(result.stdout)
For many small files, create an archive locally, upload it, and unpack it inside the Sailbox: 
sb.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()

​
Persist state with checkpoints

Runtime writes live on the Sailbox state disk. Call checkpoint() after important writes if you want recovery and future resumes to start from that point: 
sb.write("/workspace/config.json", '{"ready": true}\n')
sb.checkpoint()
See Lifecycle for checkpoint, pause, sleep, resume, and fork 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.