Filesystem - microsandbox

Read and write files inside a running sandbox. See Filesystem for usage examples.

SandboxFsOps

fs.read()

async fn read(&self, path: &str) -> MicrosandboxResult<Bytes>

Example

let bytes = sb.fs().read("/app/logo.png").await?;
println!("{} bytes", bytes.len());

Read an entire file from the guest filesystem into memory as raw bytes.

Parameters

path&str

Absolute path inside the guest, e.g. “/app/config.json”.

Returns

Bytes

File contents as raw bytes.

fs.read_to_string()

async fn read_to_string(&self, path: &str) -> MicrosandboxResult<String>

Example

let text = sb.fs().read_to_string("/etc/hostname").await?;
println!("{}", text.trim());

Read an entire file and decode it as UTF-8. Errors if the contents are not valid UTF-8.

Parameters

path&str

Absolute path inside the guest.

Returns

String

File contents as a UTF-8 string.

fs.read_stream()

async fn read_stream(&self, path: &str) -> MicrosandboxResult<FsReadStream>

Example

let mut stream = sb.fs().read_stream("/var/log/big.log").await?;
let mut total = 0;
while let Some(chunk) = stream.recv().await? {
    total += chunk.len();
}
println!("read {total} bytes");

Open a streaming reader that yields chunks of file data as they arrive. Use this for files too large to hold in memory, or to process data incrementally.

Parameters

path&str

Absolute path inside the guest.

Returns

FsReadStream

Reader that yields chunks until the file is exhausted.

Write operations

fs.write()

async fn write(&self, path: &str, data: impl AsRef<[u8]>) -> MicrosandboxResult<()>

Example

sb.fs().write("/tmp/hello.txt", "hi there").await?;

Write data to a file in the guest, creating it if it doesn’t exist and truncating it if it does. Parent directories must already exist.

Parameters

path&str

Absolute path inside the guest.

dataimpl AsRef<[u8]>

File content (bytes or a string).

fs.write_stream()

async fn write_stream(&self, path: &str) -> MicrosandboxResult<FsWriteSink>

Example

let sink = sb.fs().write_stream("/tmp/out.bin").await?;
sink.write(&[0u8; 4096]).await?;
sink.write(&[1u8; 4096]).await?;
sink.close().await?;

Open a streaming writer for large files. Write chunks incrementally, then call FsWriteSink::close() to flush and finalize. The file is created if missing and truncated if it exists.

Parameters

path&str

Absolute path inside the guest.

Returns

FsWriteSink

Writer for sending chunks; must be closed to finalize.

Handle operations

Handle operations expose agentd-side file and directory handles. Use them when you need repeated reads/writes against the same open file, directory iteration state, or handle-based metadata updates. They require Sandbox::fs() on a live local sandbox because agentd scopes handles to the relay client; SandboxFsOps::with_backend() can run path-style methods but returns Unsupported for handle methods.

Example

use microsandbox::sandbox::FsOpenOptions;

let fs = sb.fs();
let handle = fs.open_file("/tmp/data.txt", FsOpenOptions {
    read: true,
    write: true,
    create: true,
    ..Default::default()
}).await?;

fs.write_handle(handle, 0, "hello").await?;
let bytes = fs.read_handle(handle, 0, None).await?;
fs.close_handle(handle).await?;

fs.open_file()

async fn open_file(&self, path: &str, options: FsOpenOptions) -> MicrosandboxResult<FsHandle>

Open a file inside the guest and return an agentd-side handle. Configure read/write/create/truncate behavior with FsOpenOptions.

fs.open_dir()

async fn open_dir(&self, path: &str) -> MicrosandboxResult<FsHandle>

Open a directory inside the guest and return an agentd-side handle that can be consumed with read_dir_handle().

fs.close_handle()

async fn close_handle(&self, handle: FsHandle) -> MicrosandboxResult<()>

Close an open file or directory handle. Always close handles you opened directly once you are done with them.

fs.read_handle()

async fn read_handle(&self, handle: FsHandle, offset: u64, len: Option<u64>) -> MicrosandboxResult<Bytes>

Read from an open file handle at offset. Passing None for len reads through EOF.

fs.read_handle_stream()

async fn read_handle_stream(&self, handle: FsHandle, offset: u64, len: Option<u64>) -> MicrosandboxResult<FsReadStream>

Stream bytes from an open file handle. Use this for large reads while preserving the same open-handle semantics as read_handle().

fs.write_handle()

async fn write_handle(&self, handle: FsHandle, offset: u64, data: impl AsRef<[u8]>) -> MicrosandboxResult<()>

