Kiri Developers

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:

zsh
$ 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] y

Who 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.

From kiri-plugin.toml to the prompt and the passkiri-plugin.toml[adds][window][needs][[settings]]The install prompt• Be a place to deploy: Coolify• Add a tab to: Compose projects• Reach the address you type• Use a token, without reading itThe passthe same lines,checked on every callyeshello: column on imagesrefused: not listed
One file, three uses. Each table in kiri-plugin.toml becomes lines of the install prompt you read, and the same lines become the plugin's pass, which the gate checks on every call. Code that registers something the file doesn't list is refused when the plugin starts.
  • 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 RefusedError that 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.
Kiri
KiriModulesUSBSharePluginsSettingsCoolifyAppsServersDeploys

coolify 1.0.0

OverviewPermissionsWhat’s newReviews
Where it shows
Be a place to deploy: Coolify[adds] deploy
Send a project’s .env values to itenv = true
Add a tab to: Compose projects[window] tabs
Show a note in the status bar[window] status
What it may see and reach
Reach the address you typeserver · reach
Use a token, without reading ittoken · secret
After install, the same lines on the plugin's Permissions tab in the Plugins view, grouped as in the prompt. Here each is labelled with the key in kiri-plugin.toml it comes from. Nothing shows that the file doesn't list.

kiri plugin check reads the file and the built code together, and tells you what doesn’t match before anyone sees a prompt:

zsh
$ 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