Filesystem - microsandbox

The filesystem API lets you read, write, and manage files inside a sandbox without mounting volumes or SSH. It uses the same channel as command execution, so it doesn’t touch the sandbox’s network. Handy for pushing generated code into a sandbox, pulling back results, or inspecting logs without having to pre-mount a shared directory.

Write a file

await sb.fs().write("/app/config.json", '{"debug": true}');

sb.fs().write("/app/config.json", r#"{"debug": true}"#).await?;

await sb.fs.write("/app/config.json", b'{"debug": true}')

err := sb.FS().WriteString(ctx, "/app/config.json", `{"debug": true}`)

Read a file

const content = await sb.fs().readToString("/app/config.json");

let content = sb.fs().read_to_string("/app/config.json").await?;

content = await sb.fs.read_text("/app/config.json")

content, err := sb.FS().ReadString(ctx, "/app/config.json")

List a directory

const entries = await sb.fs().list("/app");
for (const entry of entries) {
    console.log(`${entry.path}: ${entry.kind}`);
}

let entries = sb.fs().list("/app").await?;
for entry in entries {
    println!("{}: {:?}", entry.path, entry.kind);
}

entries = await sb.fs.list("/app")
for entry in entries:
    print(f"{entry.path}: {entry.kind}")

entries, err := sb.FS().List(ctx, "/app")
for _, entry := range entries {
    fmt.Printf("%s: %s\n", entry.Path, entry.Kind)
}

Stream large files

For files too large to fit in memory, use streaming. Data is transferred in chunks of approximately 3 MiB each.

const stream = await sb.fs().readStream("/app/data.bin");
for await (const chunk of stream) {
    processChunk(chunk); // chunk is a Uint8Array
}

let mut stream = sb.fs().read_stream("/app/data.bin").await?;
while let Some(chunk) = stream.recv().await? {
    process(&chunk);
}

stream = await sb.fs.read_stream("/app/data.bin")
async for chunk in stream:
    process(chunk)

stream, err := sb.FS().ReadStream(ctx, "/app/data.bin")
for {
    chunk, err := stream.Recv(ctx)
    if err != nil {
        return err
    }
    if chunk == nil {
        break
    }
    process(chunk)
}

Copy from host

Copy a file from the host machine into the sandbox in a single call.

await sb.fs().copyFromHost("./local-file.txt", "/app/remote-file.txt");

sb.fs().copy_from_host("./local-file.txt", "/app/remote-file.txt").await?;

await sb.fs.copy_from_host("./local-file.txt", "/app/remote-file.txt")

err := sb.FS().CopyFromHost(ctx, "./local-file.txt", "/app/remote-file.txt")

If you need to transfer many files at once, consider using a bind-mounted volume instead. Volumes give the guest direct filesystem access, whereas the filesystem API transfers each file individually. For bulk operations, volumes are significantly faster.

Reference

For exact filesystem APIs, see TypeScript, Rust, Python, or Go. For host-to-sandbox copies, see msb copy.

⌘I