Kiri Developers

PLUGINS

Plugin API reference

The plugin part of the Kiri SDK has two halves. Handlers are functions you register on plugin: Kiri calls one when there’s a job for it, such as a check before a pull or a click on a menu item. The client, kiri, is handed to every handler and carries the plugin’s pass, so it can make only the calls the plugin’s permissions allow. Every handler needs its key in kiri-plugin.toml; a handler the file doesn’t list is refused when the plugin starts.

Packages and the shape of a plugin

Language Package Import
TypeScript and JavaScript @kiri/sdk import { plugin } from "@kiri/sdk";
Go runkiri.com/go/kiri import "runkiri.com/go/kiri/plugin"
Rust kiri use kiri::plugin;
Python kiri from kiri import plugin

TypeScript and Python register handlers when the file loads. Go and Rust register them in main and end with plugin.Run() or plugin::run(). The names are the same everywhere, in each language’s style: plugin.check in TypeScript, plugin.Check in Go, plugin::check in Rust, @plugin.check in Python, which uses snake_case and registers handlers with decorators. Each signature below follows the language picker at the top of the page; the full types are written out in TypeScript, and the other languages carry the same fields in their own style (ev.Image in Go, ev.image in Rust and Python).

import { plugin } from "@kiri/sdk";

plugin.check("before-pull", (ev) => {
  const last = ev.image.split("/").pop() ?? "";
  if (ev.image.includes("@sha256:") || (last.includes(":") && !last.endsWith(":latest"))) return plugin.allow();
  return plugin.block(`${ev.image} has no fixed version.`);
});
import "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.")
	})
	plugin.Run()
}
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.", ev.image))
    });
    plugin::run();
}
from kiri import plugin

@plugin.check("before-pull")
def no_latest(ev, kiri):
    last = ev.image.split("/")[-1]
    if "@sha256:" in ev.image or (":" in last and not last.endswith(":latest")):
        return plugin.allow()
    return plugin.block(f"{ev.image} has no fixed version.")
A job’s round tripKiri’s enginecontainers, images,the windowThe gatechecks the passthe plugin’s boxplugin.check(…)1 job: before-pull nginx2 images.getallowed3 containers.stopRefusedError4 answer: block, reasonactivity record
One job, there and back. Kiri gives the plugin a job; the handler may call back through the gate, which checks each call against the plugin's pass; then it answers. A call the pass doesn't allow comes back as a RefusedError, and both go in the activity record.

Each handler has a time to answer. When it runs out, Kiri stops waiting, treats the job as the table says, and writes it down.

Handler Time When time runs out
check 2 s, or the manifest’s timeout, up to 10 s Counts as warn, “didn’t answer in time”
action, settings.check 30 s, 10 s Kiri shows “Coolify didn’t answer”
tab, fact, column, page 5 s Kiri keeps what it last drew
scan 5 min The scan fails with the reason
on 10 s Dropped
share, deploy, command As long as the job lasts Ends when you stop it, or on Ctrl+C

Handlers

plugin.check

No Python version · showing TypeScript
type Hook = "before-pull" | "before-build" | "before-run";

plugin.check(hook: Hook, fn: (ev: CheckEvent, kiri: Kiri) => Verdict | Promise<Verdict>): void

interface CheckEvent {
  hook: Hook;
  image: string;            // as it was asked for: "nginx", "ghcr.io/example/api:1.4"
  platform: string;         // "linux/arm64"
  client: "docker" | "compose" | "window" | "kiri" | "api";
  build?: { name: string; base: string[] };   // before-build: the build's tag and its FROM images
  run?: { name: string; ports: number[] };    // before-run: the container's name and published ports
}
func Check(hook string, fn func(ev CheckEvent, k *Kiri) Verdict)

