Kiri Developers

SDK

SDK API reference

The SDK is six calls with the same names in every language, written in each language’s style: kiri.Serve in Go, kiri::serve in Rust, kiri.serve in TypeScript and Python. Each one returns the type your code already uses where there is one, such as Go’s *sql.DB and *http.Client, so the code around it doesn’t change.

Language Package Import
Go runkiri.com/go/kiri import "runkiri.com/go/kiri"
Rust kiri use kiri;
TypeScript and JavaScript @kiri/sdk import * as kiri from "@kiri/sdk";
Python kiri import kiri

Every call needs its key in kiri.yaml, except kiri.Log. A module that uses a call without its key doesn’t start.

The path of one request through kiri.Serve and kiri.DBYour browserGET /ordersKirilistens on :8080holds theconnectionshop, a modulehandler(w, r)db.Query(“SELECT …”)shop-postgresa container, or your own server1 · :80802 request3 query4 SQL5 response
One request to shop. Kiri owns the port and the database connection; the module only answers the request and asks for rows. It never holds a socket, an address or a password.

kiri.Serve

Kiri listens on the port in kiri.yaml, and at app.kiri.local, and passes each request to your handler. You pass what your framework already makes. Serve doesn’t return while the module runs.

nil means http.DefaultServeMux, as with http.ListenAndServe.

func Serve(h http.Handler) error

log.Fatal(kiri.Serve(nil))   // was: http.ListenAndServe(":8080", nil)

Takes an axum::Router, any tower::Service for http::Request, or a plain fn(Request) -> Response. Handlers can be async.

pub fn serve(app: impl kiri::Handler) -> Result<(), kiri::Error>

kiri::serve(app)?;   // was: axum::serve(listener, app).await?

Takes a fetch handler, (req: Request) => Response | Promise<Response>, or a Node request listener such as an Express app.

function serve(app: FetchHandler | NodeListener): void

kiri.serve(app);   // was: app.listen(8080)

Takes a WSGI app (Flask, Django) or an ASGI app (FastAPI, Starlette). Kiri tells which.

def serve(app) -> None

kiri.serve(app)   # was: app.run(port=8080)

Limits. One port per module. Kiri speaks HTTP/1.1 and HTTP/2 to clients, and HTTPS when HTTPS is on; your handler sees plain HTTP requests. Request and response bodies stream, so server-sent events work, but a request that runs longer than limits.request (60 s unless set) gets 504. WebSockets and other upgraded connections aren’t supported in 1.0: Kiri answers them with 501.

The module runs on one thread. Goroutines, async tasks and the event loop work as usual, and while one request waits on the database or an outbound call, others run. Long computing in one request holds up the rest.

kiri.DB

A connection to the module’s database: SQLite kept by Kiri, or Postgres, as kiri.yaml says. Kiri holds the connection and its password; your code sends queries. Write the SQL of the database you chose, with its usual placeholders: ? for SQLite, $1 for Postgres.

A *sql.DB from database/sql, so Query, Exec, QueryRow, Begin and every library built on them work as they did.

func DB() *sql.DB

rows, err := kiri.DB().Query("SELECT id, total FROM orders WHERE total > ?", 10)
pub fn db() -> kiri::Db
impl Db {   // Result is kiri::Result, with kiri::Error
    pub async fn query(&self, sql: &str, p: impl Params) -> Result<Vec<Row>>;
    pub async fn execute(&self, sql: &str, p: impl Params) -> Result<u64>;
    pub async fn transaction(&self) -> Result<Tx>;
}

let rows = kiri::db().query("SELECT id, total FROM orders", ()).await?;
let total: f64 = rows[0].get("total")?;

query answers in the shape the pg package uses, { rows, rowCount }, so code written against a pg pool keeps working.

function db(): Db
interface Db {
  query<T = Row>(sql: string, params?: unknown[]): Promise<Result<T>>;
  transaction<T>(fn: (tx: Db) => Promise<T>): Promise<T>;
}
type Result<T> = { rows: T[]; rowCount: number };

const { rows } = await kiri.db().query("SELECT id, total FROM orders");

A DB-API 2.0 connection (PEP 249), the interface sqlite3 and psycopg give you.

def db() -> Connection

cur = kiri.db().cursor()
cur.execute("SELECT id, total FROM orders WHERE total > ?", (10,))

Errors and limits. The database’s own errors, such as a syntax error or a broken constraint, come back as they would from its usual driver. When the database can’t be reached, such as when shop-postgres is stopped or your own server is down, calls fail with Unavailable. One database per module. Connections, pooling and reconnecting are Kiri’s job; settings such as Go’s SetMaxOpenConns have no effect.

kiri.HTTP

Outbound HTTP and HTTPS, to the hosts in network and no others. Kiri makes the connection and checks the certificate; a host that isn’t listed is refused before anything is sent.

A *http.Client whose transport goes through Kiri. Importing the SDK also sets http.DefaultTransport, so http.Get and libraries that use the default client go through Kiri unchanged.

func HTTP() *http.Client

resp, err := kiri.HTTP().Get("https://api.stripe.com/v1/charges")
if errors.Is(err, kiri.ErrRefused) { /* not in kiri.yaml */ }
pub fn http() -> kiri::http::Client

let resp = kiri::http().get("https://api.stripe.com/v1/charges")
    .bearer_auth(&key).send().await?;

The same as the global fetch. In a module, the global fetch is this one.

