Remote machines

A project can live on another computer, like a home server or a VPS. Its sessions run there, and it sits in the sidebar next to your Mac’s projects, with the machine’s name after its own.

What a machine needs

• Linux on x86-64 or ARM64 (not Alpine).
• SSH access with your keys or SSH agent, without a password prompt. Connect once in Terminal with ssh, so your Mac knows the machine.
• git, for the Changes tab and branches.

Add a machine

Open Settings › Machines and click Add Machine…, or choose Add Machine… under Location in New Project. Type a host from your ~/.ssh/config, which Kuvo Code suggests, or user@host. For a port or an IPv6 address, add a Host for the machine to ~/.ssh/config and type its name. Kuvo Code checks that it can connect before adding it.

To open a project there, choose the machine under Location in New Project and type the folder’s path, like ~/projects/app.

What happens on the machine

Kuvo Code installs its engine in ~/.kuvo-code on the machine, the same version as on your Mac, checked on your Mac before it’s sent. The engine listens on the machine’s own localhost only, and Kuvo Code reaches it through SSH.

The first time, Kuvo Code also puts a browser there, for the agent: Chrome, with every library and font it needs beside it, a few hundred megabytes in ~/.kuvo-code/browser. Nothing is installed on the system, and it needs no administrator rights. It’s downloaded and checked on your Mac too, then sent.

The engine keeps running when your Mac sleeps, shuts down or loses the network, so a task carries on, and its work is there when you open Kuvo Code again. When you quit with nothing running, the engine stops. If Kuvo Code hasn’t connected for a day, it stops by itself. A bot on the machine keeps it running while one of its wake-ups or watches is waiting. If the connection drops, Kuvo Code connects again by itself. Meanwhile, and while it connects at launch, its sessions stay in the sidebar and show their conversations as last seen, to read, with a bar over the composer that says what’s happening and offers Connect Now; you can write but not send until it’s back.

Accounts and settings

Your accounts, API keys and sign-ins like ChatGPT’s or GitHub Copilot’s alike, are copied to the machine’s engine and kept in step with it, so its models match your Mac’s: one you add, switch to or sign out of here does the same there right away, or the next time the machine connects. Your agents, permissions, MCP servers and integrations go along too, with your sign-ins to them and their keys, which the machine keeps in files only you can read while its engine runs; a project’s own opencode.json there wins over them, as on your Mac. An MCP server that runs a command runs it on the machine.

If a machine’s sign-out fails, Kuvo Code keeps it to try again the next time it syncs, until the copy there is gone.

If another Mac of yours started the machine’s engine, Kuvo Code uses it as it is, with that Mac’s accounts and settings, rather than starting it over under its work.

The side panel

Changes, Files, the terminal and Run work on the machine: the terminal is the machine’s own shell.

The browser runs on the machine too, so the agent’s browsing carries on while your Mac is off, and localhost in it is the machine. In a session on the machine, the panel’s browser tabs are that browser’s pages, live: new tabs open there, a page the agent opens shows up as a tab, and the tab you pick is the page the agent continues on. Your Mac’s browser tabs show only in sessions on your Mac.

Click, scroll and type in its pages as in any browser; a right-click offers to open or copy a link, and ⌘ + and ⌘ − or a pinch zoom (zoomed out, a page lays out as wide as on a desktop). What a page downloads stays on the machine, and Save to Mac copies it into your Downloads folder. The browser keeps its own sign-ins, which stay on the machine, and its open pages come back when it starts again.

Remove a machine

In Settings › Machines, Remove… signs out of your accounts there, stops its engine and takes its projects out of the sidebar. Its sessions stay on the machine, for when you add it again. To remove Kuvo Code from the machine, run rm -rf ~/.kuvo-code there.