Remote machines

What a remote machine is

A remote machine is any Linux computer you can open a terminal on: a VPS, a home server, a spare desktop. Your agents, such as Claude Code, Codex or OpenCode, run there in herdr, and One lists them next to the agents on your Mac. They get the same rows, the same chat, the same Inbox cards and the same actions: reply with text, photos and files, answer their questions, stop or kill them, and start new ones in a folder on that machine.

A small program on the machine, the One connector, keeps an outgoing connection to One. The machine needs no open port, and your phone never needs SSH access to it. Everything it sends is end-to-end encrypted to your devices.

Before you start

• A Linux machine, x64 or arm64, with curl. systemd keeps the connector running; without it, you run it under your own process manager.
• The user your agents run as. Do everything as that user, not with sudo: herdr only lets its own user in, so the connector has to be the same user.
• Claude Code or Codex, installed and signed in on the machine. One never installs, updates or signs in either of them.
• One on your Mac, signed in to your account, and on your iPhone or in your phone’s browser at getone.one/remote, connected with the code on your Mac.

Add a machine

In One, open Add a remote machine: on your Mac, Remote access → A remote machine; on your phone, Settings → Phone & machines → Remote machines. One makes an invite and offers three ways to use it. All three use the same invite, which works once, for 30 minutes. When the machine connects, One says so and its agents appear in your list.

Run a command (recommended)

Copy the command and paste it into a terminal on the machine, as the user your agents run as. It looks like this:

curl -fsSL <SERVER>/i/<INVITE> | ONE_PAIR=<FINGERPRINT>:<SECRET> sh

It then:

1. uses Node.js 22 or newer if the machine has it, or installs Node.js 22 for the connector alone, in ~/.local/share/one-node/node, checked against nodejs.org’s checksums;
2. downloads the connector and checks its SHA-256 checksum;
3. installs herdr if it’s missing, and leaves an installed herdr exactly as it is;
4. pairs the machine with your account using the invite;
5. starts the connector as a service that survives logout and reboot.

Nothing else on the machine changes. The pairing secret travels in an environment variable rather than on the command line, so other users on the machine can’t read it from the process list. On your Mac, Install over SSH runs the same command through your own ssh, with a host from ~/.ssh/config.

Ask your agent

If Claude Code or Codex is already running on the machine, copy the prompt from One and paste it into the agent. The prompt asks it to run the same command once, as its own user and without sudo, and to reply with the last lines it printed, including the pairing code. If the command fails, the agent shows you the error and stops, rather than working around it or changing anything else.

Do it by hand

For full control, run the steps one at a time. One shows them with your invite’s values filled in, each with its own Copy button, and they’re explained in full below.

The manual steps

Run these on the machine as the user your agents run as. The values in angle brackets come from One: open Add a remote machine → Do it by hand and copy each step from there, already filled in.

1. Install herdr

curl -fsSL https://herdr.dev/install.sh | sh

Skip this if herdr is already installed. herdr is the terminal workspace your agents run in; it installs into ~/.local/bin.

2. Check Node.js 22 or newer

node --version

It should print v22 or later. If it doesn’t, install Node.js 22 from nodejs.org or your package manager first.

3. Download the connector and check it

mkdir -p ~/.local/share/one-node && cd ~/.local/share/one-node && curl -fsSL <SERVER>/v1/machines/one-node.mjs -o one-node.mjs && echo "<SHA256>  one-node.mjs" | sha256sum -c

The check should end with one-node.mjs: OK. The connector is a single file with no dependencies, so you can read it before you run it.

4. Pair it with your account

ONE_SERVER=<SERVER> ONE_PAIR=<FINGERPRINT>:<SECRET> node one-node.mjs pair --invite <INVITE>

It prints the code of the device that made the invite. Check that it matches that device’s own code, listed under Devices that can control your machines. One shows the machine by its hostname; add --name "…" to pick another name.

5. Keep it running

node one-node.mjs install-service

This sets up a systemd user service called one-node that starts again after a reboot. If it asks, run sudo loginctl enable-linger $USER once so it keeps running after you log out. Or run node one-node.mjs run under your own process manager instead.

Within a few seconds, One says the machine is connected and its agents appear in your list.

What the connector does

