> ## Documentation Index
> Fetch the complete documentation index at: https://docs.microsandbox.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Filesystem

> Python SDK - Filesystem API reference

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](/sandboxes/filesystem) for usage examples. For bulk file movement, prefer a [volume](/sandboxes/volumes).

<p className="msb-label" id="typical-flow">Typical flow</p>

```python theme={null}
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`](/sdk/python/sandbox). All methods are coroutines, so `await` each call.

## Methods

#### <span className="msb-recv">fs.</span><span className="msb-hn">read()</span>

```python theme={null}
async def read(path: str) -> bytes
```

<Accordion title="Example">
  ```python theme={null}
  raw = await sb.fs.read("/app/data.bin")
  print(len(raw))
  ```
</Accordion>

Read the entire contents of a file as raw bytes.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>path</code><span className="msb-type">str</span></div>
    <div className="msb-param-desc">Absolute path inside the guest, e.g. <code>"/app/config.json"</code>.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">bytes</span></div>
    <div className="msb-param-desc">File contents as raw bytes.</div>
  </div>
</div>

#### <span className="msb-recv">fs.</span><span className="msb-hn">read\_text()</span>

```python theme={null}
async def read_text(path: str) -> str
```

<Accordion title="Example">
  ```python theme={null}
  config = await sb.fs.read_text("/app/config.json")
  ```
</Accordion>

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

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>path</code><span className="msb-type">str</span></div>
    <div className="msb-param-desc">Absolute path inside the guest.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">str</span></div>
    <div className="msb-param-desc">File contents decoded as UTF-8.</div>
  </div>
</div>

#### <span className="msb-recv">fs.</span><span className="msb-hn">read\_stream()</span>

```python theme={null}
async def read_stream(path: str) -> FsReadStream
```

<Accordion title="Example">
  ```python theme={null}
  stream = await sb.fs.read_stream("/app/large.log")
  async for chunk in stream:
      process(chunk)
  ```
</Accordion>

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

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>path</code><span className="msb-type">str</span></div>
    <div className="msb-param-desc">Absolute path inside the guest.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><a className="msb-type" href="#fsreadstream">FsReadStream</a></div>
    <div className="msb-param-desc">Async iterator yielding chunks of file data.</div>
  </div>
</div>

#### <span className="msb-recv">fs.</span><span className="msb-hn">write()</span>

```python theme={null}
async def write(path: str, data: bytes) -> None
```

<Accordion title="Example">
  ```python theme={null}
  await sb.fs.write("/app/hello.txt", b"hi\n")
  ```
</Accordion>

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

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>path</code><span className="msb-type">str</span></div>
    <div className="msb-param-desc">Absolute path inside the guest.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>data</code><span className="msb-type">bytes</span></div>
    <div className="msb-param-desc">File content.</div>
  </div>
</div>

#### <span className="msb-recv">fs.</span><span className="msb-hn">write\_stream()</span>

```python theme={null}
async def write_stream(path: str) -> FsWriteSink
```

<Accordion title="Example">
  ```python theme={null}
  async with await sb.fs.write_stream("/app/out.bin") as sink:
      await sink.write(b"chunk one")
      await sink.write(b"chunk two")
  ```
</Accordion>

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

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>path</code><span className="msb-type">str</span></div>
    <div className="msb-param-desc">Absolute path inside the guest.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><a className="msb-type" href="#fswritesink">FsWriteSink</a></div>
    <div className="msb-param-desc">Async writer that accepts chunks of bytes.</div>
  </div>
</div>

#### <span className="msb-recv">fs.</span><span className="msb-hn">list()</span>

```python theme={null}
async def list(path: str) -> list[FsEntry]
```

<Accordion title="Example">
  ```python theme={null}
  for entry in await sb.fs.list("/app"):
      print(entry.kind, entry.path)
  ```
</Accordion>

List the entries in a directory.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>path</code><span className="msb-type">str</span></div>
    <div className="msb-param-desc">Absolute directory path inside the guest.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><a className="msb-type" href="#fsentry">list\[FsEntry]</a></div>
    <div className="msb-param-desc">Directory entries.</div>
  </div>
</div>

#### <span className="msb-recv">fs.</span><span className="msb-hn">mkdir()</span>

```python theme={null}
async def mkdir(path: str) -> None
```

<Accordion title="Example">
  ```python theme={null}
  await sb.fs.mkdir("/app/data/cache")
  ```
</Accordion>

Create a directory, including any missing parent directories.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>path</code><span className="msb-type">str</span></div>
    <div className="msb-param-desc">Absolute directory path inside the guest.</div>
  </div>
</div>

#### <span className="msb-recv">fs.</span><span className="msb-hn">stat()</span>

```python theme={null}
async def stat(path: str) -> FsMetadata
```

<Accordion title="Example">
  ```python theme={null}
  meta = await sb.fs.stat("/app/config.json")
  print(meta.kind, meta.size, meta.readonly)
  ```
</Accordion>

Get detailed metadata for a file or directory.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>path</code><span className="msb-type">str</span></div>
    <div className="msb-param-desc">Absolute path inside the guest.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><a className="msb-type" href="#fsmetadata">FsMetadata</a></div>
    <div className="msb-param-desc">File metadata.</div>
  </div>
</div>

#### <span className="msb-recv">fs.</span><span className="msb-hn">exists()</span>

```python theme={null}
async def exists(path: str) -> bool
```

<Accordion title="Example">
  ```python theme={null}
  if not await sb.fs.exists("/app/config.json"):
      await sb.fs.write("/app/config.json", b"{}")
  ```
