Kiri Developers

WINDOW PLACES

Share with, Deploy to and Scan with

Kiri already shares, deploys and scans. A plugin that does one of those jobs another way doesn’t get a button of its own: it becomes one more choice in Kiri’s menu for the job, Share with ›, Deploy to › or Scan with ›. Kiri draws the choice, runs the feature and shows the result where it always does. Your plugin does only the part in the middle, and reports its progress in the same steps every other plugin uses. What people see will be in the Kiri docs under Share, deploy, scan when 1.0 ships.

Who does what

Choice Your key Kiri does Your handler does It reports
Share with › [adds] share Opens a relay to the one port, shows the link in the Share view, ends it Puts the port on the internet or a tailnet Connecting, Live, Notice, Reconnecting, Ended
Deploy to › [adds] deploy Builds each image for the server’s chip and pushes it, rewrites the compose file Sends the project to the server and follows it until it’s live Building, Pushing (Kiri), Sending, Deploying, Live or Failed
Scan with › [adds] scan Lists the packages in the image, draws the findings on its Security tab Matches the packages against its list of known vulnerabilities Findings, or the reason it failed

Because every plugin answers in the same steps, the Share view, the Deploys tab, the status bar and the activity record work the same whichever plugin did the work. Each choice is also a command: kiri share --via, kiri deploy --to and kiri scan --with.

A way to share

List your ways under [adds] share. Each name is what kiri share --via takes, so it must be unique among the plugins someone has; label is the menu entry and note a few words beside it:

[adds]
share = [
  { name = "cloudflare-quick", label = "Cloudflare, quick link", note = "no account" },
  { name = "cloudflare", label = "Cloudflare, your domain" },
]

The prompt shows Be a way to share: Cloudflare, quick link; Cloudflare, your domain. Reach the port you share, only while it is shared. When someone shares, Kiri opens a relay to the one port they picked, only for this share, and hands your handler its address as share.addr. Your plugin never joins their containers’ network.

No Python version · showing TypeScript
plugin.share("cloudflare-quick", async (share, kiri) => {
  const url = await quickTunnel(share.addr, share.signal); // share.addr: the relay to the one port
  share.live(url);                                          // only once a person can open it
});
plugin.Share("cloudflare-quick", func(s *plugin.ShareJob, k *plugin.Kiri) error {
	url, err := quickTunnel(s.Addr, s.Done()) // s.Addr: the relay to the one port
	if err != nil {
		return err
	}
	s.Live(url) // only once a person can open it
	<-s.Done()  // closed when the share is stopped
	return nil
})
plugin::share("cloudflare-quick", |share, kiri| async move {
    let url = quick_tunnel(&share.addr, share.signal.clone()).await?; // the relay to the one port
    share.live(url);                                                   // only once a person can open it
    share.signal.cancelled().await;                                    // until the share is stopped
    Ok(())
});
A share through a pluginweb:80Kiria relay, for thisshare onlythe plugin’s boxplugin.shareits programInternetor a tailnet:80share.addrtunnelshare.live(url)stop: share.signal aborts, the relay closes
The path of a share through a plugin. Kiri opens a relay to the one port and gives the plugin its address. The plugin's program connects the relay to the outside, and calls live only once a person can open the link. Stopping the share aborts the plugin's signal, and Kiri closes the relay.

Report the share’s steps on the share object. Kiri says Connecting as soon as it hands over the job:

Call Step When
share.live(url) Live The address opens for a person, now. Never earlier: the link someone clicks must work the first time.
share.notice(text) Notice Something they should know, such as “the address is slow to appear”.
share.reconnecting(why) Reconnecting The connection dropped and you’re getting it back.
share.ended(reason) Ended The share stopped, with the reason. If your handler returns without it, Kiri ends the share with “the plugin stopped”.

When the share is stopped, Kiri aborts share.signal, closes the relay and checks the port no longer answers. Only Kiri Share sees each visit, so there’s no request list for a plugin to fill. The Cloudflare and Tailscale example is the whole thing.

A place to deploy

List your places under [adds] deploy. With env = true, your plugin may receive a project’s .env values, after the person agrees for that project:

[adds]
deploy = [{ name = "coolify", label = "Coolify", env = true }]

The prompt shows Be a place to deploy: Coolify. Get a project’s compose file after Kiri builds and pushes it, and with env also Send a project’s .env values to it, after you agree for that project. Your place has two parts: targets, the entries under it in Deploy to ›, and run, called once Kiri has built and pushed the images:

