--- title: Filesystem description: Rust SDK - Filesystem API reference --- Read and write files inside a running sandbox. See [Filesystem](/sandboxes/filesystem) for usage examples. ## SandboxFsOps #### fs.read() ```rust async fn read(&self, path: &str) -> MicrosandboxResult ``` ```rust 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() ```rust async fn read_to_string(&self, path: &str) -> MicrosandboxResult ``` ```rust 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() ```rust async fn read_stream(&self, path: &str) -> MicrosandboxResult ``` ```rust 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

Reader that yields chunks until the file is exhausted.

Write operations

#### fs.write() ```rust async fn write(&self, path: &str, data: impl AsRef<[u8]>) -> MicrosandboxResult<()> ``` ```rust 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() ```rust async fn write_stream(&self, path: &str) -> MicrosandboxResult ``` ```rust 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()`](#fswritesink) to flush and finalize. The file is created if missing and truncated if it exists.

Parameters

path&str
Absolute path inside the guest.

Returns

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. ```rust 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() ```rust async fn open_file(&self, path: &str, options: FsOpenOptions) -> MicrosandboxResult ``` Open a file inside the guest and return an agentd-side handle. Configure read/write/create/truncate behavior with [`FsOpenOptions`](#fsopenoptions). #### fs.open_dir() ```rust async fn open_dir(&self, path: &str) -> MicrosandboxResult ``` Open a directory inside the guest and return an agentd-side handle that can be consumed with [`read_dir_handle()`](#fs-read_dir_handle). #### fs.close_handle() ```rust 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() ```rust async fn read_handle(&self, handle: FsHandle, offset: u64, len: Option) -> MicrosandboxResult ``` Read from an open file handle at `offset`. Passing `None` for `len` reads through EOF. #### fs.read_handle_stream() ```rust async fn read_handle_stream(&self, handle: FsHandle, offset: u64, len: Option) -> MicrosandboxResult ``` Stream bytes from an open file handle. Use this for large reads while preserving the same open-handle semantics as [`read_handle()`](#fs-read_handle). #### fs.write_handle() ```rust 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() ```rust async fn write_handle_stream(&self, handle: FsHandle, offset: u64, len: Option) -> MicrosandboxResult ``` Stream writes to an open file handle at `offset`. Call [`FsWriteSink::close()`](#fswritesink) to send EOF and wait for the guest to confirm the write. #### fs.read_dir_handle() ```rust async fn read_dir_handle(&self, handle: FsHandle, limit: Option) -> MicrosandboxResult> ``` Read the next batch of entries from an open directory handle. `limit` caps the batch size when set. #### fs.read_dir() ```rust async fn read_dir(&self, handle: FsHandle, limit: Option) -> MicrosandboxResult> ``` Compatibility alias for [`read_dir_handle()`](#fs-read_dir_handle). #### fs.stat_handle() ```rust async fn stat_handle(&self, handle: FsHandle) -> MicrosandboxResult ``` Return metadata for an open file or directory handle. #### fs.fstat() ```rust async fn fstat(&self, handle: FsHandle) -> MicrosandboxResult ``` Unix-style compatibility alias for [`stat_handle()`](#fs-stat_handle). #### fs.set_stat_handle() ```rust async fn set_stat_handle(&self, handle: FsHandle, attrs: FsSetAttrs) -> MicrosandboxResult<()> ``` Update metadata for an open file handle. Only the fields set on [`FsSetAttrs`](#fssetattrs) are changed. #### fs.fset_stat() ```rust async fn fset_stat(&self, handle: FsHandle, attrs: FsSetAttrs) -> MicrosandboxResult<()> ``` Unix-style compatibility alias for [`set_stat_handle()`](#fs-set_stat_handle).

Directory operations

#### fs.list() ```rust async fn list(&self, path: &str) -> MicrosandboxResult> ``` ```rust 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

