Filesystem

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

SandboxFsOps

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.

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.

stream.aiter()

__aiter__()

Async iterator. Use async for chunk in stream:.

Returns

bytes

stream.anext()

__anext__()

Async iterator. Use async for chunk in stream:.

Returns

bytes

stream.collect()

collect()

(async) Collect all remaining data into a single bytes object

Returns

bytes

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.

sink.write()

write(data)

(async) Write a chunk of bytes to the file

sink.close()

close()

(async) Send EOF and finalize the file

sink.aenter()

__aenter__()

(async) Use with async with for automatic close on exit

Returns

FsWriteSink

sink.aexit()

__aexit__()

(async) Use with async with for automatic close on exit

Returns

FsWriteSink

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	`FsEntryKind`	Entry type
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

Filesystem entry type returned by FsEntry.kind and FsMetadata.kind.

Member	Value	Description
`FsEntryKind.FILE`	`"file"`	Regular file
`FsEntryKind.DIRECTORY`	`"directory"`	Directory
`FsEntryKind.SYMLINK`	`"symlink"`	Symbolic link
`FsEntryKind.OTHER`	`"other"`	Other entry type

from microsandbox import FsEntryKind

files = [entry for entry in await sb.fs.list("/app") if entry.kind is FsEntryKind.FILE]

FsMetadata

Returned by stat()

Detailed file metadata, returned by stat().

Property	Type	Description
kind	`FsEntryKind`	Entry type
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

Getting Started

SDKs

CLI

SandboxFsOps

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

FsReadStream

stream.aiter()

stream.anext()

stream.collect()

FsWriteSink

sink.write()

sink.close()

sink.aenter()

sink.aexit()

Types

FsEntry

FsEntryKind

FsMetadata

​SandboxFsOps

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

​FsReadStream

​stream.aiter()

​stream.anext()

​stream.collect()

​FsWriteSink

​sink.write()

​sink.close()

​sink.aenter()

​sink.aexit()

​Types

​FsEntry

​FsEntryKind

​FsMetadata

SandboxFsOps

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

FsReadStream

stream.aiter()

stream.anext()

stream.collect()

FsWriteSink

sink.write()

sink.close()

sink.aenter()

sink.aexit()

Types

FsEntry

FsEntryKind

FsMetadata