Filesystem - microsandbox

Read, write, and manage files inside a running sandbox. Operations go through the same host-guest channel as command execution: no SSH, no network. See Filesystem for usage examples. For bulk file movement, prefer a volume.

Typical flow

from microsandbox import Sandbox

async with await Sandbox.create("api", image="python") as sb:
    fs = sb.fs                                     # 1. grab the handle

    await fs.mkdir("/app")                         # 2. set up
    await fs.write("/app/config.json", b'{"ok": true}')

    data = await fs.read_text("/app/config.json")  # 3. read it back
    print(data)

The handle is reached through the sb.fs property on a running Sandbox. All methods are coroutines, so await each call.

Methods

fs.read()

async def read(path: str) -> bytes

Example

raw = await sb.fs.read("/app/data.bin")
print(len(raw))

Read the entire contents of a file as raw bytes.

Parameters

pathstr

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

Returns

bytes

File contents as raw bytes.

fs.read_text()

async def read_text(path: str) -> str

Example

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

Read the entire contents of a file and decode it as UTF-8.

Parameters

pathstr

Absolute path inside the guest.

Returns

str

File contents decoded as UTF-8.

fs.read_stream()

async def read_stream(path: str) -> FsReadStream

Example

stream = await sb.fs.read_stream("/app/large.log")
async for chunk in stream:
    process(chunk)

Open a streaming reader for a file. Use this for files too large to hold in memory. The returned FsReadStream is an async iterator that yields chunks of bytes, or call its collect() to gather everything into one bytes.

Parameters

pathstr

Absolute path inside the guest.

Returns

FsReadStream

Async iterator yielding chunks of file data.

fs.write()

async def write(path: str, data: bytes) -> None

Example

await sb.fs.write("/app/hello.txt", b"hi\n")

Write content to a file, creating it if it doesn’t exist and overwriting it if it does.

Parameters

pathstr

Absolute path inside the guest.

databytes

File content.

fs.write_stream()

async def write_stream(path: str) -> FsWriteSink

Example

async with await sb.fs.write_stream("/app/out.bin") as sink:
    await sink.write(b"chunk one")
    await sink.write(b"chunk two")

Open a streaming writer for a file. Use this for files too large to hold in memory. The returned FsWriteSink supports the async context manager protocol, so async with closes and finalizes the file automatically.

Parameters

pathstr

Absolute path inside the guest.

Returns

FsWriteSink

Async writer that accepts chunks of bytes.

fs.list()

async def list(path: str) -> list[FsEntry]

Example

for entry in await sb.fs.list("/app"):
    print(entry.kind, entry.path)

List the entries in a directory.

Parameters

pathstr

Absolute directory path inside the guest.

Returns

list[FsEntry]

Directory entries.

fs.mkdir()

async def mkdir(path: str) -> None

Example

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

Create a directory, including any missing parent directories.

Parameters

pathstr

Absolute directory path inside the guest.

fs.stat()

async def stat(path: str) -> FsMetadata

Example

meta = await sb.fs.stat("/app/config.json")
print(meta.kind, meta.size, meta.readonly)

Get detailed metadata for a file or directory.

Parameters

pathstr

Absolute path inside the guest.

Returns

FsMetadata

File metadata.

fs.exists()

async def exists(path: str) -> bool

Example

if not await sb.fs.exists("/app/config.json"):
    await sb.fs.write("/app/config.json", b"{}")

Check whether a path exists inside the sandbox.

Parameters

pathstr

Absolute path inside the guest.

Returns

bool

True if the path exists.

fs.remove_dir()

async def remove_dir(path: str) -> None

Example

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

Remove a directory and its contents recursively.

Parameters

pathstr

Absolute directory path inside the guest.

fs.copy()

async def copy(src: str, dst: str) -> None

Example

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

Copy a file within the sandbox.

Parameters

srcstr

Source path inside the guest.

dststr

Destination path inside the guest.

fs.rename()

async def rename(src: str, dst: str) -> None

