Connecting a computer
Business Summary: Connecting a computer lets your coding agents run on a machine you control, using the logins and files already on it. It takes one command and about a minute.
Step-by-step
- Open your profile from the menu under your name, then choose the External agents tab. You need your own profile because computers belong to you, not the workspace.
- In the Computers card, choose Connect a computer. Harmony creates a computer for you and shows a one-line install command with your personal code in it.
- Copy the command with the copy button. Treat it like a password: anyone with it could run agent work on that computer.
- Open Terminal on the computer you want to use and paste the command. The installer checks that Node.js 20 or newer is there, installs the Harmony runner in your home folder, and starts it.
- Watch the dialog in Harmony. When the runner connects, the status changes from Waiting for the runner to Connected as and your computer's name.
- Choose Done. The computer now shows Online in the Computers card, along with how many agents Harmony found installed on it.
flowchart LR
Profile[Profile, External agents]
Connect[Connect a computer]
Command[Run the install command]
Runner[Runner starts and keeps running]
Online[Computer shows Online]
Profile --> Connect --> Command --> Runner --> Online
How this fits in Harmony
A computer is where your external agents run. The Harmony runner is a small program that sits on that computer. It only reaches out to Harmony to ask for work; nothing connects into your computer from outside. When you ask an agent in chat, the runner picks up the request, starts the agent, and sends back what the agent did.
The installer sets the runner to start again by itself when you restart your computer. On a Mac it uses the same system that keeps menu bar apps running. On Linux it uses a background service for your user. You can see its log in the .nimbus folder in your home folder.
What you'll see
Each computer in the Computers card shows a status dot and a short line:
| Status | What it means |
|---|---|
| Online | The runner checked in within the last minute or so and is ready. |
| Offline | The runner has not checked in. The computer may be asleep, offline, or the runner is stopped. |
| Waiting for the runner | You created the computer but have not run the install command yet. |
The line also says how many agents the runner found, for example 5 agents found. When you set up an agent, Harmony tells you whether that agent is installed on the computer you picked.
Pairing again and removing
Pair again gives the computer a new code and shows a fresh install command. Use it when you move to a new machine, or if you think the old command was shared. The old code stops working straight away.
Remove disconnects the computer. Any agent set to run on it shows No computer picked until you choose another.
Example scenario
Marco wants Claude Code to work on his team's repository while he reviews designs. He opens Profile → External agents, chooses Connect a computer, and pastes the command into Terminal on his MacBook. Thirty seconds later the dialog says Connected as Marcos-MacBook-Pro.local and the card shows 5 agents found, because he already has Claude Code, Codex and Cursor installed.
FAQs {#faqs}
Q: What does the runner need? A: Node.js 20 or newer, and macOS or Linux. Windows is not supported yet.
Q: Does the runner open a port or let Harmony into my computer? A: No. The runner only makes outgoing requests to Harmony to collect work and send results. Harmony cannot reach into your computer, and the runner only runs the agents you set up.
Q: Can I connect more than one computer? A: Yes. Connect each one, then choose which computer each agent runs on.
Q: What happens if my laptop goes to sleep while an agent is working? A: The request stops. Harmony notices the computer went quiet after a few minutes and marks the request as failed with a clear message, so you can ask again when the computer is back.
Q: How do I stop the runner?
A: Remove the computer in Harmony to cut it off immediately. To uninstall, delete the .nimbus folder in your home folder and, on a Mac, the ai.gonimbus.runner item in your login items.