Kiri Developers

EXAMPLES

Example: Coolify

Coolify runs your apps on servers you own. The coolify plugin comes with Kiri and makes Coolify a place to deploy: pick Deploy to › Coolify · prod on a Compose project, and the project runs on your server a minute later. Kiri builds and pushes the images; the plugin hands Coolify the compose file and watches the containers start. This page follows one project, shop, from connecting a server to a live address, and shows the code behind each place.

What it adds

Coolify is the plugin that uses the most places, so it’s the one to read if you want to see them work together. Everything below is drawn by Kiri, from what the plugin sends.

Place What Coolify puts there
F Deploy to › Coolify · prod, Coolify · staging: one target for each of your Coolify servers
G Settings → Deploy Your Coolify address and API token, with Check connection
C A tab on a Compose project Coolify: where it’s deployed, how, its address, the last deploy
A line on a Compose project’s page Deployed · prod, 2 min ago beside the project’s state
H A column in the Compose list Coolify: the target each project is on, such as prod
E Its own section Coolify, with Apps, Servers and Deploys
A A status note shop → prod · 3 of 5, only while a deploy runs
B A menu item on a Compose project Open in Coolify
Commands kiri plugin coolify apps, servers, logs APP, open PROJECT
Kiri
DockerContainersComposeImagesKiriSharePluginsSettingsCoolify ⚙ Apps · 3Servers · 2Deploys

Compose

ProjectState Coolify
shop/code/shop3 of 3 runningdeploying
docs/code/docs
2 of 2 runningprod
analytics/code/analyticsstoppedstaging
scratch/code/scratch
1 of 1 running
Kiri 1.0.0Terminal1 shared shop → prod · 3 of 5VM running6 of 6 runningFeedback
The Compose list during a deploy. Coolify's column shows where each project is deployed; shop is on its way to prod. In the status bar, Coolify's note shows the deploy with three of its five steps done, and leaves when it ends.

Connect a server

Coolify stays switched off until you connect it. Open Settings → Deploy, or press Set up on Coolify’s row in the Plugins view. You need two things:

  • Your Coolify address, such as https://coolify.example.com. Coolify Cloud works the same way: Coolify hosts the control panel at https://app.coolify.io, and your apps still run on your own servers.
  • An API token, made in Coolify under Keys & Tokens → API Tokens, with the write right, which covers deploys and logs. On a Coolify you run yourself, an admin first switches on Settings → Advanced → API access.

The registry at the top of Settings → Deploy is Kiri’s own, not Coolify’s: it’s where Kiri pushes the images it builds, for any place to deploy.

Kiri

Settings

AppearanceResourcesNetworkSharingDeployBuilds
Registry for deploysghcr.io/acme · signed inChange
CO CoolifyConnected
API tokenin your keychain
Coolify 4.7.6 · 2 servers: prod (x86_64), staging (arm64)
Check connectionDisconnect
Settings → Deploy with Coolify connected. The registry is Kiri's; the Coolify block below it is drawn from the plugin's two fields. Check connection asked Coolify for its version and its servers.

Or from a terminal. The token is typed where nobody sees it, and goes straight to your keychain:

zsh
$ kiri plugin set coolify server=https://coolify.example.com
  ✓ coolify: server = https://coolify.example.com
