> ## 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

> Full CPython in WebAssembly on wasmtime, for python3 in the Python SDK.

`wasi` runs full CPython, with the whole standard library, compiled to
WebAssembly and run on [wasmtime](https://wasmtime.dev) inside the Mirage
process. It has no host files or network: the files it opens are the
workspace's, under the same mount modes and permissions as shell commands.
The first run compiles the interpreter and caches it; later runs start in
milliseconds. 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

<Tabs>
  <Tab title="Python" icon="https://mintcdn.com/struktoai/F9Lv_nTaj6By6crk/images/python-logo.svg?fit=max&auto=format&n=F9Lv_nTaj6By6crk&q=85&s=cf5b268d330f7db46ea5cf6083f309a1" width="110" height="110" data-path="images/python-logo.svg">
    ```python theme={null}
    from mirage import RAMVFS, MountMode, Workspace
    from mirage.runtime.python import WasiRuntime

    ws = Workspace(
        {"/data": RAMVFS()},
        mode=MountMode.EXEC,
        runtimes=[WasiRuntime(config={"home": "/path/to/build"})],
    )
    await ws.shell("python3 -c 'print(1 + 1)'")
    ```
  </Tab>

  <Tab title="YAML" icon="file-code">
    ```yaml theme={null}
    mode: exec
    runtimes:
      - name: wasi
        config:
          home: /path/to/build
    mounts:
      /data:
        vfs: ram
    ```
  </Tab>
</Tabs>

## What is wired

Anything built on these calls, such as `os.path`, `pathlib`, `glob`,
`shutil` and `json.load`, works too.

| Python | Supported | Notes |
| - | - | - |
| `open()` in every mode, `os.open` | Yes | |
| `f.read()`, `os.read`, `os.pread` | Yes | Read in ranges, as the program asks. |
| `f.write()`, `os.write`, `os.pwrite` | Yes | Written at close or `os.fsync`. |
| `f.truncate()`, `os.truncate` | Yes | |
| `os.stat`, `os.lstat`, `os.fstat`, `Path.stat` | Yes | `st_mode` has only the file type bits. |
| `os.listdir`, `os.scandir`, `os.walk`, `glob.glob`, `Path.glob` | Yes | |
| `os.mkdir`, `os.makedirs`, `os.rmdir`, `shutil.rmtree` | Yes | |
| `os.remove`, `os.unlink`, `Path.unlink` | Yes | |
| `os.rename`, `os.replace`, `shutil.move` | Yes | `EXDEV` across mounts, where `shutil.move` copies instead. |
| `os.symlink`, `os.readlink` | Yes | |
| `os.utime`, `Path.touch` | Yes | |
| `os.getcwd`, `os.chdir` | Yes | The shell's working directory; a change lasts for the run. |
| `os.environ`, `sys.argv`, `sys.stdin` | Yes | The session's environment, the words after the script, and the piped input. |
| `os.chmod` | No | Does nothing. |
| `os.link` | No | Raises `PermissionError`. |
| `os.getxattr` and the other xattr calls | No | They do not exist. |
| `subprocess`, `socket` | No | Raise `OSError` (errno 58). |

Paths outside the mounts show the CPython build, read-only.


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