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

# WASI

> Run Python in WebAssembly with access to workspace files, in the Python SDK.

`wasi` runs CPython in WebAssembly, with the standard library available
subject to the restrictions below. Programs can access workspace files
under the same permissions as shell commands, but cannot access host files
or the network. Python SDK only.

## Installation

```bash theme={null}
pip install 'mirage-ai[wasi]'
```

Download and unzip a release from
[cpython-wasi-build](https://github.com/brettcannon/cpython-wasi-build/releases).
Point `home`, or `MIRAGE_WASI_HOME`, at the unzipped directory.

## Usage

> [tab] Python
>
> ```python theme={null}
> from mirage import RAMVFS, MountMode, Workspace
> from mirage.runtime.python import WasiRuntime
>
> ws = Workspace(
>     {"/data": RAMVFS()},
>     mode=MountMode.EXEC,
>     machines={"py": WasiRuntime(config={"home": "/path/to/build"})},
> )
> await ws.shell("python3 -c 'print(1 + 1)'")
> ```

> [tab] YAML
>
> ```yaml theme={null}
> mode: exec
> machines:
>   py:
>     provider: in_process
>     runtime: wasi
>     home: /path/to/build
> mounts:
>   /data:
>     vfs: ram
> ```

## Memory

`max_memory` caps the memory one run may grow to:

```yaml theme={null}
machines:
  py:
    provider: in_process
    runtime: wasi
    home: /path/to/build
    max_memory: 256M
```

A run that needs more raises `MemoryError`. CPython starts at about 40M, so
a cap below that fails every run. There is no cap by default.

## Python compatibility

Examples assume a writable `/data` mount. Mount modes and permissions still apply.

### `open()`

Modes and modifiers are listed separately; for example, `rb` combines `r` and `b`.

| Mode or modifier | Support |
| - | - |
| `r` | ✓ |
| `w` | ✓ |
| `a` | ✓ |
| `x` | ✓ |
| `b` | ✓ |
| `t` | ✓ |
| `+` | ✓ |

> [accordion] Example: append to a workspace file
>
> ```python theme={null}
> with open("/data/log.txt", "a") as f:
>     f.write("Job completed.\n")
> ```

> [accordion] Limitations
>
> | API or behavior | Limitation |
> | - | - |
> | File access | Writes to workspace files follow mount permissions. Paths outside the mounts expose the CPython build read-only. |

### File objects

Reads fetch ranges from the mount as the program asks for them.

| API | Support |
| - | - |
| `f.read()` | ✓ |
| `f.write()` | ✓ |
| `f.truncate()` | ✓ |

> [accordion] Example: write, read and truncate a file
>
> ```python theme={null}
> with open("/data/example.txt", "w+") as f:
>     f.write("first\nsecond\n")
>     f.seek(0)
>     print(f.read(5))  # first
>     f.truncate(5)
> ```

> [accordion] Limitations
>
> | API or behavior | Limitation |
> | - | - |
> | `f.write()` | Written at close or `os.fsync`. |

### `os`

#### File operations

`os.read()` and `os.pread()` fetch ranges from the mount as the program asks.

| API | Support |
| - | - |
| `os.open()` | ✓ |
| `os.read()` | ✓ |
| `os.pread()` | ✓ |
| `os.write()` | ✓ |
| `os.pwrite()` | ✓ |
| `os.fsync()` | ✓ |
| `os.truncate()` | ✓ |
| `os.remove()` | ✓ |
| `os.unlink()` | ✓ |
| `os.rename()` | ✓ |
| `os.replace()` | ✓ |

#### Directory operations

| API | Support |
| - | - |
| `os.listdir()` | ✓ |
| `os.scandir()` | ✓ |
| `os.walk()` | ✓ |
| `os.mkdir()` | ✓ |
| `os.makedirs()` | ✓ |
| `os.rmdir()` | ✓ |

#### Metadata and links

| API | Support |
| - | - |
| `os.stat()` | ✓ |
| `os.lstat()` | ✓ |
| `os.fstat()` | ✓ |
| `os.symlink()` | ✓ |
| `os.readlink()` | ✓ |
| `os.utime()` | ✓ |

#### Environment and working directory

| API | Support |
| - | - |
| `os.getcwd()` | ✓ |
| `os.chdir()` | ✓ |
| `os.environ` | ✓ |

> [accordion] Example: list a workspace directory
>
> ```python theme={null}
> import os
>
> print(os.listdir("/data"))
> ```

> [accordion] Limitations
>
> | API or behavior | Limitation |
> | - | - |
> | `os.chmod()` | Accepted, but has no effect. |
> | `os.link()` | Raises `PermissionError`. |
> | `os.getxattr()` | ✗ |
> | `os.setxattr()` | ✗ |
> | `os.listxattr()` | ✗ |
> | `os.removexattr()` | ✗ |
> | `os.write()`, `os.pwrite()` | Written at close or `os.fsync`. |
> | `os.rename()`, `os.replace()` | `EXDEV` across mounts, where `shutil.move` copies instead. |
> | `os.stat()`, `os.lstat()`, `os.fstat()` | `st_mode` has only the file type bits. |
> | `os.getcwd()`, `os.chdir()` | The shell's working directory; a change lasts for the run. |
> | `os.environ` | The session's environment, never the host's. |

### `os.path`

| API | Support |
| - | - |
| `os.path` | ✓ |

> [accordion] Example: check a workspace path
>
> ```python theme={null}
> import os.path
>
> path = os.path.join("/data", "input.txt")
> print(os.path.exists(path))
> ```

### `pathlib`

| API | Support |
| - | - |
| `Path.stat()` | ✓ |
| `Path.glob()` | ✓ |
| `Path.unlink()` | ✓ |
| `Path.touch()` | ✓ |

> [accordion] Example: create and inspect a workspace file
>
> ```python theme={null}
> from pathlib import Path
>
> path = Path("/data/example.txt")
> path.write_text("hello\n")
> print(path.read_text())
> print(path.stat().st_size)
> ```

> [accordion] Limitations
>
> | API or behavior | Limitation |
> | - | - |
> | `Path.stat()` | `st_mode` has only the file type bits. |

### `sys`

| API | Support |
| - | - |
| `sys.argv` | ✓ |
| `sys.stdin` | ✓ |

> [accordion] Example: read arguments and piped input
>
> ```python theme={null}
> import sys
>
> print(sys.argv[1:])
> print(sys.stdin.read())
> ```

### `time` and `datetime`

The clocks start at the workspace's [system time](https://docs.mirage.strukto.ai/home/configuration/workspace.md#system-time)
when it sets one, and files the program writes are stamped from the same
clock. `time.monotonic()` and `time.perf_counter()` measure elapsed time.

| API | Support |
| - | - |
| `time.time()`, `time.time_ns()` | ✓ |
| `time.localtime()`, `time.gmtime()`, `time.strftime()` | ✓ |
| `time.monotonic()`, `time.perf_counter()` | ✓ |
| `datetime.datetime.now()` | ✓ |
| `datetime.date.today()` | ✓ |

> [accordion] Example: print today's date
>
> ```python theme={null}
> import datetime
>
> print(datetime.date.today())
> ```

> [accordion] Limitations
>
> | API or behavior | Limitation |
> | - | - |
> | Local times | UTC. `TZ` does not change them. |

### `json`

| API | Support |
| - | - |
| `json.load()` | ✓ |

> [accordion] Example: write and read workspace JSON
>
> ```python theme={null}
> import json
>
> with open("/data/result.json", "w") as f:
>     json.dump({"status": "done"}, f)
>
> with open("/data/result.json", "r") as f:
>     result = json.load(f)
> print(result["status"])  # done
> ```

### `glob`

| API | Support |
| - | - |
| `glob.glob()` | ✓ |

> [accordion] Example: find workspace text files
>
> ```python theme={null}
> import glob
>
> print(glob.glob("/data/*.txt"))
> ```

### `shutil`

| API | Support |
| - | - |
| `shutil.rmtree()` | ✓ |
| `shutil.move()` | ✓ |

> [accordion] Example: move a workspace file
>
> ```python theme={null}
> import shutil
>
> with open("/data/draft.txt", "w") as f:
>     f.write("ready\n")
>
> shutil.move("/data/draft.txt", "/data/final.txt")
> ```

> [accordion] Limitations
>
> | API or behavior | Limitation |
> | - | - |
> | `shutil.move()` | Copies instead when a rename would cross mounts (`EXDEV`). |

### `subprocess`

Process creation is unavailable in this runtime.

> [accordion] Limitations
>
> | API or behavior | Limitation |
> | - | - |
> | `subprocess` | Raises `OSError` (errno 58). |

### `socket`

Network connections are unavailable in this runtime.

> [accordion] Limitations
>
> | API or behavior | Limitation |
> | - | - |
> | `socket` | Raises `OSError` (errno 58). |

## Notes

* Each command starts with fresh Python state. Files saved to workspace
  mounts persist between commands.
* Exit codes are limited to 0–255.
* Empty-path behavior depends on the Python build. Use `.` for the current
  directory.
* A workspace mount at `/lib` or any path starting with `/lib/python`
  makes `python3` exit 126 to protect the interpreter's standard library.
  Other paths under `/lib`, such as `/lib/app`, are fine.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.