kolu
Docs

another computer

Your terminals,
on other machines.

kolu runs terminals on other machines over ssh and puts them on your canvas as ordinary tiles. The canvas shows one host at a time, and a row of host tabs switches between them live. Each host keeps its own arrangement.

The canvas switched to a remote host's tab: an opencode agent running in /home/toor on another machine, with that host's own dock group.
Another machine’s tab: the same canvas, running on a different box.

To reach the kolu app itself from another device, see From another device.

What a host needs

Passwordless ssh

You can ssh to the host without typing a password, through an ~/.ssh/config alias or a user@host. kolu dials non-interactively, so a host that asks for one says so.

Nix on the remote

The host has Nix installed, and nix runs from a non-interactive ssh session, not only a login shell. On a Mac, make your user trusted by its nix-daemon (trusted-users).

A Nix-wrapped kolu

Launch kolu through its Nix wrapper, which bakes in the padi build it deploys. kolu asks the host for its CPU and OS, so a macOS kolu can bind a Linux box.

Add a host

  1. Click + add on the host row. It needs nothing set up first.
  2. Type the target: an ~/.ssh/config alias such as zest, or a destination such as srid@zest.
  3. Press Enter. The host joins the row as a chip and the canvas switches to it.

A host you add is remembered: it returns after a kolu restart and reconnects on its own. The only way a host leaves is your own remove; one that has gone away comes back as a failed chip with the reason.

Your local machine is the first chip and cannot be removed. Typing localhost, 127.0.0.1 or ::1 selects it. user@localhost is a real remote: the loopback as another user is a different session.

Pre-seed hosts at launch

Use this when you want a host present without clicking anything: a scripted launch, a shared dev box, a fresh profile. Set KOLU_PADI_HOST to a comma-separated list of ssh targets:

KOLU_PADI_HOST=localhost,you@box kolu

Your local host is first in the pool either way.

First connect

The first time you switch to a host that has never run padi, kolu sets it up over ssh: one Nix operation finds the build the host needs, copies it over and installs it there. A first setup can take minutes.

How kolu runsWhere padi comes from
the home-manager modulethe build is already installed alongside kolu, so the copy starts at once and the host never compiles
nix run or nix profile installthe binary cache first, and a build when the cache does not have it

A Linux host usually needs no extra setup: its Nix accepts padi from any user when it is Nix 2.17 to 2.34, or when it and kolu’s own machine both run Nix 2.35 or newer. Otherwise, and always on a Mac, the host’s nix-daemon must trust your login: add your user to trusted-users in its Nix configuration.

What lands is padi plus kaval-tui, padi-tui and kolu itself. They are on $PATH in every terminal kolu opens there, with $PADI_SOCKET set, so an agent can drive its sibling terminals and use the MCP server at once.

AI coding agents and your profiles are delivered separately when a host first connects, and kept current. See Agents for what a host needs and what a failed delivery says.

While it connects

The canvas narrates a cold connect: the phase, a live tail of Nix’s output, a large transfer’s bytes, and a timer that climbs while the log is quiet. Copy copies everything the session kept.

If nothing arrives for long enough, kolu stops narrating and shows a card:

What stalledWhat the card offers
a remote still probing or provisioningthe phase, the last line printed, and how long nothing new arrived. Retry connection re-dials from the server, which a browser reload cannot do, and Switch to local
something that never reached this tab: the host list, your saved session, a host’s agent statuswhat did not arrive, with Reload, and Switch to local on a remote
this browser’s own link to koluDisconnected from server · Reconnecting…, and no claim about any machine

A local machine whose own agent fails to start has its own “kaval didn’t start” card.

The kolu server log keeps every line the tail shows, including Nix’s error and a failed build’s last lines. To read that build’s whole log, run the nix log command the error names, on the host.

Host tabs and the connection pip

Each host is a tab: local shows a Home icon and this machine’s hostname, a remote its ssh target. Every tab carries a pip for the whole chain, kolu to that host’s padi to its kaval.

PipMeaning
greenkolu reaches the host and its terminal daemon is serving
amber, pulsingconnecting or provisioning
amber, “kaval down”kolu reaches the host, but its terminal daemon is not serving. padi restarts it for you; the tooltip carries the daemon’s verdict
red, label struck throughfailed. Open diagnostics for the error, and retry

A host that answers kolu’s watchdog in time keeps its connection however slow it is. One that is powered off or off the network is noticed in about 25 to 30 seconds, and kolu reconnects when it is back.

Click the pip for diagnostics: connection state, terminal and awaiting counts, that machine’s agents, padi and kaval detail, and remove-with-confirm.

Switch hosts

What you doWhat happens
click a tabthe canvas switches to that host, live
Cmd/Super + K, then a host namehosts are root results in the switcher
Mod + Shift + H (Mod is Cmd on a Mac, Ctrl elsewhere), or the search icon in the host barthe scoped host list, with the machine you came from highlighted, so the chord then Enter hops between two machines

Each host owns its canvas: its terminals, splits and focused tile come back as you left them, and its work keeps running while you are away. If the active host leaves the pool, kolu switches you to local.

A tab also carries that host’s attention counts, violet for needs-you and amber for unread. Clicking the violet count jumps to the agent that is waiting, and an installed PWA badges the awaiting count across hosts. See Notifications for what each signal means.

Put the tabs in your own order

Drag a host tab along the strip to move it. The tab lands where you dropped it and everything else keeps its relative order, including machines folded into the ⋯ +N overflow. A drag neither switches host nor opens diagnostics.

The order is saved on the server, so every browser, device and other list of machines shows it. A machine you add joins at the end, and your own machine is pinned first.

One Conductor, every host

