Kiri Developers

EXAMPLES

Example: Cloudflare and Tailscale

Cloudflare and Tailscale come with Kiri as two plugins, share-cloudflare and share-tailscale. Together they add four ways to share under Share with ›, next to Kiri Share. This page follows both from setup to a live link and back, and shows the code and the permissions that make them work. They are the worked example for a choice inside a Kiri feature.

What they add

Neither plugin gets a Share button or a page of its own. Each joins places Kiri already has:

Place Cloudflare (share-cloudflare, mark CF) Tailscale (share-tailscale, mark TS)
F Share with › Cloudflare, quick link and Cloudflare, your domain Tailscale and Tailscale Funnel
G Settings A block in Settings → Sharing: your domain’s token, who may open links A block in Settings → Sharing: sign in to your tailnet
A Status bar None: Kiri’s own share count already counts its links tailnet · online while something is shared, tailnet · offline in amber if the connection drops

In a terminal the four ways are --via cloudflare-quick, --via cloudflare, --via tailscale and --via funnel.

Both run a real program, cloudflared or tailscaled, so each runs as a container of its own, started with your first share through it and stopped when the last one ends. Because they come with Kiri, they update with Kiri, and you can switch them off but not remove them.

Kiri
DockerContainersComposeImagesKiriSharePluginsSettings

Compose

▾ shop3 of 3 running
web8080→80Up 2 hours
Open localhost:8080Ports…PauseShow in compose fileShare with ›Deploy to ›
Kiri Share Cloudflare, quick link Cloudflare, your domain Tailscale Tailscale Funnel
Default: Kiri Share
Share with › on the web service of shop. Kiri Share is first; the two plugins add four ways after it, each with its mark and a short note. The line at the bottom names your default, the way the Share button uses.

Set them up

A Cloudflare quick link needs nothing: no account and no setup. The other three ways need you to connect once, and Tailscale stays switched off until you do, in Settings → Sharing, or with kiri plugin set in a terminal. Kiri draws each plugin’s block from the fields in its kiri-plugin.toml, and puts every token in your system’s keychain.

Kiri

Settings

AppearanceResourcesNetworkSharingDeployBuilds
Share with, by defaultKiri Share ▾
CF Cloudflarequick links: ready, no account
Your domainexample.com · token in keychainConnectedDisconnect
Who may open linksquick links and your domainAnyone ▾
TS Tailscalekiri-mbp · your-tailnet.ts.netConnectedDisconnect
Settings → Sharing with both plugins connected. Cloudflare's quick links are ready with no account; your domain uses a token kept in the keychain. Tailscale is signed in as one machine for this computer.

Cloudflare, your domain needs a Cloudflare account with your domain on it, and an API token with Cloudflare Tunnel Edit and DNS Edit. Add Access Apps and Policies Write if you want to choose who may open a link. Type the token and the domain, press Check connection, and the plugin asks Cloudflare whether the token has those rights.

Who may open links is Anyone until you list email addresses. A quick link then asks each visitor for a one-time code that Cloudflare emails to them; a link on your domain puts Cloudflare Access in front of it, which needs the third right.

Tailscale joins your tailnet once, as one machine for this computer, such as kiri-mbp. Your tailnet needs MagicDNS and HTTPS switched on. There are two ways to sign in:

  • An OAuth client (the default). Make one in Tailscale’s admin console with the scopes auth_keys and devices:core, owning the tag tag:kiri-share, and paste its ID and secret. The plugin asks Tailscale for a tagged, pre-approved key each time it needs one; Kiri adds the secret to those requests, and the plugin never reads it.
  • A pasted auth key, tagged and pre-approved. It’s simpler, but tailscaled has to read the key to join, so this is the one secret Kiri hands to the plugin’s program. That’s why Tailscale’s permissions include “Read a key you type, to start its program”, and why your company can switch this choice off.
zsh
$ kiri plugin set share-cloudflare domain=example.com
  ✓ share-cloudflare: domain = example.com
$ kiri plugin set share-cloudflare token
  API token (typing is hidden): ••••••••••••••••••••
  ✓ Kept in your keychain.
    Checked: Tunnel Edit ✓  DNS Edit ✓  Access ✗ (links open to anyone)
$ kiri plugin set share-tailscale client_id=k7Qx3
  ✓ share-tailscale: client_id = k7Qx3
$ kiri plugin set share-tailscale client_secret
  OAuth client secret (typing is hidden): ••••••••••••••••
  ✓ Kept in your keychain.
    Joined your-tailnet.ts.net as kiri-mbp (tag:kiri-share).

Share something

Pick a way in Share with ›, or press Share to use your default. In a terminal, add --via:

zsh
$ kiri share shop-web-1 --via cloudflare-quick
  ◆ Share with Cloudflare, quick link  connecting…
  ●  live     https://lamp-orbit-garden-ice.trycloudflare.com
              via Cloudflare · for testing: the address changes every time
              press Ctrl+C to stop sharing