Write bytes to an open file handle at offset.

fs.write_handle_stream()

async fn write_handle_stream(&self, handle: FsHandle, offset: u64, len: Option<u64>) -> MicrosandboxResult<FsWriteSink>

Stream writes to an open file handle at offset. Call FsWriteSink::close() to send EOF and wait for the guest to confirm the write.

fs.read_dir_handle()

async fn read_dir_handle(&self, handle: FsHandle, limit: Option<u32>) -> MicrosandboxResult<Vec<FsEntry>>

Read the next batch of entries from an open directory handle. limit caps the batch size when set.

fs.read_dir()

async fn read_dir(&self, handle: FsHandle, limit: Option<u32>) -> MicrosandboxResult<Vec<FsEntry>>

Compatibility alias for read_dir_handle().

fs.stat_handle()

async fn stat_handle(&self, handle: FsHandle) -> MicrosandboxResult<FsMetadata>

Return metadata for an open file or directory handle.

fs.fstat()

async fn fstat(&self, handle: FsHandle) -> MicrosandboxResult<FsMetadata>

Unix-style compatibility alias for stat_handle().

fs.set_stat_handle()

async fn set_stat_handle(&self, handle: FsHandle, attrs: FsSetAttrs) -> MicrosandboxResult<()>

Update metadata for an open file handle. Only the fields set on FsSetAttrs are changed.

fs.fset_stat()

async fn fset_stat(&self, handle: FsHandle, attrs: FsSetAttrs) -> MicrosandboxResult<()>

Unix-style compatibility alias for set_stat_handle().

Directory operations

fs.list()

async fn list(&self, path: &str) -> MicrosandboxResult<Vec<FsEntry>>

Example

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

List the immediate children of a directory (non-recursive). Each entry carries its path, kind, size, mode, and modification time.

Parameters

path&str

Absolute directory path inside the guest.

Returns

Vec<FsEntry>

Directory entries.

fs.mkdir()

async fn mkdir(&self, path: &str) -> MicrosandboxResult<()>

Example

sb.fs().mkdir("/app/data/cache").await?;

Create a directory, including any missing parent directories.

Parameters

path&str

Absolute directory path inside the guest.

fs.remove_dir()

async fn remove_dir(&self, path: &str) -> MicrosandboxResult<()>

Example

sb.fs().remove_dir("/app/data/cache").await?;

Remove a directory and everything under it, recursively. For a single file use remove().

Parameters

path&str

Absolute directory path inside the guest.

fs.remove_empty_dir()

async fn remove_empty_dir(&self, path: &str) -> MicrosandboxResult<()>

Example

sb.fs().remove_empty_dir("/app/data/empty").await?;

Remove an empty directory. Unlike remove_dir(), this does not remove child entries and fails when the directory is not empty.

Parameters

path&str

Absolute directory path inside the guest.

File operations

fs.remove()

async fn remove(&self, path: &str) -> MicrosandboxResult<()>

Example

sb.fs().remove("/tmp/hello.txt").await?;

Delete a single file. Use remove_dir() for directories.

Parameters

path&str

Absolute file path inside the guest.

fs.copy()

async fn copy(&self, from: &str, to: &str) -> MicrosandboxResult<()>

Example

sb.fs().copy("/app/config.json", "/app/config.bak.json").await?;

Copy a file from one path to another within the sandbox.

Parameters

from&str

Source path inside the guest.

to&str

Destination path inside the guest.

fs.rename()

async fn rename(&self, from: &str, to: &str) -> MicrosandboxResult<()>

Example

sb.fs().rename("/tmp/draft.txt", "/tmp/final.txt").await?;

Rename or move a file or directory within the sandbox.

Parameters

from&str

Current path inside the guest.

to&str

New path inside the guest.

Metadata

fs.stat()

async fn stat(&self, path: &str) -> MicrosandboxResult<FsMetadata>

Example

let meta = sb.fs().stat("/app/config.json").await?;
println!("{} bytes, mode {:o}", meta.size, meta.mode);

Get metadata for a file or directory: kind, size, mode, read-only flag, and timestamps. A final symlink is followed (equivalent to stat_with_follow(path, true)); use stat_with_follow() to control that.

Parameters

path&str

Absolute path inside the guest.

Returns

FsMetadata

File metadata.

fs.stat_with_follow()

async fn stat_with_follow(&self, path: &str, follow_symlink: bool) -> MicrosandboxResult<FsMetadata>

Example

