Kiri Developers

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 its app name, and keeps it between runs and rebuilds. kiri module db shop opens 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’s DATABASE_URL secret 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.

zsh
$ 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.

zsh
  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 ms

Anything 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.

A refused callshopkiri.HTTPGET api.github.comyour code getsErrRefusedKirikiri.yaml network:api.stripe.comapi.github.comisn’t on the listThe internetapi.github.comnever contactedKiri’s windowLogs: refusedPermissions: 1 refusedcallnot senterrorlogged
A call to a site that isn't listed. Kiri compares the host with network in kiri.yaml, never opens the connection, returns an error to your code, and records the refusal in the module's log and on its Permissions tab.

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.

Kiri
KiriModulesUSBShareSettings

Modules › shop

OverviewLogsPermissionsSecurity
It may
✓ Listen on port 8080shop.kiri.local
✓ Use a Postgres databaseshop-postgres
✓ Reach these sites: api.stripe.com128 calls
✓ Read these secrets: STRIPE_KEYSet
It tried
✕ Reach api.github.comRefused 3 timesAdd to kiri.yaml
The shop module's Permissions tab. It may reach Stripe and read STRIPE_KEY, which is set; it tried to reach api.github.com three times, and Kiri refused each one.

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