The Conductor is one conversation, on the machine running kolu-server, and its tools reach every host in your pool. Its tab comes first in the tab row.

When a host is down

When a host’s padi cannot bind, its canvas is replaced by a card naming the cause, with Reconnect (a real re-dial, once you have cleared the cause) and Switch to local.

When the attempt printed anything, the card shows its last lines under the error, in the words of the tool that hit it. So does the diagnostics popover.

CardWhat happened
Another kolu owns this hostanother kolu supervisor already holds this host’s padi
This host runs an older koluthe padi there speaks an older contract and refused to bind
This host runs a kolu from before the protocol changekolu cannot ask that padi which protocol version it speaks. Update that machine’s kolu, or stop the padi there
This host needs passwordless sshthe host asked for a password. Set up key-based access (ssh-copy-id)
This host isn’t trusted yetssh does not recognize the host’s identity key. Run ssh <host> once to accept it, or to clear a changed-key warning
This host has no Nix that kolu can runthe shell could not run nix-instantiate: Nix is missing, or off a non-interactive session’s PATH
Connecting to this host kept stallinga step went quiet too many times, a stalled download included. The detail names the step
Kolu couldn’t set up this hostbringing padi up there kept failing. The detail is the error
This kolu run is missing its agent sourcekolu was not launched through its Nix wrapper, so it has nothing to deploy
Kolu couldn’t prepare padi for this hostthe host’s Nix did not report its CPU and OS (often a startup file writes to stdout), or the baked source could not resolve padi
This host’s padi never settleda contract upgrade’s drain never provably finished

A separate card covers the host’s kaval. When its kaval speaks an incompatible wire contract, the canvas names both versions and offers Update & restart kaval behind a confirm.

Port forwarding

A dev server on a remote host listens on that machine’s loopback, which never leaves the machine it is on: http://127.0.0.1:5173 in your browser means your own machine. Click the port and kolu forwards it (opens a door, a port on the machine running kolu that reaches the server), then opens the tab.

The Inspector’s Ports section lists what each terminal is serving, read from the host’s socket table.

What a click opens

kolu reads the port’s bind address and picks the mechanism. Nothing to configure.

Where the server listensWhat kolu doesWhat opens
a remote host, on loopbackssh -L over a connection of its ownhttp://<the kolu host>:<port>
kolu’s own machine, on loopbacka plain TCP relayhttp://<the kolu host>:<port>
kolu’s own machine, all interfacesnothing: it already answershttp://<the kolu host>:<port>
a remote host, one specific interfacenothing it can dothe row says “not reachable”

Both mechanisms reach the far side’s loopback, so a port bound to one named interface of a remote machine is out of reach, and kolu says so.

You get the same port number back whenever it is free, so a saved link survives a restart. When it is taken, the row shows the one you got.

Open and close doors

A forwarded port is one row wherever it appears, with a teal ⇄ :<port> pill naming where it answers, a copy button, and a ⨯ that closes the door. The rows are in the Inspector’s Ports list, the host tab’s dropdown and the connection pip, and each links to the terminal serving it.

  1. Open one by clicking it. Any port row that needs a door offers forward & open. Doors open only for ports you click, and close when the scanner sees the listener die.

  2. Or forward a port kolu never saw. Cmd/Super + K → Forward a port…, then host:port, or just a port for the host you are looking at. Use it for a port kolu’s scan cannot see.

  3. Close it when you are done. Click ⨯ on the row. A forward you asked for by hand stays until you cancel it or its host leaves.

A door onto a server no terminal holds, such as one you opened by hand, sits under elsewhere on this host in the Ports list, and stays visible while that group is folded.

Every door dies with the kolu server, guaranteed by the kernel rather than by a timer, so a deploy or a crash leaves none open.

A printed localhost URL

Agents print http://localhost:5173/ and its relatives (127.*, [::1], 0.0.0.0) constantly. In your browser that hostname is your own machine, not the host running the server. Click a loopback URL and a card appears at the cursor: it names what on the host listens on that port and offers forward & open and copy, carrying the printed path through the door. When nothing listens there, it says so.

Cmd/Ctrl-click opens the raw URL with no card. The card is live: leave it open while a server starts and it upgrades when the listener is real.

Known limitations

A kolu remote terminal is an ssh session, not the machine’s GUI login session, so tools that lean on that session behave differently.

SymptomWhyRemedy
on macOS, gh reports The token in default is invalidgh keeps its token in the login Keychain, unlocked only for the GUI sessiona $SSH_CONNECTION-guarded GH_TOKEN (a scoped fine-grained PAT), or security unlock-keychain, or gh auth login --insecure-storage
git push or clone fails Permission denied (publickey)the session forwards no agent: your keys live in the local session, and kolu passes no -Aput ForwardAgent yes for the host in ~/.ssh/config and reconnect (see Forwarded ssh-agent)
pbcopy, pbpaste, launchctl and desktop notifications do nothingthese are GUI-session servicesrun them from the box’s own terminal; for launchctl name the domain: launchctl print gui/$(id -u)
a command is “not found”, locale warnings, missing $PATHssh starts a leaner login shellput PATH and locale in the rc both shells read (~/.zshrc); check with echo $PATH and locale

This table grows by incident. If you hit a case that is not here, add a row.

Forwarded ssh-agent

kolu dials ssh itself and passes no -A, so your ~/.ssh/config stays the authority. Set forwarding there and reconnect:

# ~/.ssh/config
Host box
  ForwardAgent yes

kolu then hands your forwarded agent to every terminal it opens on that host, so git push and a further ssh hop work there. Each reconnect re-points the link it arrives on, so terminals opened under an earlier connection heal. ssh-add -l lists the keys a terminal can reach; an empty answer means no agent was forwarded.

Next