$ kiri share shop-web-1 --via funnel
  ◆ Share with Tailscale Funnel  connecting…
  !  notice   A first Funnel address can take up to 10 minutes
              to reach public DNS.
  ●  live     https://kiri-mbp.your-tailnet.ts.net
              via Tailscale Funnel · open to anyone

Every link, whichever way made it, shows in the Share view with “via Cloudflare” or “via Tailscale” beside its address, and in Kiri’s share count in the status bar. Only Kiri Share sees each visit, so only Kiri Share links have a request list.

Live means it opens

A way to share says Live only once a person can open the address. A Cloudflare quick tunnel hands back its address about six seconds after it starts, but the name reaches Cloudflare’s DNS a moment after the tunnel registers. A browser that looks the name up too early remembers “not found”, on a Mac for over a minute. So the plugin waits until Cloudflare’s DNS has the name, then says Live, and the link you click works the first time.

A quick link going liveYouKirishare-cloudflareCloudflareShare with › quick linkjob: share, relay addressshows Connectingask for an address….trycloudflare.comQUIC :7844 registerDNS has the name yet?Live, with the addressthe link, ready to open
One quick link, from your click to Live. cloudflared asks Cloudflare for an address, registers the tunnel, and the plugin asks Cloudflare's DNS for the new name until it answers. Only then does Kiri show the link.

Tailscale waits the same way. A tailnet link is Live once its certificate is in, which takes seconds. A first Funnel address can take up to 10 minutes to reach public DNS, so the plugin sends a Notice saying so, and Live comes when the name answers.

Your domain, step by step

Cloudflare, your domain gives a link a fixed name, such as web.example.com. When you share, the plugin:

  1. Makes a tunnel whose rules live at Cloudflare.
  2. Gives it one rule, “web.example.com goes to the shared port”, and a catch-all that answers 404.
  3. Points the name at the tunnel, with a CNAME record in the same account.
  4. If you chose who may open links, puts a Cloudflare Access application in front of the name.
  5. Runs cloudflared with the tunnel’s token, and says Live once the name answers.
  6. When you stop: removes the DNS record first, then the tunnel. A record left behind would show Cloudflare’s error 1016 to anyone who opens it.

Inside the plugins

Both plugins are short. Here is Cloudflare’s kiri-plugin.toml:

name = "share-cloudflare"
version = "1.0.0"
publisher = "kiri"
description = "Share with › Cloudflare: a quick link with no account, or a name on your own domain."
api = "1"
price = "free"
mark = { icon = "cloudflare.svg", colour = "#F38020" }

[run]
image = "Dockerfile"           # cloudflared and the plugin's code, pinned by hash at install
while = "sharing"

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

[needs]
sites = ["api.trycloudflare.com", "api.cloudflare.com", "cloudflare-dns.com",
         "region1.v2.argotunnel.com:7844", "region2.v2.argotunnel.com:7844"]

[[settings]]
key = "domain"
label = "Your domain"
type = "text"

[[settings]]
key = "token"
label = "API token"
help = "Cloudflare Tunnel Edit and DNS Edit. Add Access Apps and Policies Write to choose who opens a link."
type = "secret"
for = "api.cloudflare.com"

[[settings]]
key = "access"
label = "Who may open links"
type = "choice"
choices = ["Anyone", "These email addresses"]
default = "Anyone"

[[settings]]
key = "emails"
label = "Email addresses"
help = "Each visitor gets a one-time code by email."
type = "text"

cloudflared talks to Cloudflare on port 7844, over QUIC, and falls back to HTTP/2 on the same port. Kiri filters the plugin’s traffic by address, not with a web proxy, so the two :7844 entries hold for both.

The quick link, nearly whole. share.addr is the address of the relay Kiri opened to the one port you shared; the plugin never sees the container itself.

import { spawn } from "node:child_process";
import { createInterface } from "node:readline";
import { plugin } from "@kiri/sdk";

const ADDRESS = /https:\/\/[a-z0-9-]+\.trycloudflare\.com/;

plugin.share("cloudflare-quick", async (share, kiri) => {
  const tunnel = spawn("cloudflared", ["tunnel", "--no-autoupdate", "--url", `http://${share.addr}`]);
  share.signal.addEventListener("abort", () => tunnel.kill());

  let url = "", live = false;
  for await (const line of createInterface({ input: tunnel.stderr })) {
    url ||= line.match(ADDRESS)?.[0] ?? "";
    if (url && !live && line.includes("Registered tunnel connection")) {
      if (!(await inPublicDns(kiri, new URL(url).host))) {
        tunnel.kill();
        return share.ended("Cloudflare didn't publish the address. Try again in a minute.");
      }
      live = true;
      share.live(url);
    }
  }
  share.ended(share.signal.aborted ? "stopped" : "cloudflared stopped");
});

// Live only once Cloudflare's DNS has the name, so the first click works.
async function inPublicDns(kiri, host) {
  for (let i = 0; i < 60; i++) {
    const r = await kiri.http.fetch(`https://cloudflare-dns.com/dns-query?type=A&name=${host}`,
      { headers: { accept: "application/dns-json" } });
    if ((await r.json()).Answer) return true;
    await new Promise((done) => setTimeout(done, 500));
  }
  return false;
}

