SDK
kiri.yaml
kiri.yaml sits next to go.mod, Cargo.toml, package.json or pyproject.toml, and lists everything a module may touch. A module starts with nothing: no network, no files, no secrets. Each key under needs opens one thing, and Kiri holds the module to the list on every call.
A full file
Most modules need three or four keys. This one uses all of them:
app: shop
needs:
port: 8080
database: postgres # or sqlite, kept by Kiri
network: [api.stripe.com, search.kiri.local]
secrets: [STRIPE_KEY]
kv: true
files: [templates, static]
env:
LOG_LEVEL: info
build:
main: ./cmd/shop
limits:
memory: 512MB
request: 60s
kiri check . --write makes a first kiri.yaml from what your code uses, with nothing extra. Edit it by hand after that.
The keys
| Key | What it is |
|---|---|
app |
Required. The module’s name: lowercase letters, digits and hyphens. It names the module in the window and in kiri module commands, gives it its local address, shop.kiri.local, and is the name its database and store are kept under. |
needs |
What the module may touch. A call whose key is missing can’t be used at all. |
env |
Plain settings, read as environment variables. Not for secrets: Kiri shows these values in the window and writes them into the module’s bill of materials. |
build |
How to build, when Kiri can’t tell from the project. main picks the program when there’s more than one: a Go package such as ./cmd/shop, a Rust binary’s name, or a TypeScript or Python file. |
limits |
memory, the most memory the module may use (512 MB if left out, up to 4 GB). request, the longest one request may take before Kiri answers 504 for it (60 s if left out). |
needs
Each key opens one call.
| Key | Value | What it allows |
|---|---|---|
port |
A port number | Kiri listens on this port on your computer, and at app.kiri.local, and passes each request to your handler through kiri.Serve. One port per module. |
database |
sqlite or postgres |
A database through kiri.DB. See below. |
network |
Host names | Outbound HTTP and HTTPS through kiri.HTTP, to these hosts and no others. |
secrets |
Names | Reading these secrets through kiri.Secret. The values stay in the keychain. |
kv |
true |
The module’s own key-value store, through kiri.KV. |
files |
Folders, relative to kiri.yaml |
Reading these folders with your language’s usual file calls. Kiri packs them into the module when it builds it, read-only, at the same paths. |
gpu |
true |
Running models on your computer’s GPU, through WASI’s neural network interface, wasi-nn. |
kiri.Log needs no key: every module may write to its own log.
When someone runs a module they didn’t build, such as one pulled from a registry, Kiri turns each key into one line and asks before it starts:
| Key | Line in the prompt |
|---|---|
port: 8080 |
Listen on port 8080 |
database: sqlite |
Keep a SQLite database |
database: postgres |
Use a Postgres database |
network: [api.stripe.com] |
Reach these sites: api.stripe.com |
no network |
No internet |
secrets: [STRIPE_KEY] |
Read these secrets: STRIPE_KEY |
kv: true |
Keep data in its own store |
files: [templates] |
Read the files packed into it: templates |
gpu: true |
Run models on your GPU |
needs: network
Write each host name out in full. *.example.com covers every name under example.com, but not example.com itself. Kiri follows a redirect only to a host on the list.
A name ending in .kiri.local is a container or another module on Kiri, such as search.kiri.local for a container called search. That’s how a module calls heavy work that runs as a container beside it. A module can’t reach your computer, your local network or other private addresses, whatever the list says.
needs: database
sqlite: Kiri keeps one SQLite database for the module, under itsappname, and keeps it between runs and rebuilds.kiri module db shopopens a SQL prompt on it.postgres: Kiri starts a Postgres container for the module,shop-postgres, with its data in a volume, and connects the module to it. To use a Postgres of your own instead, a server or a hosted one, set the module’sDATABASE_URLsecret to its connection URL:kiri secret set shop DATABASE_URL. Kiri connects to that one.
Either way, Kiri holds the connection. Your code gets a handle and sends queries; it never sees the database’s address or password, and can’t open a connection of its own.
needs: secrets
A secret’s value lives in your system’s keychain: the Keychain on a Mac, Credential Manager on Windows, the Secret Service on Linux. Set one with kiri secret set shop STRIPE_KEY, which asks for the value without showing it, or from the module’s Permissions tab. kiri secret ls shop lists the names, never the values.
On a server or in CI, where there’s no keychain, Kiri reads KIRI_SECRET_STRIPE_KEY from its own environment, which your CI fills from its secret store. The module never sees Kiri’s environment; it gets only the secrets kiri.yaml lists, and only through kiri.Secret.
When a module reaches past the list
Kiri checks in two places, and a refusal is never silent.
When it builds. Kiri reads which calls the module uses and compares them with needs. A call with no key stops kiri run before the module starts, and says which line to add. A key the module never uses gets a note, so the list doesn’t grow stale.
$ kiri run .
◆ shop building Go 1.26 → WebAssembly…
✗ shop uses kiri.KV, but kiri.yaml doesn't list kv.
Add it under needs: kv: true
· kiri.yaml lists files: static, but nothing reads it.When it calls. A call to a host that isn’t in network, or for a secret that isn’t in secrets, is refused. The request is never sent: your code gets an error it can handle (kiri.ErrRefused in Go, and the same in each language; see Errors), and the module keeps running. Kiri writes the refusal to the module’s log and counts it on the Permissions tab.
14:05:02 GET 200 /checkout 41 ms
14:05:09 warn refused kiri.HTTP → api.github.com (not in network)
14:05:09 GET 502 /profile 2 msAnything no key allows, such as writing a file, opening a socket or starting a process, isn’t a call the module can make at all. WebAssembly gives it no such door, so the language’s own call fails with its usual error, and Kiri logs that too.
How permissions show in the window
A module’s Permissions tab has two lists. It may has a line for each key in needs, in the prompt’s words, with what the module did with it: calls made, and for secrets whether each is set. It tried lists what Kiri refused, with how often and when last. For a module built from your folder, Add to kiri.yaml writes the missing line into the file; the next run picks it up.
Modules › shop
A secret that’s listed but not set shows Not set and a Set… button, and kiri run asks for it before the module starts. A module from a registry has no Add to kiri.yaml: its permissions are the ones you agreed to when you ran it.
Changing the list
For a module built from your folder, edit kiri.yaml and run it again; kiri run --watch restarts it when you save. Kiri doesn’t ask you, because it’s your own code.
A module you didn’t build is different. The first time you run it, Kiri shows what its kiri.yaml asks for, one line per key, and waits for a yes. When a new version asks for more, Kiri asks again, and keeps the old version if you say no. Supply chain and policy shows the prompt, and how your company can limit what any module may ask for.
© 2026 Kiri · The SDK is open source under the Apache License 2.0 · Docs · runkiri.com