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

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

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

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

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

Read a file

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

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

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

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

List a directory

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

const entries = await sb.fs().list("/app");
for (const entry of entries) {
    console.log(`${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.

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

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

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.

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

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

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.

⌘I