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.
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:
$ 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 noteAfter 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);
$ 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 publicTwo 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