type CheckEvent struct {
	Hook, Image, Platform, Client string
	Build *struct{ Name string; Base []string } // before-build
	Run   *struct{ Name string; Ports []int }    // before-run
}
pub fn check<F, Fut>(hook: &str, f: F)
where F: Fn(CheckEvent, Kiri) -> Fut, Fut: Future<Output = Verdict>;

pub struct CheckEvent { pub hook: String, pub image: String, pub platform: String,
    pub client: String, pub build: Option<Build>, pub run: Option<Run> }

Answer with one of the three verdicts below. One block from any plugin stops the step; a warn lets it go ahead with the reason. See Checks.

plugin.share

No Python version · showing TypeScript
plugin.share(name: string, fn: (share: Share, kiri: Kiri) => Promise<void>): void

interface Share {
  id: string;
  target: { kind: "container" | "compose-service" | "pod" | "service"; name: string; port: number };
  addr: string;                  // "10.89.4.2:41022": a relay to that one port, open only while shared
  live(url: string): void;       // only once a person can open the address
  notice(text: string): void;
  reconnecting(why: string): void;
  ended(reason: string): void;
  signal: AbortSignal;           // aborts when you stop the share
}
func Share(name string, fn func(s *ShareJob, k *Kiri) error)

type ShareJob struct {
	ID     string
	Target struct{ Kind, Name string; Port int }
	Addr   string // a relay to that one port, open only while shared
}
func (s *ShareJob) Live(url string)
func (s *ShareJob) Notice(text string)
func (s *ShareJob) Reconnecting(why string)
func (s *ShareJob) Ended(reason string)
func (s *ShareJob) Done() <-chan struct{} // closed when the share is stopped
pub fn share<F, Fut>(name: &str, f: F)
where F: Fn(Share, Kiri) -> Fut, Fut: Future<Output = Result<()>>;

// Share: id, target, addr, live(url), notice(text), reconnecting(why),
// ended(reason), and signal: a token cancelled when the share is stopped

name is one of the plugin’s [adds] share names. Kiri reports Connecting as soon as it hands over the job. When fn returns without calling ended, Kiri ends the share with “the plugin stopped”. Only Kiri Share reports each request, so there’s no request here. See Share, deploy, scan.

plugin.deploy

No Python version · showing TypeScript
plugin.deploy(name: string, place: {
  targets: (kiri: Kiri) => Promise<DeployTarget[]>;
  run: (deploy: Deploy, kiri: Kiri) => Promise<void>;
}): void

interface DeployTarget { name: string; label: string; arch?: "amd64" | "arm64"; note?: string } // no arch: Kiri asks once

interface Deploy {
  id: string;
  project: string;
  target: DeployTarget;
  compose: string;                              // with image names in place of build: sections, already pushed
  env: Record<string, string> | null;           // only after you agree for this project
  git: { url: string; commit: string } | null;  // set when you deploy from git
  addresses: Record<string, string>;            // service → the address you chose for it, such as "web" → "shop.example.com"
  sending(): void;
  deploying(detail?: string): void;             // "db running · api running · web starting"
  live(urls: Record<string, string>): void;     // service → address
  failed(reason: string): void;
  log(line: string): void;
  signal: AbortSignal;
}
func Deploy(name string, p Place)

type Place struct {
	Targets func(k *Kiri) ([]DeployTarget, error)
	Run     func(d *DeployJob, k *Kiri) error // an error ends the deploy as Failed
}
type DeployTarget struct{ Name, Label, Arch, Note string }
// DeployJob: ID, Project, Target, Compose, Env, Git, Addresses,
// and Sending(), Deploying(detail), Live(urls), Failed(reason), Log(line), Done()
pub fn deploy(name: &str, place: Place);

pub struct Place { pub targets: TargetsFn, pub run: RunFn }
// run: Fn(Deploy, Kiri) -> impl Future<Output = Result<()>>; an Err ends it as Failed

targets lists what shows under the place in Deploy to ›, such as coolify:prod. Kiri reports Building and Pushing itself, building each service for the target’s arch, and calls run once the images are pushed. When you deploy from git, Kiri builds nothing: compose is the project’s own file and git says what to build.

