PLUGINS
kiri-plugin.toml
Every plugin has a kiri-plugin.toml at the top of its folder. It says who made the plugin, how it runs, what it adds to Kiri, where it shows in the window, what it may reach and which settings it needs. Kiri reads it three times: to write the install prompt, to give the plugin its pass, and to check the code when the plugin starts. A plugin can do what this file lists, and nothing else.
A full file
This is the file of the Coolify plugin that comes with Kiri. It uses most of the keys.
# Who it is
name = "coolify"
version = "1.0.0"
publisher = "kiri"
description = "Deploy to › Coolify: a Compose project to your own Coolify server."
api = "1"
price = "free"
homepage = "https://coolify.io"
licence = "Apache-2.0"
mark = { icon = "coolify.svg", colour = "#6B16ED" }
# How it runs: WebAssembly, only when Kiri calls it
[run]
wasm = "dist/coolify.wasm"
memory = "64MB"
# What it adds to Kiri
[adds]
deploy = [{ name = "coolify", label = "Coolify", env = true }]
actions = [{ name = "open", on = "compose-project", label = "Open in Coolify" }]
commands = [
{ name = "apps", help = "List your Coolify apps" },
{ name = "servers", help = "List your Coolify servers" },
{ name = "logs", help = "Show an app's logs", args = "APP" },
]
# Where it shows in the window
[window]
status = true
tabs = [{ on = "compose-project", label = "Coolify" }]
facts = ["compose-project"]
section = { name = "Coolify", pages = ["Apps", "Servers", "Deploys"], settings = true }
notices = true
notifications = true
# What it may reach: nothing beyond the address you type below
[needs]
# What it asks you for, in Settings → Deploy
[[settings]]
key = "server"
label = "Server address"
help = "Such as https://coolify.example.com"
type = "url"
required = true
reach = true
[[settings]]
key = "token"
label = "API token"
help = "Paste a token from Coolify › Keys"
type = "secret"
required = true
for = "server"
[lang]
dir = "lang"
Its install prompt reads, line by line:
$ kiri plugin install coolify
coolify 1.0.0 by Kiri ✓ · Free · fits Kiri 1.0 and later
Deploy to › Coolify: a Compose project to your own Coolify server.
From the marketplace · signed by Kiri ✓
Where it shows:
• Be a place to deploy: Coolify. Get a project's compose file after Kiri
builds and pushes it
• Send a project's .env values to it, after you agree for that project
• Add items to the menu of: Compose projects
• Add commands: kiri plugin coolify apps, servers, logs
• Show a note in the status bar
• Add a tab to: Compose projects
• Add a line to the top of: Compose projects
• Show notices in the window
• Send system notifications, if you switch them on
What it may see and reach:
• Reach the address you type in its settings
• Use a token you type, without reading it
After install it asks for: Server address, API token.
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
Add its own section to the sidebar: Coolify, 3 pages? [Y/n] yWho it is, and how it runs
The top of the file
| Key | Type | Required | What it is |
|---|---|---|---|
name |
text | yes | Lowercase letters, digits and hyphens, up to 40 characters. The name in kiri plugin commands, the activity record and the marketplace. It can’t be one of kiri plugin’s own verbs: search, install, ls, show, set, update, enable, disable, rm, activity, logs, hide, unhide, request, new, dev, check, test, build, key, publish. |
version |
text | yes | A version such as 1.2.0. Each version you publish must be higher than the last. |
publisher |
text | yes | Who made it. The prompt shows it as “by …”, with the publisher’s rank once it’s in the marketplace. |
description |
text | no | One sentence, up to 160 characters, shown in the prompt, the Plugins view and the marketplace. |
api |
text | no | The plugin API major version it was written for. Kiri 1.x serves API "1", the default. A plugin that asks for an API this Kiri doesn’t serve won’t install, and the marketplace doesn’t offer it. |
price |
"free" or "account" |
no | "free", the default, or "account": the plugin needs an account with its maker. The marketplace labels it Paid · needs an account with the maker. Installing is always free. |
homepage |
URL | no | The maker’s page, linked from the listing. |
licence |
text | no | An SPDX name, such as Apache-2.0 or MIT. |
mark |
table | no | icon: a one-colour SVG in the plugin’s folder, such as your product’s logo, up to 8 KB. colour: the tile behind it, one of blue, teal, green, yellow, orange, pink, violet or grey, or a colour such as "#F38020". letters: one or two capital letters, used when there’s no icon. Kiri draws the mark beside everything the plugin adds. With no mark, Kiri uses the first two letters of name on grey. |
Your icon is a shape, not a picture. Kiri reads only its outline, draws it in white on your tile, and refuses an SVG with scripts, images, links or fonts in it. Kiri’s own icons never sit on a tile, so a plugin’s mark can’t pass for one of them. A colour too light for white to read on is darkened.
[run]
Exactly one of wasm or image.
| Key | Type | Default | What it means |
|---|---|---|---|
wasm |
path | A WebAssembly plugin. Kiri compiles it for your computer once, at install, and runs it in its WebAssembly runtime in Kiri’s Linux side only while it calls it. | |
image |
path or reference | A plugin that needs a real program. "Dockerfile" builds the image when you build the plugin; "registry.example.com/x@sha256:…" uses a published image, pinned by digest. Kiri runs it as a container of its own. |
|
memory |
size | "64MB" for WebAssembly, "256MB" for a container |
The most memory it may use. WebAssembly up to "256MB", a container up to "1GB". A container also gets 128 processes and a 64 MB scratch folder. |
while |
"sharing", "deploying" or "on" |
while a job of its runs | Containers only: when Kiri runs it. "sharing" from your first share through it to your last; "deploying" while a deploy runs; "on" the whole time the plugin is switched on. |
cache |
size | none | Containers only: a folder that survives restarts, for something worth keeping such as a scanner’s vulnerability database. Up to "2GB". Its path is in KIRI_CACHE. Removing the plugin deletes it. |
How plugins run explains the two kinds of box.
What it adds: [adds]
Things the plugin adds to Kiri’s own features, which also work from a terminal and in CI.
| Key | What each entry holds | Line in the prompt |
|---|---|---|
share |
{ name, label, note }. name is the word for kiri share --via (letters, digits, hyphens; unique among your plugins, or Kiri asks for --via plugin/way). label is the words in Share with ›, up to 32 characters. note is a few grey words beside it, such as “no account”. |
Be a way to share: labels. Reach the port you share, only while it is shared |
deploy |
{ name, label, env }. name is the word for kiri deploy --to, label the words in Deploy to ›. env = true asks to receive a project’s .env values. |
Be a place to deploy: label. Get a project’s compose file after Kiri builds and pushes it. With env, a second line: Send a project’s .env values to it, after you agree for that project |
scan |
{ name, label }. name is the word for kiri scan --with, label the words in Scan with ›. |
Be a scanner: label, in Scan with ›. See the packages in an image you scan |
checks |
{ on, timeout }. on is "before-pull", "before-build" or "before-run". timeout is how long Kiri waits for an answer: "2s" unless set, at most "10s". |
Check before pull (, build, run) and answer allow, warn or block |
actions |
{ name, on, label, when, from, label_key, ask }. See below. |
Add items to the menu of: kinds |
commands |
{ name, help, args }. name becomes kiri plugin <plugin> <name>; help is one line for --help; args names the arguments, such as "APP" or "[IMAGE...]". |
Add commands: kiri plugin name a, b, c |
An action is a menu item, and also a command (kiri plugin coolify open shop):
| Field | Required | What it is |
|---|---|---|
name |
yes | The handler’s name in the code, and the command’s name. |
on |
yes | The kind of thing whose menu it joins: "container", "compose-project", "compose-service", "image", "volume" or "build". |
label |
yes | The words in the menu, up to 32 characters. |
when |
no | Containers and Compose services: "running", "stopped" or "any" (the default). |
from |
no | Images: only images whose name starts with this, such as "ghcr.io/example/". |
label_key |
no | Containers, services and projects: only those with this Docker label, such as "com.example.deploy". |
ask |
no | A question Kiri asks before the item runs, such as "Restart {name} on the server?". Kiri shows it with the plugin’s name. Use it for anything that changes something. |
Where it shows: [window]
Each key is one place, and one line in the prompt. Plugins in the window has the rules for each.
| Key | Value | Line in the prompt |
|---|---|---|
status |
true |
Show a note in the status bar |
tabs |
[{ on, label }]. on: "container", "compose-project", "image" or "build". label up to 16 characters. One tab per kind. |
Add a tab to: kinds |
facts |
A list of the same kinds. One line per kind at the top of that page. | Add a line to the top of: kinds |
columns |
[{ on, label }]. on: "containers", "compose", "images" or "volumes". label up to 12 characters. One column per list. |
Add a column to: lists |
page |
{ label }, up to 20 characters. |
Add a page to the sidebar: label |
section |
{ name, pages, settings }. name up to 20 characters; pages, two to five names; settings = true puts a settings button on the heading. |
Add its own section to the sidebar: name, n pages (asked as a question of its own) |
notices |
true |
Show notices in the window |
notifications |
true |
Send system notifications, if you switch them on |
A plugin has a page or a section, never both. There’s no key for the Mac menu bar or the Windows notification area: plugins don’t add to either.
What it may reach: [needs], and [[settings]]
[needs]
Leave out what the plugin doesn’t need. An empty [needs] is a plugin that answers the jobs Kiri gives it and reaches nothing.
| Key | Value | Line in the prompt |
|---|---|---|
containers |
"read" |
See your containers: names, images, state and ports (not their settings or secrets) |
"manage" |
See, start and stop your containers (never remove them) | |
images |
"read" |
See your images: names, IDs, sizes and dates |
"packages" |
See your images and the packages inside them (not their files) | |
events |
A list of events: "image.pulled", "image.built", "image.removed", "container.started", "container.stopped", "share.live", "share.ended", "deploy.live", "deploy.failed". Image events need images, the others containers. The plugin’s own plugin.switched-off and plugin.removing need no listing. |
Hear when: the events, in words |
sites |
Host names, written out in full, such as "api.cloudflare.com". A port after a colon, as in "region1.v2.argotunnel.com:7844", allows only that port. A * may stand for the start of a name under a domain the plugin names, as in "derp*.tailscale.com", never for a whole domain. |
Reach these websites: hosts. With no sites: No internet |
Your computer, your local network and other private addresses are never reachable, whatever sites says.
[[settings]]
One table per field. Kiri draws the fields in the plugin’s settings pane, keeps the values, and puts secrets in your system’s keychain. See Settings and notices.
| Field | What it is |
|---|---|
key |
The name the code reads with kiri.settings.get. Letters, digits and underscores. |
label |
The field’s name in the pane, up to 32 characters. |
help |
One line under the field. |
type |
"text", "url", "number", "switch", "choice" or "secret". |
default |
The value before you set one. Not for secrets. |
choices |
For "choice": the list to pick from. |
required |
true if the plugin can’t work without it. Kiri shows Set up until it’s filled. |
reach |
For "url": true adds the address you type to what the plugin may reach. Line: Reach the address you type in its settings. |
for |
For "secret": where Kiri may send it. The key of a "url" setting, or a host from sites. |
header |
For "secret": how Kiri adds it to requests. "Authorization: Bearer {}" unless set; {} stands for the secret. |
use |
For "secret": "header", the default, or "program". Line for "header": Use a token you type, without reading it. Line for "program": Read a key you type, to start its program. |
env |
For use = "program": the environment variable the plugin’s container gets it in, such as "TS_AUTHKEY". Containers only. |
A "header" secret never reaches the plugin’s code: Kiri adds it to the plugin’s requests to the one place for names. A "program" secret is handed to the plugin’s container when it starts, because a program such as tailscaled needs the key itself. That’s why it has a line of its own in the prompt, and why a company can refuse plugins that ask for one.
[lang]
| Key | What it is |
|---|---|
dir |
A folder of translations, one file per language: lang/de.toml, lang/ja.toml. Each maps the English words in this file and in the code to that language. |
Kiri tells the plugin which language the window uses, and shows its labels in that language when the plugin has a file for it, in English otherwise. Plugin words never go through Kiri’s own dictionary.
The file is the whole truth
Kiri builds three things from this file, and the code can’t add to any of them.
- The prompt. Every line you read before you install comes from this file, so the prompt is complete. Nothing in the code can add a line.
- The pass. When you say yes, the same lines become the plugin’s pass. The gate checks every call the plugin makes against it, and a call it doesn’t allow fails with a
RefusedErrorthat names the permission. - The start. When the plugin starts, it says what its code registered: its checks, ways to share, menu items, tabs. Anything the file doesn’t list is refused there and then, and written in the activity record.
coolify 1.0.0
kiri plugin check reads the file and the built code together, and tells you what doesn’t match before anyone sees a prompt:
$ kiri plugin check
coolify 1.0.0 · WebAssembly · 1.1 MB
✓ kiri-plugin.toml
✓ settings: token goes only to server
✗ src/main.ts registers plugin.column("images"), but kiri-plugin.toml has no column on images.
Add under [window]: columns = [{ on = "images", label = "…" }]
✗ commands: "logs" is listed, but nothing handles it.
· [needs] events lists deploy.failed, but nothing listens for it.
2 problems, 1 note. Nothing was installed.© 2026 Kiri · The SDK is open source under the Apache License 2.0 · Docs · runkiri.com