Guide · Remote SSH

Run your agents on a remote machine

Komla stays on your computer. Agents, Git, and builds run on any Linux or macOS machine you can ssh into, and they keep going when you close your laptop.

On this page
  1. How it works
  2. What you get
  3. Set it up
  4. Which machine?
  5. Security
  6. What Komla puts on the machine
  7. Good to know
  8. Troubleshooting

How it works

Your computer Komla shows the work
  • Terminals and editor
  • Notifications
  • Browser previews
Keystrokes ssh Output, alerts, Git status
Remote machine The machine does it
  • Agents, running in tmux
  • Repository and worktrees
  • Builds, tests, and Git
Komla uses your system's ssh, so the hosts, keys, and jump hosts in ~/.ssh/config just work. Your code stays on the remote machine.

What you get

The laptop disconnects while the lid is closed, but the agent keeps running and finishes before the laptop reconnects. Laptop Agent lid closed starts a task finishes
Agents keep running

They run in tmux on the remote machine. Lose Wi-Fi or quit Komla, then reattach to the same session.

A desktop and a laptop both connect to one remote machine and see the same workspaces. Desktop Laptop Remote fix-login api-tests docs
Pick up from any computer

Workspaces sync through the remote machine. Start an agent on your desktop, check on it from your laptop.

A daily schedule starts an agent on the remote machine, which works with GitHub, Slack, and other APIs while your computers are off. daily 09:00 Remote agent run GitHub Slack Your APIs your computers can be off
Automations on an always-on machine

Schedule agents that check, report, and update your other systems, or run them on demand. They run through cron with every device off, and each run's workspace shows up on all your computers.

A webhook, a CI failure, or your own script runs komla launch on the remote machine, which opens a new workspace with an agent on the task. Webhook CI failure Your script Remote komla launch Workspace agent a new agent for each event
Custom triggers

Hook up any service. A webhook handler or script on the machine can run komla launch "<prompt>" to start an agent in a new workspace. How.

A dev server on port 5173 on the remote machine is forwarded over SSH and opens at localhost:5173 on your computer. Remote npm run dev :5173 automatic ssh localhost:5173
Dev servers open on your computer

Start a server on the remote machine, then open the preview or click its localhost link. Komla forwards the port over SSH for you, on the same port number when it's free.

A GUI app runs on a virtual desktop on the remote machine and shows on your screen over VNC. Remote VNC Your screen
GUI apps, even without a display

komla desktop run -- <app> starts an app on a virtual desktop on the machine. Use it in a VNC app or in Komla's browser preview.

Files sync one way from the remote machine to a Local copy on your computer, where you run and test them. Remote src/ package.json one way Local copy src/ package.json run, test, and use simulators locally
Run and test locally

A Local copy terminal gets a one-way synced copy of the workspace on your computer, for simulators and tools that only run there.

  • Notifications
  • Live Git status
  • File editing
  • Diffs and commits
  • Browser previews
  • Komla CLI and MCP
Feels local

These work in SSH workspaces too.

Set it up

In Komla, open:

  1. Settings
  2. SSH Hosts
  3. Add SSH host

Komla checks the machine, sets it up, and walks you through the rest. Hosts in ~/.ssh/config are one click away with Fill from ~/.ssh/config…

Which machine?

Any Linux or macOS machine you can reach over SSH.

Spare computer Mac mini or desktop Turn on Remote Login (macOS) or install openssh-server (Linux). Add Tailscale to reach it from anywhere.
Cloud A cloud server From Hetzner, DigitalOcean, AWS, or any provider, sized for your builds.
This computer VM or container A sandbox where agents can skip permission prompts without touching your files. How.

Security

  • No ports to open on either machine
  • No sudo or package installs on the machine
  • Plain ssh, with your config
  • Komla's data tunnel only on the host's 127.0.0.1

Give the machine its own SSH key. Add a key on the remote machine to your Git host, scoped to the repositories it needs. Agents and automations can then push with every device off, and your other keys stay on your computer.

Forward SSH agent is on by default because it needs no setup. While you're connected, anything running as your remote user can sign with the keys in your ssh-agent, unless they ask for a passphrase or fingerprint on each use. Turn it off in the host's settings once the machine has its own key.

What Komla puts on the machine

Checking a machine changes nothing on it. Setting it up keeps Komla's files in one folder, and anything else waits until you turn it on.

Nothing else in your home folder changes: not your shell's startup files, your PATH, or ~/.tmux.conf. Komla copies the companion from the app over ssh, so the machine downloads nothing, and it never uses sudo or installs packages. If tmux or another tool is missing, setup says so.

