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.")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
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
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 stoppedpub 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 stoppedname 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
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 Failedtargets 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
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
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
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
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>): voidfunc 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" }] })),
} },
];
});
Scans
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.
$ 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