• Reads herdr’s list of agents and each agent’s conversation, from Claude Code’s and Codex’s own session files, or from the terminal screen when there is none. It looks every 2.5 seconds while you’re watching and every 10 seconds otherwise, so questions reach you.
• Acts only on requests signed by one of your approved devices: it types your message into an agent, answers a numbered question with its digit key after checking the question is still the one you answered, presses Esc to stop an agent, closes its herdr pane to kill it, and starts a new agent in a folder the machine offers.
• Saves photos and files you send under ~/.cache/one-node/attachments, readable only by you, and deletes them after a day.
• Starts herdr’s server when none is running, so agents can start after a reboot. It never restarts a running one.
• Updates itself only when you say so: a newer connector shows up in One’s Inbox as Update One on <machine>, and the machine checks the new file’s checksum and version before it installs it. Your agents keep running.
• Checks every 10 minutes whether Claude Code and Codex are signed in, without changing anything.
• Runs as a service with limits: low priority, at most 200 MB of memory and a quarter of one CPU core, and no way to gain new privileges.

What it never does

• Update herdr, Claude Code or Codex, or sign them in. It never reads or sends their credentials. (The one-line command installs herdr only when it’s missing.)
• Run any other command on behalf of One’s servers.
• Listen on a port, or need root.
• Update itself without your approval.

Privacy and security

• End-to-end encrypted. Agent names, conversations, questions, photos and files are encrypted on the machine for your approved devices only (AES-256-GCM, with a key for each machine). One’s servers pass them on but can’t read them.
• Signed commands. Every message, answer, stop, kill and new agent is signed by one of your approved devices, and the machine checks the signature itself. Someone who gets into your One account still can’t make the machine do anything without one of your devices.
• Devices you approve. A new device joins only when you approve it on a device you already use. A phone connects by scanning the code on your Mac: the code carries your Mac’s keys and a secret that never reaches One’s servers, so pressing Allow on the Mac is the only step. Other devices compare codes on both screens. Removing a device is permanent: every machine refuses it and switches to a new key that device never gets.
• What One’s servers can see: which agents exist on the machine and their state (working, waiting or finished), when things happen, and the machine’s name. They can delay or drop messages. And like any hosted installer, the install script is trusted when you run it; doing it by hand lets you read the connector first.
• No suggested replies. One doesn’t suggest replies for agents on remote machines. The connector’s setting for them is off by default: check it with node one-node.mjs suggestions and turn it off with node one-node.mjs suggestions off. An older connector with it on still sends the end of a finished agent’s screen to One’s server, which discards it.

Everyday commands

Run these on the machine, as the same user, in ~/.local/share/one-node. If the one-line command installed Node.js for the connector, use ~/.local/share/one-node/node/bin/node where these say node.

• node one-node.mjs status
  Whether the machine is paired, which devices it trusts, and whether herdr, Claude Code and Codex are ready.
• node one-node.mjs doctor
  The same, plus how many agents it sees, whether the service runs and whether One’s server can be reached.
• node one-node.mjs uninstall-service
  Stops the service and removes it.
• node one-node.mjs unpair
  Deletes this machine’s credentials. Remove the machine in One as well.
• journalctl --user -u one-node
  The connector’s log.

Remove a machine

Remove it in One first, under Remote machines: it stops taking commands at once. Then clean up on the machine:

node one-node.mjs uninstall-service node one-node.mjs unpair rm -rf ~/.local/share/one-node ~/.config/one-node ~/.cache/one-node

herdr stays installed. Remove it with herdr’s own instructions if you want to.

Troubleshooting

“herdr isn’t running”

The connector starts herdr’s server by itself when none is running, within about a minute. If the message stays, run herdr status and node one-node.mjs doctor on the machine. If herdr says its client and server don’t match, which can happen after an update, restart herdr yourself: One never restarts it.

“Claude Code is signed out here” or “Codex is signed out here”

Sign in on the machine itself: run claude and type /login, or run codex login --device-auth. One checks again within 10 minutes.

The machine shows Offline

• Check the service with systemctl --user status one-node, and start it with systemctl --user start one-node.
• If it stops when you log out, run sudo loginctl enable-linger $USER once.
• Run node one-node.mjs doctor: it says whether One’s server can be reached from the machine.

“This invite expired”

Each invite works once, for 30 minutes. Make a new one in One and run it again.

“That machine couldn’t prove it ran your invite”

The machine that used the invite didn’t have its secret, usually because the command was changed on the way. Remove that machine from the list, make a new invite and copy it again.

An agent doesn’t show up

Only agents running in herdr, as the same user as the connector, show up. Start them in herdr, or from One with New agent….

“This connector is too old”

Approve Update One on <machine> in One’s Inbox. A connector older than 0.6.4 can’t install an update by itself: the card then gives you a command to run once on the machine.

“The device that added this machine was removed”

The machine then trusts no one, on purpose. Remove it and add it again from a device you still use.

Still stuck? Email support@getone.one with what node one-node.mjs doctor prints. Leave out the pairing secret and anything else you’d rather keep private.