--- title: Filesystem description: Rust SDK - Filesystem API reference --- Read, write, list, and manipulate files inside a running sandbox. Obtained via [`sb.fs()`](/sdk/rust/sandbox#sb-fs). Every op dispatches through the same host-guest channel as command execution, so there is no SSH and no network involved. For bulk file movement, prefer a [volume](/sdk/rust/volumes) that gives the guest direct filesystem access. See [Filesystem](/sandboxes/filesystem) for conceptual usage.

Read3

fs.read()whole file as bytes fs.read_to_string()whole file as UTF-8 fs.read_stream()stream chunks in

Write2

fs.write()overwrite a file fs.write_stream()stream chunks out

Directories3

fs.list()children of a dir fs.mkdir()create dir + parents fs.remove_dir()remove dir recursively

Files3

fs.remove()delete a single file fs.copy()copy within sandbox fs.rename()rename / move

Metadata6

fs.stat()file metadata fs.stat_with_follow()stat, control symlinks fs.set_stat()update metadata fs.read_link()resolve a symlink fs.symlink()create a symlink fs.exists()does a path exist

Host transfer2

fs.copy_from_host()host file -> guest fs.copy_to_host()guest file -> host

Types

SandboxFs FsEntry FsEntryKind FsMetadata FsSetAttrs FsReadStream FsWriteSink FsHandle

Typical flow

```rust use microsandbox::Sandbox; let sb = Sandbox::builder("api").image("python").create().await?; let fs = sb.fs(); fs.write("/tmp/config.json", r#"{"debug": true}"#).await?; let text = fs.read_to_string("/tmp/config.json").await?; println!("{text}"); for entry in fs.list("/tmp").await? { println!("{} ({} bytes)", entry.path, entry.size); } ``` `sb.fs()` is synchronous and just borrows the sandbox's backend and name; the work happens on the `await`ed methods below, every one of which is `async`. ## Read operations --- #### fs.read()
instanceasync
```rust async fn read(&self, path: &str) -> MicrosandboxResult ``` 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.
```rust let bytes = sb.fs().read("/app/logo.png").await?; println!("{} bytes", bytes.len()); ``` --- #### fs.read_to_string()
instanceasync
```rust async fn read_to_string(&self, path: &str) -> MicrosandboxResult ``` 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.
```rust let text = sb.fs().read_to_string("/etc/hostname").await?; println!("{}", text.trim()); ``` --- #### fs.read_stream()
instanceasync
```rust async fn read_stream(&self, path: &str) -> MicrosandboxResult ``` 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.
```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"); ``` --- ## Write operations --- #### fs.write()
instanceasync
```rust async fn write(&self, path: &str, data: impl AsRef<[u8]>) -> MicrosandboxResult<()> ``` 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).
```rust sb.fs().write("/tmp/hello.txt", "hi there").await?; ``` --- #### fs.write_stream()
instanceasync
```rust async fn write_stream(&self, path: &str) -> MicrosandboxResult ``` 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.
```rust let sink = sb.fs().write_stream("/tmp/out.bin").await?; sink.write(&[0u8; 4096]).await?; sink.write(&[1u8; 4096]).await?; sink.close().await?; ``` --- ## Directory operations --- #### fs.list()
instanceasync
```rust async fn list(&self, path: &str) -> MicrosandboxResult> ``` 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.
```rust for entry in sb.fs().list("/app").await? { println!("{:?} {}", entry.kind, entry.path); } ``` --- #### fs.mkdir()
instanceasync
```rust async fn mkdir(&self, path: &str) -> MicrosandboxResult<()> ``` Create a directory, including any missing parent directories.

Parameters

