Kiri Developers

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.

Where a module runs on a MacYour Mackiri daemonEngine API, the window, kiri runanswers host callsKeychainSTRIPE_KEYGPUmodel inferencereadswasi-nnYour browsershop.kiri.localKiri’s Linux VMkiri-initthe agent, PID 1Module runtimeWasmtime, one per engineshop2.1 MBhooksanother moduleshop-postgresa containersearcha containervsock:8080host callskiri.DB: SQLkiri.HTTP, if listed
Where a module runs on a Mac. The module runtime sits in Kiri's Linux VM beside your containers. Your browser reaches the module at port 8080, its database calls go to a container next to it, and calls that need the Mac, the keychain and the GPU, cross to Kiri on the Mac over vsock.

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.yaml allows. 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 files are 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 past limits.request is 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.

Memory of the same small program while it waits for work: 12.6 MB as a Python container, 5.8 MB as a Go container, about a megabyte as a module.
Time to load the module's ready-made code: what starting a module costs before your own start-up code runs.

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 and a module side by sideA containeryour programits librariesOS userland: libc, shell, packagesnamespaces, cgroup,system call filterA moduleyour code, its librariesand the SDKshop.wasmmodule runtime:its own memory, no system calls,each call checkedthe same Linux kernel: Kiri’s VM on a Mac, the host on Linux, WSL on Windowsany addressmounted foldersonlykiri.yaml
What's inside each. A container brings its own Linux userland and reaches whatever its network allows; a module is your code and the SDK, and reaches only what kiri.yaml lists, through Kiri.
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