Installation¶

SimpleTechnical

Setting up roamd takes three steps: make an account, install roamd on a computer, and approve that computer. It takes about five minutes.

 1. Account            2. Install               3. Approve
 (in your browser)     (on the computer)        (both together)

 dev.roamd.co.uk  -->  paste one command  -->  roamd login
 email + password      into its terminal       click Approve
 save recovery key                             check the 6 digits match
                                               type y

1. Make an account¶

Go to dev.roamd.co.uk and enter the preview access password we gave you.
Choose Create account. Enter your email and a master password (at least 10 characters; a few random words work well).
You'll see a recovery key like ABCD-EFGH-… (9 groups of 4). Write it down or save it in your password manager. If you ever forget your master password, it's the only way back in. We can't reset it for you.

2. Install roamd on the computer you want to reach¶

Open a terminal on that computer and paste one of these. You don't need to be an administrator.

Linux or Mac (Terminal):

curl -fsSL https://dev.roamd.co.uk/install.sh | sh

Windows (PowerShell):

irm https://dev.roamd.co.uk/install.ps1 | iex

The installer checks the download hasn't been tampered with before installing it. You can also copy these commands from My devices → Add a machine in the app.

3. Approve the computer¶

On the computer, run:
```
roamd login
```
It prints a link. Open it in your browser (logged in to roamd) and click Approve.
Your browser and the computer each show a 6-digit pairing code. If they match, type y on the computer. If they don't, type n: something is wrong, and nothing is trusted.
Start it:
```
roamd run
```

The computer now shows as online in My devices.

4. Optional: start roamd automatically¶

So you don't have to run roamd run by hand after every restart:

roamd service install

roamd now starts when you log in to that computer, and restarts if it ever crashes. On a Linux server that nobody logs in to, it also prints one extra command to keep it running.

Requirements¶

	Supported
Browser	Current Chrome, Edge, Firefox, Safari (WebAssembly and WebCrypto random numbers)
Linux	x86_64 and aarch64; static musl binaries, no dependencies
macOS	Apple Silicon and Intel; ad-hoc signed (install from Terminal: Gatekeeper blocks browser downloads of unsigned binaries)
Windows	x86_64 (ARM64 via emulation); Windows 10 or later

macOS and Windows builds are cross-compiled and not yet tested on real hardware.

Account¶

The account is created in the browser: email plus master password (minimum 10 characters). The browser derives keys locally, creates the vault, and shows the recovery key once. See Accounts and the vault.

Installing the agent¶

curl -fsSL https://dev.roamd.co.uk/install.sh | sh        # Linux, macOS
irm https://dev.roamd.co.uk/install.ps1 | iex             # Windows PowerShell

 installer
   |
   +-- detect OS + CPU (uname / PROCESSOR_ARCHITECTURE)
   +-- download roamd-<os>-<arch> and SHA256SUMS over HTTPS
   +-- verify SHA-256; abort on mismatch or missing entry
   +-- install: ~/.local/bin/roamd              (Linux, macOS)
   |            %LOCALAPPDATA%\roamd\bin        (Windows; added to user PATH)
   +-- no root/admin, no services created

Binaries and SHA256SUMS are also linked from My devices → Add a machine.

Enrolling a machine¶

roamd login [--hub URL] [--name NAME] [--config DIR]

 machine (roamd login)          hub                          browser (logged in)
 ---------------------   ------------------------   -----------------------------
 create host key (Ed25519)
 register name, host key --> pending approval
                         <-- short code (15 min)
 print approve link                                   open link
                                                      GET pending -> name, host fp
                                                      Approve: send browser pubkey
                             device record created <--
 collect result          --> device id, token,
                         <-- browser pubkey
 show pairing code                                    show pairing code
   (6 digits from SHA-256 over both fingerprints)
 user types y
 save browser key -> authorized_keys
 save device.json (hub, id, token)

The machine trusts nothing until the user confirms on the machine that the pairing codes match. A hub that swapped either key would produce different codes.

Running and autostart¶

roamd run [--config DIR]
roamd service install | uninstall | status [--config DIR]

OS	Service	Location
Linux	systemd user unit, `Restart=on-failure`	`~/.config/systemd/user/roamd.service`
macOS	LaunchAgent, `KeepAlive` on non-zero exit	`~/Library/LaunchAgents/uk.co.roamd.roamd.plist`
Windows	Task Scheduler task at logon, least privilege, restart on failure	task `roamd`

Linux user services stop at logout unless lingering is enabled (sudo loginctl enable-linger $USER). The service runs roamd run --service, which exits 0 when stopping on purpose (machine removed, unsafe settings) so it isn't restarted in a loop. The macOS and Windows service definitions are unit-tested but not yet run on real systems.

Settings folder¶

OS	Default
Linux	`$XDG_CONFIG_HOME/roamd` or `~/.config/roamd`
macOS	`~/Library/Application Support/roamd`
Windows	`%LOCALAPPDATA%\roamd` (local, not roaming)

--config DIR or ROAMD_CONFIG_DIR overrides it.