let link_meta = sb.fs().stat_with_follow("/app/current", false).await?;
println!("{:?}", link_meta.kind);

Get metadata, choosing whether to follow a final symlink. With follow_symlink = false you stat the link itself rather than its target.

Parameters

path&str

Absolute path inside the guest.

follow_symlinkbool

When false, stat the symlink itself instead of its target.

Returns

FsMetadata

File metadata.

fs.set_stat()

async fn set_stat(&self, path: &str, follow_symlink: bool, attrs: FsSetAttrs) -> MicrosandboxResult<()>

Example

use microsandbox::sandbox::FsSetAttrs;

sb.fs().set_stat("/app/run.sh", true, FsSetAttrs {
    mode: Some(0o755),
    ..Default::default()
}).await?;

Update metadata on a file or directory: mode, owner uid/gid, size, and access/modification times. Only the fields you set on FsSetAttrs are applied.

Parameters

path&str

Absolute path inside the guest.

follow_symlinkbool

When false, target the symlink itself instead of its target.

attrsFsSetAttrs

Attributes to change; unset fields are left untouched.

fs.read_link()

async fn read_link(&self, path: &str) -> MicrosandboxResult<String>

Example

let target = sb.fs().read_link("/app/current").await?;
println!("-> {target}");

Read the target of a symbolic link, returning the literal target text.

Parameters

path&str

Absolute path of the symlink inside the guest.

Returns

String

The link’s target path.

fs.symlink()

async fn symlink(&self, target: &str, link_path: &str) -> MicrosandboxResult<()>

Example

sb.fs().symlink("/app/releases/v2", "/app/current").await?;

Create a symbolic link at link_path that points to target.

Parameters

target&str

What the link points to (literal target text).

link_path&str

Absolute path of the symlink to create.

fs.real_path()

async fn real_path(&self, path: &str) -> MicrosandboxResult<String>

Example

let canonical = sb.fs().real_path("/app/../app/config.json").await?;
println!("{canonical}");

Resolve a path to its canonical absolute path inside the guest.

Parameters

path&str

Path inside the guest.

Returns

String

Canonical absolute path.

fs.exists()

async fn exists(&self, path: &str) -> MicrosandboxResult<bool>

Example

if sb.fs().exists("/app/config.json").await? {
    println!("config present");
}

Check whether a file or directory exists at the given path in the guest. Implemented as a stat() probe: a successful stat yields true, a filesystem-op error yields false, and transport errors still propagate.

Parameters

path&str

Absolute path inside the guest.

Returns

bool

true if the path exists.

Host transfer

fs.copy_from_host()

async fn copy_from_host(&self, host_path: impl AsRef<Path>, guest_path: &str) -> MicrosandboxResult<()>

Example

sb.fs().copy_from_host("./local/model.bin", "/app/model.bin").await?;

Copy a file from the host machine into the sandbox, streaming it in chunks. For transferring many files, consider a bind-mounted volume instead.

Parameters

host_pathimpl AsRef<Path>

Path on the host filesystem.

guest_path&str

Destination path inside the sandbox.

fs.copy_to_host()

async fn copy_to_host(&self, guest_path: &str, host_path: impl AsRef<Path>) -> MicrosandboxResult<()>

Example

sb.fs().copy_to_host("/app/out/report.pdf", "./report.pdf").await?;

Copy a file from the sandbox to the host machine.

Parameters

guest_path&str

Path inside the sandbox.

host_pathimpl AsRef<Path>

Destination path on the host.

FsReadStream

Returned by read_stream() · read_handle_stream()

Streaming reader for file data from the sandbox. Obtained via read_stream() or read_handle_stream().

stream.recv()

recv()

Receive the next chunk; None once the file is fully read. Errors if the guest reports a failure.

stream.collect()

collect()

Consume the stream and collect all remaining chunks into a single buffer.

FsWriteSink

Returned by write_stream() · write_handle_stream()

Streaming writer for file data to the sandbox. Obtained via write_stream() or write_handle_stream().

sink.write()

write()

Write a chunk of data.

sink.close()

close()

Send EOF and wait for confirmation. Must be called to finalize the write; errors if the guest reports a write failure.

Types

FsEntry

Returned by list()

Metadata for a single entry returned from a directory listing.

Field	Type	Description
path	`String`	Path of the entry
kind	`FsEntryKind`	Kind of entry
size	`u64`	Size in bytes
mode	`u32`	Unix permission bits (e.g. `0o644`)
uid	`u32`	Owner user ID
gid	`u32`	Owner group ID
accessed	`Option<DateTime<Utc>>`	Last access time
modified	`Option<DateTime<Utc>>`	Last modification time