Directory entries.
#### fs.mkdir() ```rust async fn mkdir(&self, path: &str) -> MicrosandboxResult<()> ``` ```rust 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() ```rust async fn remove_dir(&self, path: &str) -> MicrosandboxResult<()> ``` ```rust sb.fs().remove_dir("/app/data/cache").await?; ``` Remove a directory and everything under it, recursively. For a single file use [`remove()`](#fs-remove).

Parameters

path&str
Absolute directory path inside the guest.
#### fs.remove_empty_dir() ```rust async fn remove_empty_dir(&self, path: &str) -> MicrosandboxResult<()> ``` ```rust sb.fs().remove_empty_dir("/app/data/empty").await?; ``` Remove an empty directory. Unlike [`remove_dir()`](#fs-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() ```rust async fn remove(&self, path: &str) -> MicrosandboxResult<()> ``` ```rust sb.fs().remove("/tmp/hello.txt").await?; ``` Delete a single file. Use [`remove_dir()`](#fs-remove_dir) for directories.

Parameters

path&str
Absolute file path inside the guest.
#### fs.copy() ```rust async fn copy(&self, from: &str, to: &str) -> MicrosandboxResult<()> ``` ```rust 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() ```rust async fn rename(&self, from: &str, to: &str) -> MicrosandboxResult<()> ``` ```rust 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() ```rust async fn stat(&self, path: &str) -> MicrosandboxResult ``` ```rust 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()`](#fs-stat_with_follow) to control that.

Parameters

path&str
Absolute path inside the guest.

Returns

File metadata.
#### fs.stat_with_follow() ```rust async fn stat_with_follow(&self, path: &str, follow_symlink: bool) -> MicrosandboxResult ``` ```rust 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

File metadata.
#### fs.set_stat() ```rust async fn set_stat(&self, path: &str, follow_symlink: bool, attrs: FsSetAttrs) -> MicrosandboxResult<()> ``` ```rust 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`](#fssetattrs) are applied.

Parameters

path&str
Absolute path inside the guest.
follow_symlinkbool
When false, target the symlink itself instead of its target.
Attributes to change; unset fields are left untouched.
#### fs.read_link() ```rust async fn read_link(&self, path: &str) -> MicrosandboxResult ``` ```rust 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() ```rust async fn symlink(&self, target: &str, link_path: &str) -> MicrosandboxResult<()> ``` ```rust 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() ```rust async fn real_path(&self, path: &str) -> MicrosandboxResult ``` ```rust 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() ```rust async fn exists(&self, path: &str) -> MicrosandboxResult ``` ```rust 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() ```rust async fn copy_from_host(&self, host_path: impl AsRef, guest_path: &str) -> MicrosandboxResult<()> ``` ```rust 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](/sdk/rust/volumes) instead.

Parameters

host_pathimpl AsRef<Path>
Path on the host filesystem.
guest_path&str
Destination path inside the sandbox.
#### fs.copy_to_host() ```rust async fn copy_to_host(&self, guest_path: &str, host_path: impl AsRef) -> MicrosandboxResult<()> ``` ```rust 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()`](#fs-read_stream) or [`read_handle_stream()`](#fs-read_handle_stream). #### stream.recv() ```rust recv() ``` Receive the next chunk; `None` once the file is fully read. Errors if the guest reports a failure. #### stream.collect() ```rust 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()`](#fs-write_stream) or [`write_handle_stream()`](#fs-write_handle_stream). #### sink.write() ```rust write() ``` Write a chunk of data. #### sink.close() ```rust 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`](#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>` | Last access time | | modified | `Option>` | 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`](#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>` | Last access time | | modified | `Option>` | Last modification time | | created | `Option>` | Creation time (not populated by guest stat, currently always `None`) | ### FsOpenOptions

Used by open_file()

Options accepted by [`open_file()`](#fs-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` | 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` | Unix permission bits | | uid | `Option` | Owner user ID | | gid | `Option` | Owner group ID | | size | `Option` | File size (truncate or extend) | | atime | `Option` | Access time as Unix timestamp seconds | | mtime | `Option` | 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()`](#fs-close_handle). ```rust pub type FsHandle = u64; ```