SDK
How modules run
A module is one WebAssembly file. Kiri compiles it to machine code once, when it builds it, and runs it in its module runtime, built on the open-source Wasmtime, in the same Linux place where your containers run. The module’s code never runs on your Mac or PC directly, and everything it touches outside its own memory goes through Kiri.
Where modules run
Kiri runs modules beside your containers, wherever its engine keeps them:
| Mac | Linux | Windows | |
|---|---|---|---|
| Where | In Kiri’s Linux VM, next to your containers | On the host’s kernel, in a locked-down process of its own | In WSL, in the distro where Kiri’s engine lives |
| Host calls | Go to Kiri on the Mac over vsock: the keychain, the GPU | Go to Kiri on the host | Go to Kiri on Windows, for the keychain and the GPU |
| Reached at | shop.kiri.local and localhost:8080 |
the same | the same |
Because a module and your containers share that Linux place, a module reaches a container at its .kiri.local name, and a container reaches a module at its port, without anything leaving your computer.
How a module is held to kiri.yaml
A module is shut in by WebAssembly itself, and by what Kiri gives it:
- Its own memory, and nothing else. A module’s memory is one block that the runtime gives it. Its code can’t address anything outside that block: not the runtime, not another module, not the VM.
- No system calls. A module can’t open a file, a socket or a process by itself. It can only call the functions Kiri hands it when it starts, and Kiri hands it only the calls
kiri.yamlallows. A call with no key isn’t there to make. - Every call checked. The calls it has are checked each time: the host of every outbound request, the name of every secret. A refusal goes to the module’s log and its Permissions tab.
- Files only from the module. The folders in
filesare packed into the module at build time, read-only. Nothing on your computer or in the VM is visible. - Limits. The module’s memory stops at
limits.memory, and a request that runs pastlimits.requestis ended. A module runs on one thread, so it can’t take every CPU. - Kiri’s own walls around it. On a Mac and on Windows, the runtime is inside the same VM boundary as your containers; see Security. On Linux, the runtime is its own process with no capabilities and a system call filter, like a container.
Modules and containers can reach each other only as clients: a module calls a container whose .kiri.local name is in its network list, and anything can call a module at its port. Two modules never share memory.
Host capabilities
Heavy work doesn’t run inside the module. The module asks for it, and Kiri does it as native code, at full speed:
| Capability | How the module asks | Where the work runs |
|---|---|---|
| A database | kiri.DB, with database |
SQLite inside Kiri, or a real Postgres: a container beside the module, or your own server |
| A GPU | WASI’s neural network interface, wasi-nn, with gpu: true |
Your computer’s GPU. On a Mac, Kiri runs the model on the Mac and returns the result to the module in the VM |
| A heavy program, such as video encoding | kiri.HTTP to a container’s .kiri.local name |
That container, beside the module |
So a module stays small and starts at once, while the work that needs a big program or special hardware runs where it runs best.
Start time, memory and size
Kiri compiles a module to machine code when it builds it, or when it pulls one from a registry, and keeps that code with the module. Starting a module is loading ready-made code, with no compiler running. The runtime itself costs about 2 MB, once for all modules.
These figures come from the same small program built four ways and run in Kiri’s Linux side on an Apple silicon Mac. Your module’s numbers depend on what it carries, and kiri run prints them each time.
On disk, that program was 3.2 MB of WebAssembly from Go and 91 KB from Rust, against container images of 2.4 MB for Go and 17.4 MB for Python. A TypeScript or Python module also carries its language’s engine, so it’s bigger and slower to start than these.
A module and a container, compared
| A container | A module | |
|---|---|---|
| What you ship | An image: your program and a Linux userland | One WebAssembly file, with kiri.yaml and any packed files |
| How it’s built | A Dockerfile | Kiri reads go.mod, Cargo.toml, package.json or pyproject.toml |
| Languages | Any program that runs on Linux | Go, Rust, TypeScript and JavaScript, Python |
| Starts in | 2.55 ms through Kiri’s Engine API (see Benchmarks) | About a millisecond |
| Reaches | Any address its network allows, and the folders you mount | Only what kiri.yaml lists, through Kiri |
| Secrets | Environment variables or mounted files | kiri.Secret, from the keychain |
| Walls | Namespaces, cgroup and a system call filter, inside Kiri’s VM on a Mac | WebAssembly’s sandbox and the module runtime, inside the same VM |
| In a registry | An OCI image | An OCI artifact, beside your images |
| In the window | Containers | Modules |
Use both. A module for the code you write, containers for the programs you run, side by side on the same Kiri.
© 2026 Kiri · The SDK is open source under the Apache License 2.0 · Docs · runkiri.com