const http: { fetch: typeof fetch }

const resp = await kiri.http.fetch("https://api.stripe.com/v1/charges");

A small client with get, post and request. urllib.request goes through Kiri too.

http.get(url, *, headers=None, params=None, timeout=None) -> Response

resp = kiri.http.get("https://api.stripe.com/v1/charges", headers=auth)

Errors and limits. A host that isn’t listed, or a redirect to one, fails with Refused. A listed host that doesn’t answer fails with Unavailable. Only HTTP and HTTPS: no other protocols, and no raw connections. A call can’t outlast the request that made it.

kiri.Secret

Reads a secret that secrets lists. The value comes from your system’s keychain when you ask, so a secret you change takes effect on the next call, without a restart. Kiri never writes it to a file, and if your code logs a secret’s value, Kiri shows ••• in its place.

func Secret(name string) (string, error)

key, err := kiri.Secret("STRIPE_KEY")
pub fn secret(name: &str) -> kiri::Result<String>

let key = kiri::secret("STRIPE_KEY")?;
function secret(name: string): string

const key = kiri.secret("STRIPE_KEY");
def secret(name: str) -> str

key = kiri.secret("STRIPE_KEY")

Errors. A name that secrets doesn’t list fails with Refused. A listed secret with no value fails with NotSet; kiri run asks for missing secrets before the module starts, so this happens only when one is removed while the module runs. kiri.yaml says how to set them, and where they come from in CI.

kiri.KV and kiri.Log

kiri.KV

The module’s own key-value store, kept under its app name. It outlives restarts and rebuilds; kiri module rm shop --data deletes it. Each set and delete is atomic for its key.

Every language has the same four methods: get, set, delete and list, which lists the keys under a prefix.

A missing key gives nil, false, nil.

func KV() *kiri.Store
func (s *Store) Get(key string) ([]byte, bool, error)
func (s *Store) Set(key string, value []byte) error
func (s *Store) Delete(key string) error
func (s *Store) List(prefix string) ([]string, error)

last, ok, err := kiri.KV().Get("rates:EUR")

A missing key gives Ok(None).

pub fn kv() -> kiri::Kv
impl Kv {
    pub async fn get(&self, key: &str) -> Result<Option<Vec<u8>>>;
    pub async fn set(&self, key: &str, value: impl AsRef<[u8]>) -> Result<()>;
    pub async fn delete(&self, key: &str) -> Result<()>;
    pub async fn list(&self, prefix: &str) -> Result<Vec<String>>;
}

let last = kiri::kv().get("rates:EUR").await?;

A missing key gives null. Values are strings or Uint8Array.

function kv(): Store
interface Store {
  get(key: string): Promise<string | Uint8Array | null>;
  set(key: string, value: string | Uint8Array): Promise<void>;
  delete(key: string): Promise<void>;
  list(prefix?: string): Promise<string[]>;
}

const last = await kiri.kv().get("rates:EUR");

A missing key gives None. Values are bytes or str.

def kv() -> Store
# Store.get(key) -> bytes | None, .set(key, value), .delete(key), .list(prefix="") -> list[str]

last = kiri.kv().get("rates:EUR")

Limits. Keys up to 512 bytes, values up to 1 MB; larger ones fail with TooLarge. For more, or for anything you query, use kiri.DB.

kiri.Log

Writes to the module’s log, which shows in your terminal under kiri run, in kiri module logs, and on the module’s Logs tab. No key needed. What the module prints to standard output and standard error goes there too, so fmt.Println, console.log and print still show.

Language What kiri.Log is To send existing logging there
Go func Log() *slog.Logger slog.SetDefault(kiri.Log())
Rust A logger for the log crate kiri::log::init(), then log::info!
TypeScript kiri.log.debug, info, warn, error (message, fields) console already goes there
Python A logging.Logger named after the app logging already goes there

Each line has a level (debug, info, warn, error) and any fields you add, which the window shows as key=value and lets you filter by.

Kiri
KiriModulesUSBShareSettings

Modules › shop

OverviewLogsPermissionsSecurity
14:05:01infocharge createdorder=1042 total=42.50
14:05:02infoGET /checkout 20041 ms
14:05:09warnrefused kiri.HTTP → api.github.comnot in network
14:05:12errorstripe: card declinedorder=1043
The shop module's Logs tab. Lines from kiri.Log carry their level and fields; Kiri's own lines, such as a refused call, sit among them.

Errors

The SDK’s own errors are the same four in every language. Each message names what was refused or missing, and the kiri.yaml key that would allow it.

Error When
Refused The call isn’t allowed by kiri.yaml: a host, a redirect or a secret name
NotSet A listed secret has no value
Unavailable The database or a listed host can’t be reached
TooLarge A key or value is over the store’s limit
Language Their names
Go kiri.ErrRefused, ErrNotSet, ErrUnavailable, ErrTooLarge
Rust kiri::Error::Refused, NotSet, Unavailable, TooLarge
TypeScript kiri.RefusedError, NotSetError, UnavailableError, TooLargeError
Python kiri.Refused, NotSet, Unavailable, TooLarge

In Go, match them with errors.Is, also through the *url.Error that http.Client wraps around them. Every Refused also goes in the module’s log and on its Permissions tab, whether your code handles it or not.

© 2026 Kiri · The SDK is open source under the Apache License 2.0 · Docs · runkiri.com