Start

Pairing

Other machines use the cloud without the owner token: each one pairs once and holds its own device token, which you can revoke. A device must have the plugin installed first (omp plugin marketplace add TechDufus/omp-cloud, then omp plugin install omp-cloud@omp-cloud, then /restart; Other machines), because /cloud connect is a plugin command. omp-cloud setup creates the TLS identity (~/.config/omp-cloud/tls/: a self-signed P-256 key, 0600 in a 0700 directory, and its certificate, valid for 100 years, generated by setup itself with no openssl) and the remote section of service.json once; it never overwrites either. On an existing service.json it adds a missing remote section. The listeners are defined in API; the limits on offers, codes and attempts are in Devices and pairing.

Add a device#

On the service host, in omp's interactive UI: /cloud pair. It shows the code as text with a countdown (it works once and expires after a few minutes), and sends it to your clipboard once (through the terminal's clipboard escape sequence, so over SSH or Tern remote it can land on the machine you type on). Nothing confirms the copy and some terminals ignore the sequence (tmux by default, VTE terminals): if pasting fails, copy the code from the overlay by hand. Esc closes the overlay and cancels the code. The dashboard's Devices page shows the code with a Copy button.
On the other machine, in omp: /cloud connect and paste the code (or /cloud connect <code> [--name <name>]). The device is named after the machine unless --name gives a name of 1 to 64 letters, digits, spaces, ., _ or -. A machine that is already connected refuses until --replace, which pairs again and revokes the old device. There is no QR code: the other machine is a computer running omp, and nothing in the flow scans one.
The device reads the certificate of the remote listener and goes on only if its fingerprint equals the one inside the code. It then asks to pair, and the service host shows name · platform · address: press y to approve or n to decline (the dashboard has Approve and Decline). The device waits, with a countdown, and only after approval does it receive its token, once.
The device keeps the pinned certificate and its token in ~/.config/omp-cloud/connection.json (0600; $XDG_CONFIG_HOME, %APPDATA% on Windows, where file modes do not apply). An OMP_CLOUD_URL or a url in config.yml wins over it; /cloud status says which connection is in use.

Over SSH#

If you can ssh to the service host's account, skip the code: /cloud connect user@host (also host or ssh://user@host:2222) asks the service host's own omp-cloud ssh-pair to create the device, and there is nothing to approve, because being able to log in to the service's account is the proof that you own it. ssh runs without a password prompt, so key-based login and a known host key are needed (it tells you what to run: ssh user@host once to accept the host key, ssh-copy-id). The certificate fingerprint arrives over ssh, and nothing is sent to an address until the certificate there matches it; the device then writes connection.json as above. OMP_CLOUD_SSH names another ssh program (a file name, no arguments). The service host needs the omp-cloud command, installed by omp-cloud setup (mise run infra:up in a checkout), and the service must have run once on that account (the command never migrates the database, and says to restart the service or git pull when its schema differs from the one this omp-cloud expects). If omp-cloud is not found there, the error says to install it there and run omp-cloud setup; the agent prompt for a remote service host does both ends.

Manage devices#

/cloud devices (or the dashboard) lists them with when and from where each was last seen; /cloud devices revoke <name|id-prefix> revokes one after a confirmation. Revoking is immediate: its next request gets 401, and its open event streams and in-flight requests end. Threads it started keep running; the command lists them. /cloud disconnect revokes this machine's device and deletes connection.json (--force deletes the file even when the service cannot be reached, and the token then stays valid until you revoke it on the service host).

On a paired device, /cloud dashboard starts a loopback forwarder (127.0.0.1, random port, one-time sign-in link) that relays the dashboard and its API to the service over the pinned connection. Devices can do what the owner does with threads (launch, send, answer, stop, pull, delete); they see only their own entry in the device list and cannot create or approve pairings, change settings, run provider logins, mint dashboard links or revoke other devices (API). When the cloud has no login for a provider, the device is told to log the server in on the server machine: omp-cloud login <provider>, over ssh as ssh -t <user>@<host> '~/.local/bin/omp-cloud login <provider>' (/cloud login is refused on a device without a request).

What crosses the network#

TLS to the remote listener, which serves the self-signed certificate; the device pins its fingerprint and trusts no certificate authority, so a different certificate at the same address is refused before anything is sent. The device token travels only in the Authorization header over that TLS connection. The owner token never does (the remote listener rejects it), and neither do provider or git credentials. The pairing code holds a one-time secret the service stores only as a hash, and device tokens are stored hashed (SHA-256) in the database; the plaintext exists only in each device's connection.json. The unauthenticated pairing routes answer every failure alike and rate-limit wrong attempts (API).

Who may connect#

The remote listener accepts only private source addresses by default and always refuses the gateway address; remote.allow replaces the list of sources and remote.advertise sets the addresses a code names (default list and settings: configuration). /cloud connect refuses addresses that are not local (loopback, private, link-local, single-label names and names ending .local, .lan, .home.arpa or .internal count as local) unless --allow-public.

Firewall#

Allow TCP 8443 from your LAN to the service host, for example sudo ufw allow from 192.168.0.0/16 to any port 8443 proto tcp. Setup never changes firewall rules.

Backups and identity#

A device is a database row, so restoring an older backup brings back devices you revoked after it was taken: revoke them again. The TLS identity lives with the service config, not in the backup archive. If tls/ is replaced or lost (omp-cloud uninstall --purge removes it), every device's pin stops matching and each must pair again.