plugin.scan

No Python version · showing TypeScript
plugin.scan(name: string, fn: (scan: Scan, kiri: Kiri) => Promise<Finding[]>): void

interface Scan { image: string; digest: string; platform: string; packages: CycloneDX; signal: AbortSignal }

interface Finding {
  id: string;                 // "CVE-2026-1234"
  package: string;
  version: string;
  severity: "critical" | "high" | "medium" | "low" | "unknown";
  fixed?: string;             // the version that fixes it
  title?: string;
}
func Scan(name string, fn func(s *ScanJob, k *Kiri) ([]Finding, error))

type ScanJob struct{ Image, Digest, Platform string; Packages BOM }
type Finding struct{ ID, Package, Version, Severity, Fixed, Title string }
pub fn scan<F, Fut>(name: &str, f: F)
where F: Fn(Scan, Kiri) -> Fut, Fut: Future<Output = Result<Vec<Finding>>>;

Kiri makes the image’s package list, a CycloneDX bill of materials, and hands it over; the scanner never sees the image’s files. The findings show on the image’s Security tab under the scanner’s name.

plugin.action and plugin.command

No Python version · showing TypeScript
plugin.action(name: string, fn: (target: Target, kiri: Kiri) => ActionResult | Promise<ActionResult>): void

interface Target {
  kind: "container" | "compose-project" | "compose-service" | "image" | "volume" | "build";
  name: string;
  id?: string;
  // plus what the plugin's see permissions allow: a container's image, state and ports
}
type ActionResult = void | Say | Open;

plugin.command(name: string, fn: (args: string[], out: Output, kiri: Kiri) => Promise<number | void>): void

interface Output {
  line(text: string): void;
  table(columns: string[], rows: string[][]): void;
  json(value: unknown): void;
  error(text: string): void;
}
func Action(name string, fn func(t Target, k *Kiri) Result)
func Command(name string, fn func(args []string, out *Output, k *Kiri) int)

// Result is Say(text), Open(Where{...}) or nil.
// Output: Line(text), Table(columns, rows), JSON(v), Error(text).
pub fn action<F, Fut>(name: &str, f: F)
where F: Fn(Target, Kiri) -> Fut, Fut: Future<Output = ActionResult>;
pub fn command<F, Fut>(name: &str, f: F)
where F: Fn(Vec<String>, Output, Kiri) -> Fut, Fut: Future<Output = i32>;

An action runs from the menu it joins, or as kiri plugin NAME ACTION TARGET. A command runs as kiri plugin NAME COMMAND ARGS; it returns its exit code, 0 if it returns nothing. Every command also takes --json, which turns table and line into JSON. See Menus and commands.

plugin.tab, fact, column and page

No Python version · showing TypeScript
type PageKind = "container" | "compose-project" | "image" | "build";
type List = "containers" | "compose" | "images" | "volumes";

plugin.tab(kind: PageKind, fn: (target: Target, kiri: Kiri) => Promise<Block[]>): void
plugin.fact(kind: PageKind, fn: (target: Target, kiri: Kiri) => Promise<Fact | null>): void
plugin.column(list: List, fn: (rows: Target[], kiri: Kiri) => Promise<Record<string, Cell>>): void
plugin.page(name: string, fn: (kiri: Kiri) => Promise<Block[]>): void

interface Fact { label: string; value: string; tone?: Tone }
interface Cell { text: string; tone?: Tone; sort?: number | string; tip?: string }
func Tab(kind string, fn func(t Target, k *Kiri) ([]Block, error))
func Fact(kind string, fn func(t Target, k *Kiri) (*FactLine, error))
func Column(list string, fn func(rows []Target, k *Kiri) (map[string]Cell, error))
func Page(name string, fn func(k *Kiri) ([]Block, error))
pub fn tab(kind: &str, f: impl Fn(Target, Kiri) -> impl Future<Output = Result<Vec<Block>>>);
pub fn fact(kind: &str, f: impl Fn(Target, Kiri) -> impl Future<Output = Result<Option<Fact>>>);
pub fn column(list: &str, f: impl Fn(Vec<Target>, Kiri) -> impl Future<Output = Result<HashMap<String, Cell>>>);
pub fn page(name: &str, f: impl Fn(Kiri) -> impl Future<Output = Result<Vec<Block>>>);