</Accordion>

Check whether a path exists inside the sandbox.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>path</code><span className="msb-type">str</span></div>
    <div className="msb-param-desc">Absolute path inside the guest.</div>
  </div>
</div>

<p className="msb-label">Returns</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><span className="msb-type">bool</span></div>
    <div className="msb-param-desc"><code>True</code> if the path exists.</div>
  </div>
</div>

#### <span className="msb-recv">fs.</span><span className="msb-hn">remove\_dir()</span>

```python theme={null}
async def remove_dir(path: str) -> None
```

<Accordion title="Example">
  ```python theme={null}
  await sb.fs.remove_dir("/app/data/cache")
  ```
</Accordion>

Remove a directory and its contents recursively.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>path</code><span className="msb-type">str</span></div>
    <div className="msb-param-desc">Absolute directory path inside the guest.</div>
  </div>
</div>

#### <span className="msb-recv">fs.</span><span className="msb-hn">copy()</span>

```python theme={null}
async def copy(src: str, dst: str) -> None
```

<Accordion title="Example">
  ```python theme={null}
  await sb.fs.copy("/app/config.json", "/app/config.bak.json")
  ```
</Accordion>

Copy a file within the sandbox.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>src</code><span className="msb-type">str</span></div>
    <div className="msb-param-desc">Source path inside the guest.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>dst</code><span className="msb-type">str</span></div>
    <div className="msb-param-desc">Destination path inside the guest.</div>
  </div>
</div>

#### <span className="msb-recv">fs.</span><span className="msb-hn">rename()</span>

```python theme={null}
async def rename(src: str, dst: str) -> None
```

<Accordion title="Example">
  ```python theme={null}
  await sb.fs.rename("/app/tmp.txt", "/app/final.txt")
  ```
</Accordion>

Rename or move a file or directory within the sandbox.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>src</code><span className="msb-type">str</span></div>
    <div className="msb-param-desc">Current path inside the guest.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>dst</code><span className="msb-type">str</span></div>
    <div className="msb-param-desc">New path inside the guest.</div>
  </div>
</div>

#### <span className="msb-recv">fs.</span><span className="msb-hn">remove()</span>

```python theme={null}
async def remove(path: str) -> None
```

<Accordion title="Example">
  ```python theme={null}
  await sb.fs.remove("/app/config.bak.json")
  ```
</Accordion>

Remove a file. Use [`remove_dir()`](#fs-remove_dir) for directories.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>path</code><span className="msb-type">str</span></div>
    <div className="msb-param-desc">Absolute file path inside the guest.</div>
  </div>
</div>

#### <span className="msb-recv">fs.</span><span className="msb-hn">copy\_from\_host()</span>

```python theme={null}
async def copy_from_host(host_path: str, guest_path: str) -> None
```

<Accordion title="Example">
  ```python theme={null}
  await sb.fs.copy_from_host("./local/seed.csv", "/app/seed.csv")
  ```
</Accordion>

Copy a file from the host machine into the sandbox. For transferring many files, consider a [bind-mounted volume](/sandboxes/volumes) instead.

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>host\_path</code><span className="msb-type">str</span></div>
    <div className="msb-param-desc">Path on the host filesystem.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>guest\_path</code><span className="msb-type">str</span></div>
    <div className="msb-param-desc">Destination path inside the sandbox.</div>
  </div>
</div>

#### <span className="msb-recv">fs.</span><span className="msb-hn">copy\_to\_host()</span>

```python theme={null}
async def copy_to_host(guest_path: str, host_path: str) -> None
```

<Accordion title="Example">
  ```python theme={null}
  await sb.fs.copy_to_host("/app/report.pdf", "./report.pdf")
  ```
</Accordion>

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

<p className="msb-label">Parameters</p>

<div className="msb-params">
  <div className="msb-param">
    <div className="msb-param-key"><code>guest\_path</code><span className="msb-type">str</span></div>
    <div className="msb-param-desc">Path inside the sandbox.</div>
  </div>

  <div className="msb-param">
    <div className="msb-param-key"><code>host\_path</code><span className="msb-type">str</span></div>
    <div className="msb-param-desc">Destination path on the host.</div>
  </div>
</div>

## Types

### FsEntry

<p className="msb-backref">Returned by <a href="#fs-list">list()</a></p>

Metadata for a single directory entry, returned by [`list()`](#fs-list).

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

### FsEntryKind

<p className="msb-backref">Describes <a href="#fsentry">FsEntry.kind</a> · <a href="#fsmetadata">FsMetadata.kind</a></p>

String enum ([`StrEnum`](https://docs.python.org/3/library/enum.html#enum.StrEnum)) of filesystem entry types. The `kind` fields on [`FsEntry`](#fsentry) and [`FsMetadata`](#fsmetadata) carry these string values.

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

### FsMetadata

<p className="msb-backref">Returned by <a href="#fs-stat">stat()</a></p>

Detailed file metadata, returned by [`stat()`](#fs-stat).

| Property | Type            | Description                                                                                        |
| -------- | --------------- | -------------------------------------------------------------------------------------------------- |
| kind     | `str`           | Entry type: `"file"`, `"directory"`, `"symlink"`, or `"other"` (see [`FsEntryKind`](#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

<p className="msb-backref">Returned by <a href="#fs-read_stream">read\_stream()</a></p>

Async stream for reading a file in chunks. Obtained via [`read_stream()`](#fs-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

<p className="msb-backref">Returned by <a href="#fs-write_stream">write\_stream()</a></p>

Async writer for streaming data into a file. Obtained via [`write_stream()`](#fs-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 |