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 |
Compose
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 athttps://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.
Settings
Or from a terminal. The token is typed where nobody sees it, and goes straight to your keychain:
$ 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] yConnecting 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:
Deploy shop to Coolify · prod
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:
$ 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.comWho 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.
- 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. - Pushing. Kiri pushes the images to the registry in Settings → Deploy, and writes their names into the compose file.
- 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
.envvalues. - 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. - 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.
Compose › shop
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:
$ 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