Example

await sb.fs.rename("/app/tmp.txt", "/app/final.txt")

Rename or move a file or directory within the sandbox.

Parameters

srcstr

Current path inside the guest.

dststr

New path inside the guest.

fs.remove()

async def remove(path: str) -> None

Example

await sb.fs.remove("/app/config.bak.json")

Remove a file. Use remove_dir() for directories.

Parameters

pathstr

Absolute file path inside the guest.

fs.copy_from_host()

async def copy_from_host(host_path: str, guest_path: str) -> None

Example

await sb.fs.copy_from_host("./local/seed.csv", "/app/seed.csv")

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

Parameters

host_pathstr

Path on the host filesystem.

guest_pathstr

Destination path inside the sandbox.

fs.copy_to_host()

async def copy_to_host(guest_path: str, host_path: str) -> None

Example

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

Copy a file from the sandbox out to the host machine.

Parameters

guest_pathstr

Path inside the sandbox.

host_pathstr

Destination path on the host.

Types

FsEntry

Returned by list()

Metadata for a single directory entry, returned by list().

Property	Type	Description
path	`str`	Full path of the entry
kind	`str`	Entry type: `"file"`, `"directory"`, `"symlink"`, or `"other"` (see `FsEntryKind`)
size	`int`	File size in bytes
mode	`int`	Unix permission bits
modified	`float \| None`	Last-modified time, milliseconds since the Unix epoch

FsEntryKind

Describes FsEntry.kind · FsMetadata.kind

String enum (StrEnum) of filesystem entry types. The kind fields on FsEntry and FsMetadata carry these string values.

Value	Description
`"file"`	Regular file
`"directory"`	Directory
`"symlink"`	Symbolic link
`"other"`	Other entry type

FsMetadata

Returned by stat()

Detailed file metadata, returned by stat().

Property	Type	Description
kind	`str`	Entry type: `"file"`, `"directory"`, `"symlink"`, or `"other"` (see `FsEntryKind`)
size	`int`	File size in bytes
mode	`int`	Unix permission bits
readonly	`bool`	Whether the file is read-only
modified	`float \| None`	Last-modified time, milliseconds since the Unix epoch
created	`float \| None`	Creation time, milliseconds since the Unix epoch

FsReadStream

Returned by read_stream()

Async stream for reading a file in chunks. Obtained via read_stream(). Iterate it with async for chunk in stream:, or call collect() to gather everything at once.

Method / Protocol	Returns	Description
`__aiter__` / `__anext__`	`bytes`	Async iterator. Use `async for chunk in stream:`.
collect()	`bytes`	(async) Collect all remaining data into a single `bytes` object

FsWriteSink

Returned by write_stream()

Async writer for streaming data into a file. Obtained via write_stream(). Supports the async context manager protocol, so async with closes the sink on exit.

Method / Protocol	Returns	Description
write(data)	`None`	(async) Write a chunk of `bytes` to the file
close()	`None`	(async) Send EOF and finalize the file
`__aenter__` / `__aexit__`	`FsWriteSink`	(async) Use with `async with` for automatic close on exit

​Methods

​fs.read()

​fs.read_text()

​fs.read_stream()

​fs.write()

​fs.write_stream()

​fs.list()

​fs.mkdir()

​fs.stat()

​fs.exists()

​fs.remove_dir()

​fs.copy()

​fs.rename()

​fs.remove()

​fs.copy_from_host()

​fs.copy_to_host()

​Types

​FsEntry

​FsEntryKind

​FsMetadata

​FsReadStream

​FsWriteSink

Methods

fs.read()

fs.read_text()

fs.read_stream()

fs.write()

fs.write_stream()

fs.list()

fs.mkdir()

fs.stat()

fs.exists()

fs.remove_dir()

fs.copy()

fs.rename()

fs.remove()

fs.copy_from_host()

fs.copy_to_host()

Types

FsEntry

FsEntryKind

FsMetadata

FsReadStream

FsWriteSink