PLUGINS
Your first plugin
A plugin is a folder with two things in it: a kiri-plugin.toml that says what the plugin adds and what it needs, and the code. This page builds one from an empty folder. The no-latest plugin blocks a pull when the image has no fixed version: no tag, or :latest. Then it gets a note in the status bar, a test, and a copy you can hand to someone. It takes about ten minutes. The steps use TypeScript; the same check in Go, Rust and Python is at the end, in the language you picked at the top of the page.
You need Kiri 1.0 or later. You don’t need Node.js or a WebAssembly toolchain: kiri plugin builds in Kiri’s own builder.
Make a check
-
Make the folder.
kiri plugin newwrites akiri-plugin.toml, amark.svgto replace with your own icon, asrc/main.ts, atests/folder and the build setup:kiri plugin new no-latest --lang typescript cd no-latest -
Say what the plugin adds, in
kiri-plugin.toml. It adds one check, before a pull, and needs nothing:name = "no-latest" version = "1.0.0" publisher = "your-name" description = "Blocks pulls of images with no fixed version (no tag, or :latest)." mark = { icon = "mark.svg", colour = "orange" } [run] wasm = "dist/no-latest.wasm" [adds] checks = [{ on = "before-pull" }] [needs] -
Write the check, in
src/main.ts. Kiri calls it before every pull with the image’s name, and its answer decides whether the pull goes ahead:import { plugin } from "@kiri/sdk"; function pinned(image: string): boolean { if (image.includes("@sha256:")) return true; const last = image.split("/").pop() ?? ""; return last.includes(":") && !last.endsWith(":latest"); } plugin.check("before-pull", (ev) => { if (pinned(ev.image)) return plugin.allow(); return plugin.block(`${ev.image} has no fixed version. Name one, such as nginx:1.27-alpine.`); });It looks only at the last part of the name, so a registry with a port, such as
localhost:5000/app, still counts as having no tag. An image pinned by digest is fine. -
Build it and install it for yourself.
kiri plugin devbuilds the WebAssembly, shows you the install prompt once, then builds and loads it again each time you save. Leave it running in its own terminal. -
Pull something, from any terminal or from the window.
$ kiri plugin dev
no-latest 1.0.0 by your-name · fits Kiri 1.0 and later
Blocks pulls of images with no fixed version (no tag, or :latest).
From a folder · not signed
Where it shows:
• Check before pull and answer allow, warn or block
What it may see and reach:
• No internet
It runs as WebAssembly in Kiri's Linux side, only when Kiri calls it.
It can't see your files, the Docker socket or your other plugins.
Install? [y/N] y
✓ built in 0.4 s · WebAssembly 212 KB
✓ no-latest loaded. Watching src/ and kiri-plugin.toml. Ctrl+C stops watching.
14:03:40 ✓ no-latest check before pull nginx: block
14:03:52 ✓ no-latest check before pull nginx:1.27-alpine: allow$ docker pull nginx
Error response from daemon: no-latest blocked this pull: nginx has no fixed version. Name one, such as nginx:1.27-alpine.
$ docker pull nginx:1.27-alpine
1.27-alpine: Pulling from library/nginx
Status: Downloaded newer image for nginx:1.27-alpine
docker.io/library/nginx:1.27-alpineThe check holds for every pull that reaches Kiri’s engine: docker and Compose in a terminal, the window’s Pull image, and a CI job. If you’d rather go ahead once, the window offers Pull anyway, and kiri pull nginx --anyway does the same; both go in the activity record. Checks has the rest.
Add a note to the status bar
A note in the status bar is a place in the window, so it’s a permission of its own. Add it to the file, and have the check count today’s blocks in the plugin’s own small store.
[window]
status = true
plugin.check("before-pull", async (ev, kiri) => {
if (pinned(ev.image)) return plugin.allow();
const key = "blocked:" + new Date().toISOString().slice(0, 10);
const n = Number((await kiri.store.get(key)) ?? 0) + 1;
await kiri.store.set(key, String(n));
await kiri.status.set({ text: `${n} blocked today`, tone: "warning", lines: [`Last: ${ev.image}`] });
return plugin.block(`${ev.image} has no fixed version. Name one, such as nginx:1.27-alpine.`);
});
Save both files. kiri plugin dev notices that the plugin now asks for more than you agreed to, and asks again before it loads the new build. A plugin you install from the marketplace does the same when an update asks for more.
↻ kiri-plugin.toml changed
It now also asks to:
• Show a note in the status bar
Allow? [y/N] y
✓ built in 0.3 s · reloaded
14:06:12 ✓ no-latest check before pull redis: block
14:06:12 ✓ no-latest status: "1 blocked today"If you’d added kiri.status.set to the code but not status = true to the file, the build would still load, and the call would fail with a RefusedError that names the line it needs. kiri plugin dev prints every refused call, so you see it at once.
Images
Test it
kiri plugin test runs your plugin against jobs you write down, with the answers you expect, in the same box and with the same pass it gets when installed. The files go in tests/ and look the same whatever language the plugin is in.
# tests/no-latest.toml
[[case]]
name = "no tag is blocked"
job = { check = "before-pull", image = "nginx" }
expect = { verdict = "block" }
[[case]]
name = ":latest is blocked"
job = { check = "before-pull", image = "ghcr.io/example/api:latest" }
expect = { verdict = "block" }
[[case]]
name = "a registry port isn't a tag"
job = { check = "before-pull", image = "localhost:5000/app" }
expect = { verdict = "block" }
[[case]]
name = "a pinned tag goes through"
job = { check = "before-pull", image = "nginx:1.27-alpine" }
expect = { verdict = "allow", status = "" }
$ kiri plugin test
no-latest 1.0.0 · 4 cases
✓ no tag is blocked
✓ :latest is blocked
✓ a registry port isn't a tag
✓ a pinned tag goes through
4 passed in 0.3 sTest and publish has the whole test file format: fake containers and images, canned answers from websites, and checks on what the plugin put in the status bar.
Give it to someone
When you’re happy with it, stop kiri plugin dev with Ctrl+C. The plugin stays installed; kiri plugin rm no-latest takes it away.
To hand it to someone, build it into an image and push it to a registry they can reach. They install it by name and read the same prompt you did.
$ kiri plugin build --tag registry.example.com/team/no-latest:1.0.0
✓ no-latest 1.0.0 · WebAssembly 214 KB
✓ built registry.example.com/team/no-latest:1.0.0
sha256:9c41e07b52f3…
$ kiri push registry.example.com/team/no-latest:1.0.0
# on their computer
$ kiri plugin install registry.example.com/team/no-latest:1.0.0A plugin from a registry installs by digest, so they run exactly what you built. To put it in front of everyone who uses Kiri, publish it to the marketplace instead: see Test and publish.
Other languages
A plugin can be written in any of the SDK’s four languages: TypeScript, Go, Rust or Python. kiri plugin new takes --lang typescript, go, rust or python, and the handlers have the same names in each. Rust and Go plugins are the smallest and start fastest, which matters for a check that runs on every pull. The same check in each:
package main
import (
"strings"
"runkiri.com/go/kiri/plugin"
)
func main() {
plugin.Check("before-pull", func(ev plugin.CheckEvent, k *plugin.Kiri) plugin.Verdict {
if pinned(ev.Image) {
return plugin.Allow("")
}
return plugin.Block(ev.Image + " has no fixed version. Name one, such as nginx:1.27-alpine.")
})
plugin.Run()
}
func pinned(image string) bool {
if strings.Contains(image, "@sha256:") {
return true
}
parts := strings.Split(image, "/")
last := parts[len(parts)-1]
return strings.Contains(last, ":") && !strings.HasSuffix(last, ":latest")
}use kiri::plugin;
fn main() {
plugin::check("before-pull", |ev, _kiri| async move {
if pinned(&ev.image) {
return plugin::allow("");
}
plugin::block(format!("{} has no fixed version. Name one, such as nginx:1.27-alpine.", ev.image))
});
plugin::run();
}
fn pinned(image: &str) -> bool {
if image.contains("@sha256:") {
return true;
}
let last = image.rsplit('/').next().unwrap_or("");
last.contains(':') && !last.ends_with(":latest")
}import { plugin } from "@kiri/sdk";
function pinned(image: string): boolean {
if (image.includes("@sha256:")) return true;
const last = image.split("/").pop() ?? "";
return last.includes(":") && !last.endsWith(":latest");
}
plugin.check("before-pull", (ev) => {
if (pinned(ev.image)) return plugin.allow();
return plugin.block(`${ev.image} has no fixed version. Name one, such as nginx:1.27-alpine.`);
});from kiri import plugin
def pinned(image: str) -> bool:
if "@sha256:" in image:
return True
last = image.split("/")[-1]
return ":" in last and not last.endswith(":latest")
@plugin.check("before-pull")
def no_latest(ev, kiri):
if pinned(ev.image):
return plugin.allow()
return plugin.block(f"{ev.image} has no fixed version. Name one, such as nginx:1.27-alpine.")Go and Rust register their handlers in main and finish with plugin.Run(); TypeScript and Python register them when the file loads. The kiri-plugin.toml is the same for all four, apart from the path in [run] wasm.
© 2026 Kiri · The SDK is open source under the Apache License 2.0 · Docs · runkiri.com