No Rust version · showing TypeScriptNo Python version · showing TypeScript
plugin.deploy("coolify", {
  targets: async (kiri) => [
    { name: "prod", label: "Coolify · prod", arch: "amd64" },
    { name: "staging", label: "Coolify · staging" },          // no arch: Kiri asks once
  ],
  run: async (deploy, kiri) => {
    deploy.sending();
    const svc = await sendCompose(kiri, deploy.target, deploy.compose, deploy.env);
    deploy.deploying("containers starting");
    deploy.live(await waitUntilRunning(kiri, svc));          // service → address
  },
});
plugin.Deploy("coolify", plugin.Place{
	Targets: func(k *plugin.Kiri) ([]plugin.DeployTarget, error) {
		return []plugin.DeployTarget{
			{Name: "prod", Label: "Coolify · prod", Arch: "amd64"},
			{Name: "staging", Label: "Coolify · staging"}, // no Arch: Kiri asks once
		}, nil
	},
	Run: func(d *plugin.DeployJob, k *plugin.Kiri) error {
		d.Sending()
		svc, err := sendCompose(k, d.Target, d.Compose, d.Env)
		if err != nil {
			return err // Kiri shows Failed, with the reason
		}
		d.Deploying("containers starting")
		urls, err := waitUntilRunning(k, svc)
		if err != nil {
			return err
		}
		d.Live(urls) // service → address
		return nil
	},
})

What run gets on deploy:

Field What it holds
target The target picked, such as prod, with its arch.
compose The project’s compose file with image names in place of its build: sections. The images are already pushed.
env The project’s .env values, only after the person agreed for this project; otherwise null. Kiri asks again when a new name appears.
git { url, commit } when the person deploys from git: then Kiri builds nothing and compose is the project’s own file.
addresses The address chosen for each service with a port, such as web → shop.example.com. Kiri asks the first time.

Report Sending, Deploying and Live with deploy.sending(), deploy.deploying(detail) and deploy.live(urls); deploy.failed(reason), or an error, ends it as Failed. deploy.log(line) adds a line to the deploy’s log on the project’s Deploys tab. Your plugin never reads the project’s folders and never pushes images: Kiri pushes, to the registry the person named in Settings → Deploy.

The deploy stepsKiri reportsYour handler reportsBuildingserver’s chipPushingtheir registrySendingsending()Deployingdeploying()Livelive(urls)imagerun()sentupFailederrorfailed(reason)or an error, at any step
The steps of every deploy, whichever plugin is the place. Kiri reports Building and Pushing itself; your handler reports Sending, Deploying and Live, or Failed with the reason at any step.

A scanner

List your scanners under [adds] scan, and ask to see the packages inside images under [needs]:

[adds]
scan = [{ name = "trivy", label = "Trivy" }]

[needs]
images = "packages"

The prompt shows Be a scanner: Trivy, in Scan with ›. See the packages in an image you scan. name is the word kiri scan --with takes.

Kiri lists the packages in the image, the same CycloneDX bill of materials Save SBOM saves, and hands it to your handler. You return findings; Kiri draws them on the image’s Security tab under your scanner’s name, and keeps the last 20 scans whichever scanner made them. Your plugin never sees the image’s files. A scan has 5 minutes.

No Rust version · showing TypeScriptNo Python version · showing TypeScript
plugin.scan("trivy", async (scan, kiri) => {
  const report = await matchPackages(scan.packages); // CycloneDX, from Kiri
  return report.map((v) => ({ id: v.id, package: v.pkg, version: v.installed, severity: v.severity, fixed: v.fixed, title: v.title }));
});
plugin.Scan("trivy", func(s *plugin.ScanJob, k *plugin.Kiri) ([]plugin.Finding, error) {
	report, err := matchPackages(s.Packages) // CycloneDX, from Kiri
	if err != nil {
		return nil, err
	}
	out := make([]plugin.Finding, 0, len(report))
	for _, v := range report {
		out = append(out, plugin.Finding{ID: v.ID, Package: v.Pkg, Version: v.Installed, Severity: v.Severity, Fixed: v.Fixed, Title: v.Title})
	}
	return out, nil
})

severity is critical, high, medium, low or unknown. A scanner that also warns before a run, as the Trivy plugin does, adds a check that reads its own saved scans. The image scanner example has both.

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