PLUGINS
Plugins overview
A plugin adds something to Kiri itself: a way to share, a place to deploy, a scanner, a check before a pull, an item in a menu, a note in the status bar. You write it with the Kiri SDK, in Go, Rust, TypeScript or Python, and it lives in a folder with two things in it: a kiri-plugin.toml that says what the plugin adds and what it needs, and your code. Kiri’s engine loads it, so it works the same in the window, in a terminal, on a server and in CI.
A plugin and a module
The SDK writes two things. A module is your own program, such as a web service, that Kiri runs beside your containers. A plugin changes Kiri for everyone who installs it.
| A module | A plugin | |
|---|---|---|
| What it is | Your workload: a service Kiri runs for you | A part of Kiri: a way to share, a check, a tab |
| Its file | kiri.yaml |
kiri-plugin.toml |
| How it starts | kiri run . |
kiri plugin install, then Kiri calls it when there’s a job |
| Who reads its permissions | You, because it’s your code | Anyone who installs it, in the install prompt |
| Secrets | Reads the secrets you set for it | Never reads a token: Kiri adds it to requests to one site |
| SDK calls | kiri.Serve, kiri.DB and the rest of the six calls |
plugin.check, plugin.share and the rest of the plugin API |
Both are WebAssembly by default, in the same runtime, and both are held to their file. The two files differ because a plugin’s file is a list someone else reads before they say yes: every line in it becomes one line of the install prompt. If you’re building something for your own app, write a module. If you want Kiri to do something new, write a plugin.
From a folder to other people’s Kiri
Six commands take a plugin from nothing to the marketplace, and each runs in Kiri, on your computer or in CI. You don’t install Node.js, a WebAssembly toolchain or anything else: kiri plugin builds in Kiri’s own builder.
$ kiri plugin new no-latest --lang typescript
✓ wrote kiri-plugin.toml, src/main.ts, tests/ and the build setup
$ kiri plugin dev # build, show the prompt once, install for you, reload on save
$ kiri plugin check # the file and the code agree, every label fits
$ kiri plugin test # tests/*.toml, in the same box and with the same pass
$ kiri plugin key create # once: your publisher name and a signing key
$ kiri plugin publish # check, test, build, sign, uploadYour first plugin goes through all of it with a check that blocks images with no fixed version. Test and publish, Review and the marketplace cover the second half.
How your plugin runs
Kiri asks, and your plugin answers. Kiri sends a job, such as a check before a pull, a share to open or a click on your menu item, and calls the handler you registered for it. Each handler gets kiri, a client that carries your plugin’s pass: the calls its kiri-plugin.toml allows, and nothing else. Every call goes through Kiri’s permission gate, which lets it through or refuses it with an error that names the permission line it needed.
A plugin runs in one of two boxes, and [run] in kiri-plugin.toml picks which. Most plugins should be WebAssembly. Use a container only when the job needs a real program that can’t be WebAssembly, such as cloudflared or grype.
Each handler has a time to answer: a check 2 seconds (up to 10 with timeout), a tab or page 5 seconds, an action 30 seconds, a scan 5 minutes, and a share, deploy or command as long as the job lasts. When time runs out, Kiri goes on without the answer and writes it down. An error your handler doesn’t catch ends that one job only. The Plugin API has the full table.
A WebAssembly plugin always runs in Kiri’s Linux side, so it behaves the same on a Mac, on Windows and on Linux. There’s no key for the system and no call that says which one it is: test once and it holds on all three.
Where a plugin shows
A plugin never gets a panel to fill as it likes. It names the places it wants in its file, each place is a line of the install prompt, and Kiri draws what the plugin sends there in Kiri’s own look: notes, menu items, tabs, pages, columns, a choice in Share with ›, Deploy to › or Scan with ›, settings, notices, and checks. No HTML, script, picture or font from a plugin ever enters the window, so its pages follow the person’s theme, text size and language direction, and can’t pass for part of Kiri.
Every place shows them all on one window, with the key, the call and the limits for each. A plugin doesn’t have to show in the window at all: a check with no screen is a complete plugin.
Ask for less
There’s no “everything” permission. A plugin starts with none and gets only what its file lists and the person accepted. Every line you add is a line someone reads before they say yes, and a line a company can block for all its people.
- Name only the places you use. A check needs no note; a note needs no page.
- List each website in full.
api.tailscale.com, not every name under a domain. With no list, the prompt says No internet, which is the easiest line to say yes to. - Use tokens without reading them. A secret with
use = "header"is added to your requests by Kiri; your code never sees it. Ask foruse = "program"only when a program of yours must read the key itself. - See, don’t manage.
containers = "read"is enough to show state. Ask for"manage"only to start and stop.
An update that asks for more waits for every person who has your plugin to say yes, and waits for review in the marketplace first. An update that asks for the same or less installs quietly.
What a plugin can never do
Whatever its file lists, a plugin can’t:
- run code on the person’s Mac or PC. It runs in Kiri’s Linux side, in its own box;
- open the Docker socket, or use the engine except through the calls its pass allows;
- see files or folders. A scanner gets the list of packages in an image, never the image’s files;
- see a container’s settings, environment or mounts. With permission to see containers, it sees their names, images, state and ports;
- remove a container, an image or a volume;
- read a token it’s given, unless its prompt said “Read a key you type, to start its program”;
- reach containers, except the one port shared through it, and only while it’s shared;
- reach the person’s computer, another plugin or another machine on their network;
- reach a website that isn’t on its list;
- put its own web page, script or picture in Kiri’s window (its icon is a shape Kiri draws on its tile);
- add a second Share, Deploy or Scan button. It joins Kiri’s menu for that;
- add anything to the Mac menu bar or the Windows notification area;
- take more permissions in an update without asking first.
The person’s side of these rules, what they see in the prompt and the activity record, will be in the Kiri docs when 1.0 ships: Plugins, Permissions and How plugins run.
© 2026 Kiri · The SDK is open source under the Apache License 2.0 · Docs · runkiri.com