Kiri asks a tab or a page for its blocks when you open it, and asks again when the plugin calls kiri.refresh. A column gets the rows on screen and answers with a cell for each row’s name; a row with no cell stays empty. page’s name is the [window] page label, or one of the section’s pages. See Tabs, pages and columns.

plugin.settings.check and plugin.on

No Python version · showing TypeScript
plugin.settings.check(fn: (values: Settings, kiri: Kiri) => Promise<{ ok: boolean; text: string }>): void

type Event =
  | "image.pulled" | "image.built" | "image.removed"
  | "container.started" | "container.stopped"
  | "share.live" | "share.ended" | "deploy.live" | "deploy.failed"
  | "plugin.switched-off" | "plugin.removing";

plugin.on(event: Event, fn: (ev: EventData, kiri: Kiri) => void | Promise<void>): void
func SettingsCheck(fn func(v Settings, k *Kiri) CheckResult)
func On(event string, fn func(ev EventData, k *Kiri))
pub fn settings_check(f: impl Fn(Settings, Kiri) -> impl Future<Output = CheckResult>);
pub fn on(event: &str, f: impl Fn(EventData, Kiri) -> impl Future<Output = ()>);

settings.check puts Check connection in the plugin’s settings pane. It gets the values as typed, before they’re saved; a secret shows as { set: true }, and a kiri.http.fetch with secret uses the typed one.

on needs the event in [needs] events. Each event carries the names involved: image and digest for images, name and image for containers (and exit when one stops), target, via and url for shares, project, place and urls or reason for deploys.

Two events are about the plugin itself, so they need no permission and aren’t listed in [needs]. plugin.switched-off comes when you switch the plugin off, so it can stop its work cleanly. plugin.removing comes just before Kiri removes it, not when it’s only switched off. Either way the plugin has 10 s, with its usual permissions, to tidy what it made at its own services:

plugin.on("plugin.removing", async (ev, kiri) => {
  const id = await kiri.store.get("device-id");
  if (id) await kiri.http.fetch(`https://api.tailscale.com/api/v2/device/${id}`, { method: "DELETE", secret: "api_key" });
});

After 10 s, or when the handler returns, Kiri goes ahead. See Update and remove.

Go and Rust

In Go, a handler may block on the client’s calls; while it waits, Kiri can run other jobs. In Rust, handlers are async; Kiri is a cheap handle you can clone into a task.

Answers, blocks and cells

Answers

TypeScript Go Rust What it does
plugin.allow(reason?) plugin.Allow(reason string) plugin::allow(reason) Lets the step go ahead. A reason, if any, goes only in the activity record.
plugin.warn(reason) plugin.Warn(reason string) plugin::warn(reason) Lets it go ahead and shows the reason: a warning in docker’s output, a note on the step in the window.
plugin.block(reason) plugin.Block(reason string) plugin::block(reason) Stops it. docker prints “PLUGIN blocked this pull: reason”.
plugin.say(text) plugin.Say(text string) plugin::say(text) From an action: a notice with the plugin’s mark, up to 120 characters. Needs no notices permission, because you asked.
plugin.open({ page }) ({ tab }) ({ url }) plugin.Open(plugin.Where{...}) plugin::open(Where::Page(..)) From an action or a button: opens one of the plugin’s pages, its tab on the target’s page, or a web address in your browser (https or http only).

A reason is one sentence, up to 200 characters. Say what’s wrong and what to do instead.

Blocks

