Kiri Developers

SDK

Move a service to a module

A service that runs in a container today does its own wiring: it opens a socket, dials its database with an address and a password, reads secrets from its environment and files from its image. In a module, Kiri does that wiring and kiri.yaml lists it. This page moves two real-sized services, a Go net/http API and an Express app, and lists what kiri check finds most often.

From container wiring to kiri.yamlBefore: the containerListenAndServe(“:8080”)sql.Open(DATABASE_URL)os.Getenv(“STRIPE_KEY”)templates/ copied into the imagehandlersAfter: the moduleport: 8080 · kiri.Servedatabase: postgres · kiri.DBsecrets: [STRIPE_KEY]files: [templates]the same handlersKiri listensKiri holds the connectionfrom the keychainpacked into the moduleunchanged
What moves where. Each piece of wiring the container did for itself becomes a line in kiri.yaml and a call to Kiri. The handlers in between don't move.

A Go net/http service

orders is an API with a Postgres database, Stripe for payments and HTML templates on disk. Its main did all the wiring:

func main() {
	db, err := sql.Open("pgx", os.Getenv("DATABASE_URL"))
	if err != nil {
		log.Fatal(err)
	}
	stripeKey := os.Getenv("STRIPE_KEY")
	tmpl := template.Must(template.ParseGlob("templates/*.html"))

	mux := http.NewServeMux()
	mux.HandleFunc("GET /orders", listOrders(db, tmpl))
	mux.HandleFunc("POST /checkout", checkout(db, stripeKey))

	log.Fatal(http.ListenAndServe(":8080", mux))
}

kiri check finds the two lines every service changes, plus the secret and the templates, which only need a line in kiri.yaml and a call:

zsh
$ kiri check .
  orders · Go 1.26 · 58 packages
  ✓ 57 packages work as WebAssembly
  ✗ github.com/jackc/pgx/v5        opens its own TCP connections
      main.go:12  sql.Open("pgx", …)              → kiri.DB()
  ✗ net/http listener               listens by itself
      main.go:23  http.ListenAndServe(":8080", mux) → kiri.Serve(mux)
  ·  main.go:16  os.Getenv("STRIPE_KEY")  a module gets no environment of yours
                                          → kiri.Secret("STRIPE_KEY")
  ·  main.go:17  reads templates/*.html   → add templates to files in kiri.yaml

  2 to change, 2 to note

After the change, main asks Kiri for the same things. listOrders and checkout don’t change: they get the same *sql.DB, the same key string and the same templates. The Stripe calls inside checkout use Go’s default HTTP client, which the SDK sends through Kiri.

func main() {
	db := kiri.DB()
	stripeKey, err := kiri.Secret("STRIPE_KEY")
	if err != nil {
		log.Fatal(err)
	}
	tmpl := template.Must(template.ParseGlob("templates/*.html"))

	mux := http.NewServeMux()
	mux.HandleFunc("GET /orders", listOrders(db, tmpl))
	mux.HandleFunc("POST /checkout", checkout(db, stripeKey))

	log.Fatal(kiri.Serve(mux))
}
app: orders
needs:
  port: 8080
  database: postgres
  network: [api.stripe.com]
  secrets: [STRIPE_KEY]
  files: [templates]

database: postgres starts a Postgres container for the module. If you have a Postgres already, set its address as the module’s DATABASE_URL secret with kiri secret set orders DATABASE_URL, and Kiri connects there instead. The Dockerfile can go once you’ve moved; until then it still builds the same code, because the SDK falls back to ordinary behaviour outside Kiri (see Outside Kiri).

An Express app

The same service in JavaScript, with Express and the pg package:

import express from "express";
import pg from "pg";

const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL });
const app = express();
app.use(express.json());
app.use(express.static("public"));

app.get("/orders", async (req, res) => {
  const { rows } = await pool.query("SELECT id, total FROM orders");
  res.json(rows);
});

app.listen(3000);
zsh
$ kiri check .
  orders · JavaScript · 64 packages
  ✓ 63 packages work as WebAssembly
  ✗ pg                     opens its own TCP connections
      server.js:4   new pg.Pool({ … })   → kiri.db()
  ✗ app.listen             listens by itself
      server.js:14  app.listen(3000)     → kiri.serve(app)
  ·  server.js:7   express.static("public") reads files
                 → add public to files in kiri.yaml

  2 to change, 1 to note
$ kiri check . --write
  ✓ wrote kiri.yaml: app orders · needs database postgres, port 3000, files public

Two lines change. kiri.db() answers query in the same shape as a pg pool, { rows, rowCount }, so the route doesn’t change, and kiri.serve takes the Express app as it is:

 import express from "express";
-import pg from "pg";
+import * as kiri from "@kiri/sdk";

-const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL });
+const pool = kiri.db();
 const app = express();
 ...
-app.listen(3000);
+kiri.serve(app);

Kiri reads package.json to build it, TypeScript included: a .ts entry is compiled as part of the build, with your tsconfig.json. The module carries a small JavaScript engine with the parts of Node’s API that web frameworks use, such as http requests and responses, Buffer, streams and events, so Express, Koa and Fastify run as they are.

What kiri check finds most often

Language It finds What to do
Go A package that needs cgo, such as mattn/go-sqlite3 kiri.DB() with database: sqlite, or a pure-Go package
Go A database driver that dials by itself: pgx, lib/pq, go-sql-driver/mysql kiri.DB()
Go os/exec, or a package that starts programs Run that program as a container and call it by its .kiri.local name
Rust tokio with rt-multi-thread, or std::thread::spawn kiri::serve runs your async code on one thread; drop the multi-thread runtime
Rust A crate that links a C library, such as openssl-sys kiri::http makes TLS connections for you; use pure-Rust crates for the rest
Rust sqlx, tokio-postgres, reqwest kiri::db() and kiri::http()
TypeScript A package with a native addon, such as bcrypt or sharp A pure-JavaScript package such as bcryptjs, or a container for heavy work like sharp
TypeScript child_process, or writing files with fs A container for the program; kiri.kv() or kiri.db() for data
Python A package with C parts that has no WebAssembly build, such as psycopg2 kiri.db(), or a pure-Python package
Python threading, multiprocessing or subprocess An ASGI app for concurrency; a container for other programs
Any Reading a secret from the environment kiri.Secret and secrets in kiri.yaml
Any Reading files from disk The folder in files, packed into the module read-only
Any Writing files, such as uploads or a cache kiri.KV for small values, kiri.DB for the rest

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