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.
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(())
});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:
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.
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.
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