path&str
Absolute directory path inside the guest.
```rust sb.fs().mkdir("/app/data/cache").await?; ``` --- #### fs.remove_dir()
instanceasync
```rust async fn remove_dir(&self, path: &str) -> MicrosandboxResult<()> ``` 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.
```rust sb.fs().remove_dir("/app/data/cache").await?; ``` --- ## File operations --- #### fs.remove()
instanceasync
```rust async fn remove(&self, path: &str) -> MicrosandboxResult<()> ``` Delete a single file. Use [`remove_dir()`](#fs-remove_dir) for directories.

Parameters

path&str
Absolute file path inside the guest.
```rust sb.fs().remove("/tmp/hello.txt").await?; ``` --- #### fs.copy()
instanceasync
```rust async fn copy(&self, from: &str, to: &str) -> MicrosandboxResult<()> ``` 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.
```rust sb.fs().copy("/app/config.json", "/app/config.bak.json").await?; ``` --- #### fs.rename()
instanceasync
```rust async fn rename(&self, from: &str, to: &str) -> MicrosandboxResult<()> ``` 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.
```rust sb.fs().rename("/tmp/draft.txt", "/tmp/final.txt").await?; ``` --- ## Metadata --- #### fs.stat()
instanceasync
```rust async fn stat(&self, path: &str) -> MicrosandboxResult ``` 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.
```rust let meta = sb.fs().stat("/app/config.json").await?; println!("{} bytes, mode {:o}", meta.size, meta.mode); ``` --- #### fs.stat_with_follow()
instanceasync
```rust async fn stat_with_follow(&self, path: &str, follow_symlink: bool) -> MicrosandboxResult ``` Get metadata, choosing whether to follow a final symlink. With `follow_symlink = false` you stat the link itself rather than its target. Local backend only; cloud returns `Unsupported`.

Parameters

path&str
Absolute path inside the guest.
follow_symlinkbool
When false, stat the symlink itself instead of its target.

Returns

File metadata.
```rust let link_meta = sb.fs().stat_with_follow("/app/current", false).await?; println!("{:?}", link_meta.kind); ``` --- #### fs.set_stat()
instanceasync
```rust async fn set_stat(&self, path: &str, follow_symlink: bool, attrs: FsSetAttrs) -> MicrosandboxResult<()> ``` 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. Local backend only; cloud returns `Unsupported`.

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.
```rust use microsandbox::sandbox::FsSetAttrs; sb.fs().set_stat("/app/run.sh", true, FsSetAttrs { mode: Some(0o755), ..Default::default() }).await?; ``` --- #### fs.read_link()
instanceasync
```rust async fn read_link(&self, path: &str) -> MicrosandboxResult ``` Read the target of a symbolic link, returning the literal target text. Local backend only; cloud returns `Unsupported`.

Parameters

path&str
Absolute path of the symlink inside the guest.

Returns

String
The link's target path.
```rust let target = sb.fs().read_link("/app/current").await?; println!("-> {target}"); ``` --- #### fs.symlink()
instanceasync
```rust async fn symlink(&self, target: &str, link_path: &str) -> MicrosandboxResult<()> ``` Create a symbolic link at `link_path` that points to `target`. Local backend only; cloud returns `Unsupported`.

Parameters

target&str
What the link points to (literal target text).
link_path&str
Absolute path of the symlink to create.
```rust sb.fs().symlink("/app/releases/v2", "/app/current").await?; ``` --- #### fs.exists()
instanceasync
```rust async fn exists(&self, path: &str) -> MicrosandboxResult ``` 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.
```rust if sb.fs().exists("/app/config.json").await? { println!("config present"); } ``` --- ## Host transfer --- #### fs.copy_from_host()
instanceasync
```rust async fn copy_from_host(&self, host_path: impl AsRef, guest_path: &str) -> MicrosandboxResult<()> ``` 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.
```rust sb.fs().copy_from_host("./local/model.bin", "/app/model.bin").await?; ``` --- #### fs.copy_to_host()
instanceasync
```rust async fn copy_to_host(&self, guest_path: &str, host_path: impl AsRef) -> MicrosandboxResult<()> ``` 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.
```rust sb.fs().copy_to_host("/app/out/report.pdf", "./report.pdf").await?; ``` --- ## Types ### SandboxFs
struct

Returned by sb.fs()

Filesystem operations handle for a running sandbox, borrowing the parent sandbox's backend and name (it is generic over a lifetime, `SandboxFs<'a>`). Every method dispatches through the same host-guest channel as command execution. Local routes to `core.fs.*` agent messages; cloud returns `Unsupported` per method until cloud guest-fs lands. All operations are listed in the sections above. `with_backend(backend, name)` is a public constructor for FFI shims that re-assemble a `SandboxFs` per call; most callers obtain one via [`sb.fs()`](/sdk/rust/sandbox#sb-fs). ### FsEntry
struct

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`) | | modified | `Option>` | Last modification time | ### FsEntryKind
enum

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
struct

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 | | readonly | `bool` | Whether the entry is read-only (no owner write bit) | | modified | `Option>` | Last modification time | | created | `Option>` | Creation time (not populated by guest stat, currently always `None`) | ### FsSetAttrs
struct

Used by set_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 | ### FsReadStream
struct

Returned by read_stream()

Streaming reader for file data from the sandbox. Obtained via [`read_stream()`](#fs-read_stream). | Method | Signature | Description | |--------|-----------|-------------| | recv() | `recv(&mut self) -> MicrosandboxResult>` | Receive the next chunk; `None` once the file is fully read. Errors if the guest reports a failure. | | collect() | `collect(self) -> MicrosandboxResult` | Consume the stream and collect all remaining chunks into a single buffer. | ### FsWriteSink
struct

Returned by write_stream()

Streaming writer for file data to the sandbox. Obtained via [`write_stream()`](#fs-write_stream). | Method | Signature | Description | |--------|-----------|-------------| | write() | `write(&self, data: impl AsRef<[u8]>) -> MicrosandboxResult<()>` | Write a chunk of data. | | close() | `close(self) -> MicrosandboxResult<()>` | Send EOF and wait for confirmation. Must be called to finalize the write; errors if the guest reports a write failure. | ### FsHandle
type
Type alias for an agentd-side filesystem handle. Internal plumbing: no public method takes or returns it, and the streaming types hold one only behind their own state. ```rust pub type FsHandle = u64; ```