Calls to Cloudflare’s API for your domain go out with kiri.http.fetch(url, { secret: "token" }): Kiri adds the token to requests to api.cloudflare.com, the host its setting names, and to no other.

Tailscale’s plugin joins your tailnet once. Its container’s scratch folder is emptied each time it stops, so the plugin keeps the machine’s small state file in its store through Kiri and puts it back at start: a restart is the same machine, not a new one.

Each share is a port on that one machine. Funnel links take ports 443, 8443 and 10000, the only three Funnel allows. Tailnet-only links take ports from 8001 up, and the plugin remembers which port it gave each container, so the address stays the same next time. A machine per share would mean a new certificate every time, which can hit Let’s Encrypt’s limits and lock you out for up to 34 hours, and every name written into public certificate logs.

Tailscale: one machine, a route per shareYour tailneta teammateyour phoneThe internetanyonea webhookshare-tailscale, its own containertailscaledone machine: kiri-mbp:8001 tailnet only → web:443 Funnel → apiOpened by Kiri, while sharedrelayweb :80relayapi :3000relaysFunnel
Tailscale shares, all on one machine for this computer. A tailnet-only link answers people on your tailnet, on a port of its own; Funnel opens a link to anyone, on port 443, 8443 or 10000, so at most three public links at once. Traffic reaches the shared port through the relay Kiri opened.

The plugin may reach Tailscale’s own sites and nothing else, so it can’t reach other machines on your tailnet directly. Your tailnet reaches a share through Tailscale’s relays, which can be slower than a direct connection between two devices.

What they may do

Plugins that come with Kiri have no install prompt. Their Permissions tab in the Plugins view lists the same lines under It may:

Cloudflare Tailscale
Be a way to share: Cloudflare, quick link; Cloudflare, your domain. Reach the port you share, only while it is shared Be a way to share: Tailscale; Tailscale Funnel. Reach the port you share, only while it is shared
Show a note in the status bar
Reach these websites: api.trycloudflare.com, api.cloudflare.com, cloudflare-dns.com, region1.v2.argotunnel.com, region2.v2.argotunnel.com Reach these websites: controlplane.tailscale.com, login.tailscale.com, log.tailscale.com, api.tailscale.com, acme-v02.api.letsencrypt.org, and Tailscale’s relay servers (derp1-all.tailscale.com, derp2-all.tailscale.com and the rest, each by name)
Use a token you type, without reading it Use a token you type, without reading it
Read a key you type, to start its program

Neither may see your containers, images or files, reach a port you didn’t share, or reach your computer or other plugins.

Every way to share, side by side

Kiri Share Cloudflare, quick link Cloudflare, your domain Tailscale Tailscale Funnel
Account Kiri Cloud none Cloudflare, with a domain on it Tailscale Tailscale, Funnel allowed
Address name.runkiri.cloud a random trycloudflare.com name web.example.com kiri-mbp.your-tailnet.ts.net:8001 kiri-mbp.your-tailnet.ts.net, public
Who can open it anyone anyone, or listed email addresses with a one-time code anyone, or who Cloudflare Access lets in your tailnet only anyone
Same address next time with a reserved name no yes yes while its port is free
Request list in Kiri yes no no no no
Worth knowing see Kiri Share testing only, 200 requests at once, no server-sent events uploads over 100 MB refused on free plans; 125 s for your app to answer needs MagicDNS and HTTPS beta at Tailscale, three public links per machine, first DNS up to 10 minutes
Best for everyday sharing, with a history of visits a quick demo companies already on Cloudflare teammates and your own devices webhooks and short public demos

Kiri shows the limits that matter before the link opens: the quick link’s “for testing” line, and Funnel’s DNS wait. Cloudflare’s terms let it limit free accounts that serve video or many large files.

Stop, switch off, disconnect

Stop on a link, in the Share view or with Ctrl+C, ends that one share. Kiri tells the plugin, closes the relay and checks that the port no longer answers. When the last share through a plugin ends, its container stops.

Switching a plugin off in the Plugins view, or with kiri plugin disable share-tailscale, takes its ways out of Share with ›. If something is shared through it, Kiri asks first and ends those links. Its settings and tokens stay, ready for when you switch it back on.

Disconnect in Settings → Sharing forgets what you connected:

What Disconnect does What stays
Cloudflare, your domain Ends its links, removes their DNS records and tunnels, deletes the token from your keychain Your Cloudflare account and domain, untouched. Quick links keep working: they need no account
Tailscale, OAuth client Ends its links, deletes the machine kiri-mbp from your tailnet, deletes the client secret from your keychain The OAuth client in Tailscale’s admin console, for you to delete if you like
Tailscale, pasted key Ends its links, logs the machine out, deletes the key from your keychain The machine may stay listed as logged out in Tailscale’s admin console; remove it there

The activity record keeps each share either plugin made, with its way and its address.

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