Skip to main content
Read, write, list, and manipulate files inside a running sandbox. Obtained via sb.fs(). Every op dispatches through the same host-guest channel as command execution, so there is no SSH and no network involved. Path-style helpers are the usual choice; handle-style helpers are available for callers that need POSIX-like file descriptor reuse. For bulk file movement, prefer a volume that gives the guest direct filesystem access. See Filesystem for conceptual usage.

Typical flow

sb.fs() is synchronous and just borrows the sandbox’s backend and name; the work happens on the awaited methods below, every one of which is async.

Read operations

fs.read()

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()

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()

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()

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()

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

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.

fs.open_file()

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

fs.open_dir()

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

fs.close_handle()

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

fs.read_handle()

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

fs.read_handle_stream()

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()

Write bytes to an open file handle at offset.

fs.write_handle_stream()

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()

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

fs.read_dir()

Compatibility alias for read_dir_handle().

fs.stat_handle()

Return metadata for an open file or directory handle.

fs.fstat()

Unix-style compatibility alias for stat_handle().

fs.set_stat_handle()

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

fs.fset_stat()

Unix-style compatibility alias for set_stat_handle().

Directory operations

fs.list()

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()

Create a directory, including any missing parent directories.

Parameters

path&str
Absolute directory path inside the guest.

fs.remove_dir()

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()

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()

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

Parameters

path&str
Absolute file path inside the guest.

fs.copy()

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()

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()

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

File metadata.

fs.stat_with_follow()

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()

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.
Attributes to change; unset fields are left untouched.
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.
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()

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()

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()

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()

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.

Types

SandboxFsOps

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, SandboxFsOps<'a>). Every method dispatches through the same host-guest channel as command execution: core.fs.* agent messages over the relay socket locally, or the agent WebSocket route on cloud. Handle-based helpers (stat_handle and friends) require the live local agent client and return Unsupported on cloud. All operations are listed in the sections above. with_backend(backend, name) is a public constructor for FFI shims that re-assemble a SandboxFsOps per call; most callers obtain one via sb.fs().

FsEntry

Returned by list()

Metadata for a single entry returned from a directory listing.

FsEntryKind

Used by FsEntry.kind · FsMetadata.kind

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

FsMetadata

Returned by stat() · stat_with_follow()

Detailed metadata for a file or directory.

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.

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.

FsReadStream

Returned by read_stream() · read_handle_stream()

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

FsWriteSink

Returned by write_stream() · write_handle_stream()

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

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().