Tabs, pages and sections are lists of blocks. Kiri draws each block in its own look, with your theme, accent, text size and language direction, and works it from the keyboard. No HTML, script or picture from a plugin enters the window.

type Block =
  | { table: { columns: string[]; rows: Row[] } }
  | { tiles: { label: string; value: string; tone?: Tone }[] }      // up to four
  | { facts: [label: string, value: string][] }
  | { form: { fields: Field[]; submit: Button } }                   // fields as in [[settings]]
  | { log: { lines: string[]; follow?: boolean } }
  | { buttons: Button[] }                                            // up to three
  | { notice: { text: string; tone: Tone } }
  | { text: string }
  | { empty: { title: string; text: string; button?: Button } };

interface Row { key: string; cells: (string | Cell)[]; menu?: Button[] }   // menu: the row's ⋯
type Button = { label: string } & ({ page: string } | { tab: PageKind } | { action: string } | { url: string });
type Tone = "plain" | "good" | "warning" | "bad";

A button with action runs one of the plugin’s handlers by name, with the row’s key as the target when it’s in a row’s ⋯ menu. Here is a page, and what Kiri draws from it:

plugin.page("Scans", async (kiri) => {
  const rows = await scannedImages(kiri);           // your own code
  if (rows.length === 0) {
    return [{ empty: { title: "No scans yet", text: "Scan an image from its menu.", button: { label: "Open Images", url: "kiri://images" } } }];
  }
  return [
    { tiles: [
      { label: "Images", value: String(rows.length) },
      { label: "Critical", value: "3", tone: "bad" },
      { label: "With a fix", value: "2", tone: "warning" },
    ] },
    { table: {
      columns: ["Image", "Critical", "High", "Scanned"],
      rows: rows.map((r) => ({ key: r.image, cells: [r.image, { text: String(r.critical), tone: r.critical ? "bad" : "good" }, String(r.high), r.when], menu: [{ label: "Scan again", action: "rescan" }] })),
    } },
  ];
});
Kiri
KiriModulesUSBSharePluginsSettingsPlugins Scans

Scans

Images6
Critical3
With a fix2
ImageCriticalScanned
nginx:1.27210 min ago⋯
ghost:6110 min ago⋯
postgres:17010 min ago⋯
What Kiri draws from the blocks above: a page under the Plugins heading, with three number tiles and a table whose rows each have the plugin's ⋯ menu. The tones become Kiri's own colours.

kiri:// addresses open a place in Kiri’s own window: kiri://images, kiri://containers, kiri://settings/sharing. They’re the one kind of url that doesn’t open your browser.

The client

Every handler gets kiri. Each call checks the plugin’s pass; the right column says which permission it needs.

TypeScript

interface Kiri {
  status: {
    set(note: { text: string; tone?: Tone; lines?: string[]; buttons?: Button[] }): Promise<void>;
    clear(): Promise<void>;
  };
  notify(n: { text: string; kind?: "info" | "success" | "warning" | "error"; button?: Button; system?: boolean }): Promise<void>;
  refresh(place: "status" | "tab" | "fact" | "column" | "page"): Promise<void>;
  containers: {
    list(): Promise<Container[]>;
    get(name: string): Promise<Container>;
    start(name: string): Promise<void>;
    stop(name: string): Promise<void>;
  };
  images: {
    list(): Promise<Image[]>;
    get(ref: string): Promise<Image>;
    packages(ref: string): Promise<CycloneDX>;
  };
  http: { fetch(url: string, init?: RequestInit & { secret?: string }): Promise<Response> };
  settings: { get(key: string): Promise<Value>; all(): Promise<Record<string, Value>> };
  store: {
    get(key: string): Promise<string | Uint8Array | null>;
    set(key: string, value: string | Uint8Array): Promise<void>;
    delete(key: string): Promise<void>;
    list(prefix?: string): Promise<string[]>;
  };
  log: { info(msg: string, fields?: object): void; warn(msg: string, fields?: object): void; error(msg: string, fields?: object): void };
  lang: string;   // the window's language, such as "de" or "pt-BR"
}

