Remote machines (SSH)

Kanbell can start an agent on another machine, such as a VPS, over SSH. The session shows in the sidebar like a local one, with the name of the machine on it. The agent runs in tmux on the remote machine, so it keeps working when you close Kanbell.

There is no Kanbell server in the middle. Everything goes through SSH, with a reverse tunnel back to your Mac.

What you need

• SSH access to the machine, with a user that can log in.
• A Linux machine.
• apt or dnf on the machine, to install tmux if it is missing.
• curl 7.76 or newer on the machine: Kanbell's relay uses it to report status, questions and the board.
• A project whose folder is a git repository with a remote, so Kanbell can find the same folder on the machine.

Add a machine

1. In a project, click + and choose On a machine….
2. Pick a host from your ~/.ssh/config, or add user@host.
3. Kanbell runs the guided setup below. You do it once per machine.

The guided setup

1. Connection. Kanbell connects and asks you to check the host fingerprint.
2. A dedicated SSH key. If the machine asks for a password, Kanbell offers to put a dedicated key on it. It does so only with your approval. Kanbell never stores or types a password.
3. The project folder. Kanbell finds the project's folder on the machine from its git remote.
4. tmux and Claude Code. If they are missing, Kanbell installs tmux (with apt or dnf) and Claude Code (with the official installer). It asks first.
5. Claude signs in on the machine. Either through the sign-in page opened on your Mac, or with an API key.

If the folder is not on the machine, Kanbell does not clone the repository. It shows the git clone command for you to run.

Close Kanbell, come back later

The agent keeps running in tmux. When you reopen Kanbell, it reconnects and reattaches to the session on its own, without a click.

The questions that arrived while you were away are in the menu bar panel, ready to answer. You get a single notification, not one per question.

What works like a local agent

• The state of the session: working, waiting, finished.
• Questions and permission requests, in the menu bar panel.
• The task board and the kanbell command for the agent.
• A label with the machine name on the session.

See Answer your agents and Task board.

When the machine is unreachable

The session turns grey and Kanbell reconnects by itself. A lost connection is detected in about twenty seconds. The agent is not stopped: it keeps running in tmux on the machine.

Limits

• Claude Code only. Codex and Gemini CLI do not run on a remote machine.
• Linux machines only.
• A remote session shows as a terminal, not in the Focus view.
• Kanbell does not clone the repository on the machine.

Back to Sessions and terminals.