FsEntryKind

Used by FsEntry.kind · FsMetadata.kind

The kind of a filesystem entry. Derives Copy, PartialEq, and Eq.

Variant	Description
`File`	Regular file
`Directory`	Directory
`Symlink`	Symbolic link
`Other`	Other entry type (device, socket, etc.)

FsMetadata

Returned by stat() · stat_with_follow()

Detailed metadata for a file or directory.

Field	Type	Description
kind	`FsEntryKind`	Kind of entry
size	`u64`	Size in bytes
mode	`u32`	Unix permission bits
uid	`u32`	Owner user ID
gid	`u32`	Owner group ID
readonly	`bool`	Whether the entry is read-only (no owner write bit)
accessed	`Option<DateTime<Utc>>`	Last access time
modified	`Option<DateTime<Utc>>`	Last modification time
created	`Option<DateTime<Utc>>`	Creation time (not populated by guest stat, currently always `None`)

FsOpenOptions

Used by open_file()

Options accepted by open_file(). Re-exported from microsandbox_protocol::fs. Derives Default, so set only the flags you need.

Field	Type	Description
read	`bool`	Open for reading
write	`bool`	Open for writing
append	`bool`	Append writes to the end
create	`bool`	Create the file if it is missing
truncate	`bool`	Truncate the file after opening
create_new	`bool`	Create a new file and fail if it already exists
mode	`Option<u32>`	Permission bits to set on creation

FsSetAttrs

Used by set_stat() · set_stat_handle() · fset_stat()

Attributes accepted by set_stat(). Re-exported from microsandbox_protocol::fs. Derives Default, so set only the fields you want to change and spread the rest with ..Default::default(). Each field is Option: None leaves that attribute unchanged.

Field	Type	Description
mode	`Option<u32>`	Unix permission bits
uid	`Option<u32>`	Owner user ID
gid	`Option<u32>`	Owner group ID
size	`Option<u64>`	File size (truncate or extend)
atime	`Option<i64>`	Access time as Unix timestamp seconds
mtime	`Option<i64>`	Modification time as Unix timestamp seconds

FsHandle

Returned by open_file() · open_dir()

Type alias for an agentd-side filesystem handle. Handles are valid only for the live relay client that opened them; close directly opened handles with close_handle().

pub type FsHandle = u64;

​SandboxFsOps

​fs.read()

​fs.read_to_string()

​fs.read_stream()

​fs.write()

​fs.write_stream()

​fs.open_file()

​fs.open_dir()

​fs.close_handle()

​fs.read_handle()

​fs.read_handle_stream()

​fs.write_handle()

​fs.write_handle_stream()

​fs.read_dir_handle()

​fs.read_dir()

​fs.stat_handle()

​fs.fstat()

​fs.set_stat_handle()

​fs.fset_stat()

​fs.list()

​fs.mkdir()

​fs.remove_dir()

​fs.remove_empty_dir()

​fs.remove()

​fs.copy()

​fs.rename()

​fs.stat()

​fs.stat_with_follow()

​fs.set_stat()

​fs.read_link()

​fs.symlink()

​fs.real_path()

​fs.exists()

​fs.copy_from_host()

​fs.copy_to_host()

​FsReadStream

​stream.recv()

​stream.collect()

​FsWriteSink

​sink.write()

​sink.close()

​Types

​FsEntry

​FsEntryKind

​FsMetadata

​FsOpenOptions

​FsSetAttrs

​FsHandle

SandboxFsOps

fs.read()

fs.read_to_string()

fs.read_stream()

fs.write()

fs.write_stream()

fs.open_file()

fs.open_dir()

fs.close_handle()

fs.read_handle()

fs.read_handle_stream()

fs.write_handle()

fs.write_handle_stream()

fs.read_dir_handle()

fs.read_dir()

fs.stat_handle()

fs.fstat()

fs.set_stat_handle()

fs.fset_stat()

fs.list()

fs.mkdir()

fs.remove_dir()

fs.remove_empty_dir()

fs.remove()

fs.copy()

fs.rename()

fs.stat()

fs.stat_with_follow()

fs.set_stat()

fs.read_link()

fs.symlink()

fs.real_path()

fs.exists()

fs.copy_from_host()

fs.copy_to_host()

FsReadStream

stream.recv()

stream.collect()

FsWriteSink

sink.write()

sink.close()

Types

FsEntry

FsEntryKind

FsMetadata

FsOpenOptions

FsSetAttrs

FsHandle