interface Container { name: string; id: string; image: string; state: "created" | "running" | "paused" | "exited"; ports: { inside: number; outside?: number; proto: "tcp" | "udp" }[] }
interface Image { ref: string; id: string; size: number; created: string }
type Value = string | number | boolean | { set: boolean };   // a secret is only ever { set: true | false }
Call Needs What it does
status.set(note), status.clear() [window] status The plugin’s note: up to 24 characters, a tone, and up to five lines and two buttons for the panel a click opens. At most one change a second; faster ones are merged.
notify(n) [window] notices; with system: true, [window] notifications and your switch A notice in the window, up to 120 characters, with one button. One every 10 s per plugin. A system notification at most once a minute.
refresh(place) that place Asks Kiri to ask the plugin again for a tab, fact, column or page that’s on screen.
containers.list(), .get(name) [needs] containers = "read" Names, IDs, images, state and ports. Never settings, environment, mounts or labels.
containers.start(name), .stop(name) containers = "manage" Starts or stops one. There is no call to remove.
images.list(), .get(ref) images = "read" Names, IDs, sizes and dates.
images.packages(ref) images = "packages" The image’s package list as CycloneDX, made by Kiri. Never its files.
http.fetch(url, init) the host in sites, or the address in a reach setting Fetches like the standard fetch, through Kiri. secret: "token" asks Kiri to add that secret to the request as its header says, only if the URL is where its for points. Redirects are checked too.
settings.get(key), .all() none The plugin’s settings. A secret comes back as { set: true } or { set: false }, never its value.
store.get/set/delete/list none The plugin’s own small store, kept when it updates, deleted when you remove it. Keys up to 512 bytes, values up to 1 MB, 64 MB in all.
log.info/warn/error none The plugin’s log, shown by kiri plugin logs and kiri plugin dev.
lang none The window’s language, so the plugin can answer in it.

In Go and Rust

TypeScript Go Rust
kiri.status.set(note) k.Status.Set(plugin.Note{Text, Tone, Lines, Buttons}) error kiri.status().set(Note { .. }).await -> Result<()>
kiri.status.clear() k.Status.Clear() error kiri.status().clear().await -> Result<()>
kiri.notify(n) k.Notify(plugin.Notice{Text, Kind, Button, System}) error kiri.notify(Notice { .. }).await -> Result<()>
kiri.refresh(place) k.Refresh(place string) error kiri.refresh(Place::Tab).await -> Result<()>
kiri.containers.list() k.Containers.List() ([]plugin.Container, error) kiri.containers().list().await -> Result<Vec<Container>>
kiri.containers.get(name) k.Containers.Get(name string) (plugin.Container, error) kiri.containers().get(name).await -> Result<Container>
kiri.containers.start(name), stop k.Containers.Start(name string) error, Stop kiri.containers().start(name).await -> Result<()>, stop
kiri.images.list(), get(ref) k.Images.List() ([]plugin.Image, error), Get(ref string) kiri.images().list().await -> Result<Vec<Image>>, get(ref)
kiri.images.packages(ref) k.Images.Packages(ref string) (plugin.BOM, error) kiri.images().packages(ref).await -> Result<Bom>
kiri.http.fetch(url, init) k.HTTP().Do(req) with plugin.WithSecret(req, "token"); *http.Client kiri.http().get(url).secret("token").send().await -> Result<Response>
kiri.settings.get(key) k.Settings.Get(key string) (plugin.Value, error) kiri.settings().get(key).await -> Result<Value>
kiri.store.get(key), set, delete, list k.Store.Get(key string) ([]byte, bool, error), Set, Delete, List kiri.store().get(key).await -> Result<Option<Vec<u8>>>, set, delete, list
kiri.log.info(msg) k.Log() *slog.Logger log::info! after kiri::log::init()
kiri.lang k.Lang() string kiri.lang() -> &str