$ kiri plugin set coolify token
  API token (kept in your keychain, never shown to Coolify's plugin): ••••••••••
  ✓ token saved · ✓ connected to Coolify 4.7.6 · 2 servers
  Coolify is on.
  Also add its own section to the sidebar: Coolify, 3 pages? [Y/n] y

Connecting switches Coolify on. Because a section takes room in the sidebar, Kiri asks about it once, as it would at install. Say no and everything else still works; kiri plugin unhide coolify section brings it back later.

Deploy a project

Open the menu of a Compose project, on its row or its page, and choose Deploy to ›, then a target. In a terminal, kiri deploy shop --to coolify:prod.

The first time a project goes to a target, Kiri asks two things, and remembers the answers for next time:

Kiri

Deploy shop to Coolify · prod

Serverprod · x86_64
Buildhere, for linux/amd64: shop has changes not committed
apiport 3000inside only ▾
dbno port · no address
.env6 values: DATABASE_URL, SESSION_KEY, …Don’t sendSend
CancelDeploy
The first deploy of shop to prod. Kiri asks which address each service with a port should get, and whether to send the .env values. db has no port, so it gets no address. The plugin sees the .env names now, and their values only after you press Send.

Leave an address empty and Coolify gives the service a free sslip.io name, which stays plain http://. An https:// name on your own domain gets a Let’s Encrypt certificate from Coolify, once the name points at the server and ports 80 and 443 are open there.

Then the deploy runs. Every step shows on the project’s Deploys tab, which is Kiri’s own, and in the terminal:

zsh
$ kiri deploy shop --to coolify:prod
  shop → Coolify · prod (coolify.example.com, x86_64)
  shop has changes that are not committed, so Kiri builds here.
  ✓ building   api for linux/amd64 in 38 s
  ✓ pushing    ghcr.io/acme/shop-api:k-7f3a2c
  ✓ sending    the compose file · web → https://shop.example.com
               6 values from .env (DATABASE_URL, SESSION_KEY, …)
  ⠿ deploying  db running · api running · web starting
  ●  live      in 1 min 12 s
               https://shop.example.com

Who does what

Kiri does the building and pushing on your computer. The plugin never sees your folders, and Coolify never needs to reach them. Coolify gets a compose file with image names in place of the build: sections, so the server only pulls and starts.

A Coolify deploy, call by callKiricoolify pluginCoolifyyour serverbuild linux/amd64push to registrydeploy jobcompose, addresses, .envPOST /servicesPATCH …/envs/bulkPOST /deploypull images, startGET /services, every 3 sLive, with the address
One deploy, call by call. Kiri builds and pushes, then hands the plugin the rewritten compose file and the addresses you chose. The plugin makes or updates the app in Coolify, sends the .env values you agreed to, starts the deploy and asks Coolify every three seconds until every container runs.
  1. Building. Kiri asks the plugin for the target’s chip, which Coolify reports for each server, and builds each service with a build: section for it. When Coolify doesn’t know a server’s chip, Kiri asks you once and remembers.
  2. Pushing. Kiri pushes the images to the registry in Settings → Deploy, and writes their names into the compose file.
  3. Sending. The plugin makes the app in Coolify the first time, in a Coolify project named after yours, or updates it after that. It sends the compose file, each service’s address and, if you agreed, the .env values.
  4. Deploying. The plugin starts the deploy. Coolify gives no deploy ID for a Compose app, so the plugin watches each container’s state instead, and passes it to Kiri as log lines: db running · api running · web starting.
  5. Live once every container runs, with the addresses. Failed if one exits, with Coolify’s reason and the last log lines.

From git instead

When the project’s folder has no uncommitted changes and its commit is pushed, the first-deploy dialog also offers Build: from git. Then Kiri builds and pushes nothing. The plugin gets the repository and the commit, hands them to Coolify, and Coolify builds on the server. The server has to be able to fetch that repository, and the build uses the server’s time, not yours. A build on the server has a deploy ID in Coolify, so the plugin follows Coolify’s own build log, line by line, onto the Deploys tab. With changes not committed, or no remote, Kiri builds here, and says why, as above.

After a deploy

The project’s page now carries Coolify’s line at the top, Deployed · prod, 2 min ago, and its Coolify tab after Kiri’s own five. The tab’s buttons and the row’s Open in Coolify take you to the app in Coolify’s own dashboard, in your browser.

Kiri

Compose › shop

3 of 3 running~/code/shop Deployed · prod, 2 min ago
StructureServicesCompose fileLogsDeploys Coolify
Deployed toprod · coolify.example.com
Howbuilt here for linux/amd64, pushed to ghcr.io/acme
Last deployfinished 2 minutes ago, in 1 min 12 s
Variables6 from .env: names shown, never values
Open in CoolifySee deploys
The shop project after the deploy. Coolify's line sits beside the project's state. Its tab, after Kiri's Deploys tab, shows the target, how the images got there, the address, the last deploy and the variables, names only.

Coolify’s section lists what’s on your servers, including apps you made in Coolify without Kiri:

  • Apps: each app, its server, its state and its address. The ⋯ on a row has Deploy again, Logs, Open in Coolify and Stop, which asks first.
  • Servers: each server, its address, its chip and how many apps it runs.
  • Deploys: Coolify’s own history, newest first, for every app.

The same lists are commands, for a terminal or a script:

zsh
$ kiri plugin coolify apps
  APP         SERVER    STATE       ADDRESS
  shop        prod      running     https://shop.example.com
  docs        prod      running     https://docs.example.com
  analytics   staging   stopped     http://analytics.203.0.113.20.sslip.io
$ kiri plugin coolify servers
  SERVER    ADDRESS         CHIP      APPS
  prod      203.0.113.7     x86_64    2
  staging   203.0.113.20    arm64     1
$ kiri plugin coolify logs shop
  web-1  | 10.0.1.4 - GET / 200
  api-1  | listening on :3000
$ kiri plugin coolify open shop
  Opening shop in Coolify, in your browser.

open is the menu item Open in Coolify run from a terminal: every menu item a plugin adds is also a command.

Inside the plugin

Coolify’s plugin only talks to one server over HTTPS, so it’s WebAssembly: it costs nothing between calls and needs no container. Here is its kiri-plugin.toml:

name = "coolify"
version = "1.0.0"
publisher = "kiri"
description = "Deploy to › Coolify: run a Compose project on your own servers."
api = "1"
price = "free"
mark = { icon = "coolify.svg", colour = "#6B16ED" }

[run]
wasm = "coolify.wasm"

[adds]
deploy = [{ name = "coolify", label = "Coolify", env = true }]
actions = [{ name = "open", on = "compose-project", label = "Open in Coolify" }]
commands = [
  { name = "apps", help = "List your Coolify apps and where they run" },
  { name = "servers", help = "List your Coolify servers and their chips" },
  { name = "logs", help = "Show an app's logs from Coolify", args = "APP" },
]

[window]
status = true
tabs = [{ on = "compose-project", label = "Coolify" }]
facts = ["compose-project"]
columns = [{ on = "compose", label = "Coolify" }]
section = { name = "Coolify", pages = ["Apps", "Servers", "Deploys"], settings = true }

[[settings]]
key = "server"
label = "Coolify address"
help = "Such as https://coolify.example.com, or https://app.coolify.io for Coolify Cloud."
type = "url"
reach = true
required = true

[[settings]]
key = "token"
label = "API token"
help = "Keys & Tokens → API Tokens, with the write right."
type = "secret"
for = "server"
required = true

There’s no [needs] sites: the only place the plugin may reach is the address you type. And there’s no containers or images: it never sees your containers, only the compose file Kiri hands it for a deploy.

The deploy itself. deploy.compose already names the pushed images, and deploy.env is empty unless you pressed Send:

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

// Every call goes to the address you typed. Kiri adds the token on the way out.
async function coolify(kiri, method, path, body, server) {
  server ??= await kiri.settings.get("server");
  const r = await kiri.http.fetch(`${server}/api/v1${path}`, {
    method, secret: "token", body: body && JSON.stringify(body),
    headers: { "content-type": "application/json" },
  });
  if (!r.ok) throw new Error(`Coolify answered ${r.status}: ${(await r.json()).message ?? ""}`);
  return r;
}

plugin.deploy("coolify", {
  targets: async (kiri) => {
    const servers = await (await coolify(kiri, "GET", "/servers")).json();
    // arch(s) reads the server's chip, "amd64" or "arm64"; when Coolify doesn't know it, Kiri asks you
    return servers.map((s) => ({ name: s.name, label: `Coolify · ${s.name}`, arch: arch(s) }));
  },

  run: async (deploy, kiri) => {
    deploy.sending();
    // compose file in base64 and deploy.addresses; or, from git, deploy.git's repository and commit
    const app = await makeOrUpdate(kiri, deploy);
    if (deploy.env) {
      const data = Object.entries(deploy.env).map(([key, value]) => ({ key, value }));
      await coolify(kiri, "PATCH", `/services/${app}/envs/bulk`, { data });
    }
    await coolify(kiri, "POST", `/deploy?uuid=${app}`);

    deploy.deploying("containers starting");
    await kiri.status.set({ text: `${deploy.project} → ${deploy.target.name} · 3 of 5`, tone: "plain" });
    try {
      for (;;) {
        const parts = await containers(kiri, app);   // [{ name, state }]
        deploy.log(parts.map((p) => `${p.name} ${p.state}`).join(" · "));
        const gone = parts.find((p) => p.state === "exited");
        if (gone) return deploy.failed(`${gone.name} stopped on the server. See its logs in Coolify.`);
        if (parts.every((p) => p.state === "running")) return deploy.live(deploy.addresses);
        await new Promise((done) => setTimeout(done, 3000));
      }
    } finally {
      await kiri.status.clear();
    }
  },
});

// Check connection: the values as typed, before they're saved.
plugin.settings.check(async (values, kiri) => {
  const version = await (await coolify(kiri, "GET", "/version", null, values.server)).text();
  const servers = await (await coolify(kiri, "GET", "/servers", null, values.server)).json();
  return { ok: true, text: `Coolify ${version} · ${servers.length} servers` };
});

The tab, the line and the Apps page are on Tabs, pages and columns, and the menu item and commands on Menus and commands. The column is a few lines more:

plugin.column("compose", async (rows, kiri) => {
  const cells = {};
  for (const project of rows) {                          // the rows on screen
    const d = await kiri.store.get(`deploy:${project.name}`);
    if (d) cells[project.name] = d.running ? { text: "deploying" } : { text: d.target, tone: "good" };
  }
  return cells;                                          // a project with no cell stays empty
});

What it may do

Coolify comes with Kiri, so there’s no install prompt. Its Permissions tab lists, under It may:

  • Be a place to deploy: Coolify. Get a project’s compose file after Kiri builds and pushes it
  • Send a project’s .env values to it, after you agree for that project
  • Add items to the menu of: Compose projects
  • Add commands: kiri plugin coolify apps, servers, logs
  • Show a note in the status bar
  • Add a tab to: Compose projects
  • Add a line to the top of: Compose projects
  • Add a column to: Compose
  • Add its own section to the sidebar: Coolify, 3 pages
  • Reach the address you type in its settings
  • Use a token you type, without reading it

It can’t see your containers, images or folders, start or stop anything on your computer, or reach any site but your Coolify.

Disconnect in Settings → Deploy deletes the token from your keychain, forgets which Coolify app belongs to which project, and takes Coolify’s places out of the window. Your apps keep running on your servers, untouched. The project’s Deploys tab keeps its history, since it’s Kiri’s.

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