What keeps running
  • Terminals run in Komla's own tmux server, tmux -L komla-v1, which doesn't read your ~/.tmux.conf. Agents keep running there after you disconnect; stop a workspace to end them.
  • The companion sends Git status and agent alerts to Komla. It exits on its own soon after your last Komla terminal there ends and Komla is no longer connected.
  • No service, daemon, systemd unit or launch agent, and nothing starts at login or boot. The one exception is the crontab line for automations, below.
Only when you turn it on
  • Notifications and MCP for an agent, in Settings → Integrations & MCP: Komla adds its hooks and a komla MCP server to that agent's own settings on the machine, such as ~/.claude/settings.json and ~/.claude.json. The Komla skill there adds a komla folder to the agents' skills folders.
  • Automations on the machine: one line in your crontab, ending in # komla-automations, that checks each minute whether one is due. Komla leaves your other lines as they are.
  • Phone access to the machine, in Settings → Remote: a server on 127.0.0.1 that Tailscale Serve publishes on your tailnet only. Phones sign in with a passkey, and Komla encrypts the connection end to end on top of Tailscale's, so nothing in between can read or change what you type.
What goes over the network
  • Nothing on the machine listens on a public address. Komla's data tunnel, saved port forwards and the phone server all bind to 127.0.0.1.
  • The machine talks only to Komla on your computer, through ssh, to your Git servers, and, with phone access on, to your phones over Tailscale. There's no telemetry from the machine.

Good to know

Several computers on one machine
  • Workspaces, agent tabs, renames, archiving, and tab layout sync between computers with Sync with other devices on (the default).
  • Opening a synced workspace attaches to the running agents. The computer that attaches takes over the session.
  • Every connected computer shows the agent's notifications.
  • To pick workspaces by hand, turn sync off in the host's Workspaces panel and use Add here.
Local copy details
  • It syncs one way, from the remote machine, with rsync. Local edits aren't sent back and can be overwritten.
  • Gitignored files, such as node_modules and .env, stay put.
  • Choose where Terminal Commands run under the project's SSH workspaces → Run Terminal Commands on.
  • It needs rsync on both machines and isn't available when Komla runs on Windows.
GUI apps: what to install

komla desktop run needs tigervnc-standalone-server on the Linux machine. For Komla's browser preview, add novnc and websockify and pass --browser before the app. Komla suggests it when an app can't find a display.

Run komla launch from your own scripts

Outside Komla's terminals, call the CLI by its full path, <remote Komla path>/helpers/komla (~/.komla by default). Run it as your remote user, from inside an existing workspace's folder or with -C <workspace path>, so it knows which project to use when no computer is connected.

Previews, port forwards, and your own terminal
  • Running several servers? Pick one with Pick a running server or URL in the preview.
  • Saved port forwards, in either direction, live under the host's Advanced. They bind to 127.0.0.1.
  • Copy tmux attach command on a pane's host pill joins the same session from any terminal.
Use a VM or container as a sandbox
  • Lima: add Include ~/.lima/*/ssh.config to the top of ~/.ssh/config, then add the host lima-<name>. OrbStack, UTM, and Multipass also give VMs an SSH login.
  • Docker: install an SSH server, Git, tmux, and curl in the image, publish its port (-p 2222:22), and add localhost on that port.
  • Lock it down: share no folders, give it its own SSH key with Forward SSH agent off, and limit network access with the VM's own settings.

Komla's older sandbox methods are deprecated. A VM or container host replaces them.

Troubleshooting

Check machine can't connect

Run the same ssh command in your terminal. Put jump hosts and aliases in ~/.ssh/config, or under Extra SSH args.

"tmux is required" or a tool is missing

Install it on the remote machine (sudo apt install tmux or brew install tmux), then click Check again.

Cloning a private repository fails

Add the remote machine's own SSH key to your Git host, or load your key into ssh-agent with Forward SSH agent on.

Notifications or MCP don't arrive

Enable the integration on the host's tab in Settings → Integrations & MCP and apply any update. For Codex, run /hooks.

A terminal shows as disconnected

Select the workspace or click Reconnect session. The agent kept running in tmux.

A preview doesn't open

Make sure the dev server listens on localhost on the remote machine, then use Forward Remote Port in the preview panel and enter its port.

Keep your agents working while your laptop sleeps

For macOS, Windows, and Linux.

Download Komla

Need an SSH setup Komla doesn't support yet? Get in touch.