Errors

Error When Go Rust
RefusedError The pass doesn’t allow the call. Its message names the permission line it needs, such as “needs: See, start and stop your containers (never remove them)”. plugin.ErrRefused kiri::Error::Refused
UnavailableError A listed website or your setup address doesn’t answer, or the thing asked about is gone. plugin.ErrUnavailable kiri::Error::Unavailable
TimeoutError A client call took longer than the handler has left. plugin.ErrTimeout kiri::Error::Timeout

In TypeScript, all three come from @kiri/sdk; in Python they’re kiri.Refused, kiri.Unavailable and kiri.Timeout. Every RefusedError goes in the activity record with the permission it needed, whether your code catches it or not. An error your handler throws and doesn’t catch ends that job only: a check counts as warn, an action shows “the plugin failed”, and the reason goes in its log.

Container plugins and the door

A plugin with [run] image runs as a container of its own, and can be in any language. The SDK works there too, unchanged: inside a container it talks to the plugin’s door, an HTTP address on the plugin’s own network that takes only that plugin’s pass. Without the SDK, speak to the door yourself. Kiri starts the container with:

Variable What it holds
KIRI_DOOR The door’s address, such as http://10.89.4.1:7700.
KIRI_PASS The plugin’s pass. Send it as Authorization: Bearer on every request.
KIRI_LANG The window’s language.
a secret’s env A use = "program" secret, such as TS_AUTHKEY.
Request What it’s for
POST /v1/hello Says what the code handles, such as {"checks": ["before-pull"], "shares": ["cloudflare-quick"], "actions": ["open"]}. Kiri answers with anything it refused.
GET /v1/inbox?wait=30 Waits up to 30 s for the next job; 204 if none came.
POST /v1/jobs/ID/result The answer to a job, such as {"verdict": "block", "reason": "…"} or {"blocks": […]}.
POST /v1/jobs/ID/events A share’s, deploy’s or command’s progress: {"type": "live", "url": "https://…"}, {"type": "deploying", "detail": "…"}, {"type": "line", "text": "…"}.
GET /v1/containers, GET /v1/containers/NAME, POST /v1/containers/NAME/start or /stop kiri.containers.
GET /v1/images, GET /v1/images/REF, GET /v1/images/REF/packages kiri.images.
PUT /v1/status, DELETE /v1/status, POST /v1/notify, POST /v1/refresh The note, notices and redraws.
POST /v1/fetch kiri.http.fetch with a secret: {"url", "method", "headers", "body", "secret": "token"}. Kiri makes the request and adds the secret.
GET /v1/settings, GET PUT DELETE /v1/store/KEY, POST /v1/log Settings, the store and the log.

Jobs arrive as JSON with an id and a kind: check, share.start, share.stop, deploy.targets, deploy.run, scan, action, command, tab, fact, column, page, settings.check and event. Their fields are the TypeScript objects above.

sh, inside a container plugin
$ curl -s -H "Authorization: Bearer $KIRI_PASS" "$KIRI_DOOR/v1/inbox?wait=30"
{"id":"7f3a2c","kind":"check","hook":"before-pull","image":"nginx","platform":"linux/arm64","client":"docker"}
$ curl -s -H "Authorization: Bearer $KIRI_PASS" -d '{"verdict":"block","reason":"nginx has no fixed version."}' "$KIRI_DOOR/v1/jobs/7f3a2c/result"
$ curl -s -H "Authorization: Bearer $KIRI_PASS" -X POST "$KIRI_DOOR/v1/containers/web/stop"
{"error":"refused","needs":"See, start and stop your containers (never remove them)"}

The door is the plugin’s own. It’s not the engine’s API, which plugins never reach, and a pass from another plugin is refused at it. How plugins run explains the walls around it.

© 2026 Kiri · The SDK is open source under the Apache License 2.0 · Docs · runkiri.com