Quick start

Get Raemote running

Five minutes: install the server on the computer that runs your apps, install the app on your phone (or pair a browser instead — step 6), scan one QR code.

1 Before you start

Will your app work? Check in ten seconds. On the computer that runs it, open http://localhost:<port> in a browser — the same address you'd use locally. If the page loads, Raemote can reach it too.

From a terminal, that's one line:

curl -I http://localhost:3000

What that check is really doing is exactly what Raemote does when it looks for apps: it asks each local port for its page and keeps the ones that answer with a real web page. So if it loads for you, Raemote will find it.

Raemote speaks plain HTTP — what a lot of self-hosted software serves out of the box. An app you've already put behind HTTPS with a certificate won't be reachable yet; that's the next thing we're building.

Nothing loading yet? That's fine — you can also add one by hand later with raemote apps add <name> <port>.

You'll also need

A Mac (Apple Silicon or Intel) or a Linux machine (x86_64 or arm64 — a Raspberry Pi is fine) that runs the web apps you want to reach.
An iPhone. The app targets iOS 27 or later.
Nothing exposed to the internet: Raemote keeps everything on your machine and hands it only to devices you paired.

Don't have any apps running yet? A dev server is enough — start anything that serves a web page and Raemote will show it.

2 Install the server

curl -fsSL https://github.com/raemote/raemote_cli/raw/main/install.sh | sh

On a network where GitHub is slow or blocked, use the Gitee mirror:

curl -fsSL https://gitee.com/pppkin/raemote_cli/raw/main/install.sh | sh

The installer puts raemote and raemoted in ~/.local/bin, installs a background service (launchd on macOS, systemd on Linux), starts it, and prints your pairing link.

Installer options and AI agents

Useful flags: --no-service, --bin-dir <dir>, --proxy <url>, --source gitee|github, --tag <tag>, --quiet.

For an AI agent or a script, --json writes one JSON object to stdout (including the node id and the pairing uri) and all progress to stderr, and exits non-zero on failure:

curl -fsSL https://github.com/raemote/raemote_cli/raw/main/install.sh | sh -s -- --json

Full contract: agent-install.md.

Prefer to read it first? Download install.sh, then run sh install.sh.

3 Install the phone app

Install Raemote from TestFlight on your iPhone (iOS 27+), then open it. There is no account to create and nothing to sign up for.

A browser is an equal option: raemote connect pairs a computer and serves these same apps — step 6. One link can pair both.

First launch shows a Safari “Not Secure Connection” page? That is Safari's own warning for the plain-HTTP loopback address Raemote uses inside the app — the hop to your computer is still end-to-end encrypted. Turn it off in Settings → Apps → Safari → Privacy & Security → Not Secure Connection Warning.

4 Pair your phone

On the computer that runs the server:

raemote pair

It prints a raemote:// link and a QR code. In the app, tap + and scan it — or paste the link with Manual Setup. You do this once per device.

The same link pairs a computer: run raemote connect '<link from raemote pair>' and it becomes another paired device (step 6).

The link is short-lived (five minutes by default) and can pair more than one device until it expires. Print a fresh one any time with raemote pair.

A longer-lived link, or pairing another device later

For a link that stays valid, pin a token and a long TTL in ~/.raemote/config.toml:

[bind]
token = "…64 hex characters…"
token_ttl_secs = 3153600000

then run raemote pair again. Treat that link as a secret: anyone holding it can pair. Or skip the server entirely — from an already paired device use … → Invite Device… in the app for a one-time code.

Pair a device that should only reach some apps

By default a pairing link grants every app the server can see. To share only some, list the ports:

raemote pair --ports 8096,3000

That device's app list shows only those apps, and opening anything else is refused. You can narrow or widen a paired device later — it takes effect immediately:

raemote devices access <id> --ports 8096
raemote devices access <id> --all

Invitations follow the same rule: a limited device sharing … → Invite Device… can pass on everything it has or a narrower selection — never more than its own grant. Access is per port, so two apps behind the same port are allowed or refused together.

5 Use it

Your paired servers appear in the app; open one to see the apps raemoted found.
Tap an app to open it in Safari. Each app keeps its own origin, so logins and site data survive.
Open a second app and both stay running — the Recent row switches between them instantly, with page state intact.
The app refreshes itself when you return to it; tap … → Refresh Apps to scan again right away.

If an app never shows up, pin it by hand:

raemote apps add jellyfin 8096
raemote apps list

6 Use it in a browser

raemote connect is a full client, exactly like the phone app: pair this computer with the same link and serve your apps in a browser:

raemote connect '<link from raemote pair>'   # pair and open
raemote connect                              # reopen the last server

The app list is served on 127.0.0.1:7788 (move it with --port), and every app gets its own loopback port so its URLs, cookies and logins behave exactly as they do on the server. The paired computer appears in raemote devices list like any phone — name it, restrict it, revoke it. --no-open skips launching the browser.

7 Day-to-day commands

Command	What it does
`raemote status`	is the service running, and how many apps were found
`raemote doctor`	health check: daemon, permissions, config, discovery, relay
`raemote discover`	scan for apps right now (add `--verbose` to see what was skipped and why)
`raemote apps list`	the merged app list, with where each entry came from
`raemote apps hide <name>`	drop a false positive (`unhide` restores it)
`raemote devices list`	paired devices — names, node ids, and what each can reach
`raemote devices rename <id> "Living Room"`	give a device a readable name
`raemote devices revoke <id>`	cut a device off immediately
`raemote devices access <id> --ports 8096`	limit a device to specific apps (`--all` restores everything)
`raemote config set name "Mac mini"`	rename the server as paired devices see it
`raemote logs -n 50`	recent activity (`--follow` to stream)
`raemote restart`	restart the service after a config change

8 If something looks wrong

Start here:

raemote doctor

Symptom	Fix
An app isn't listed	`raemote discover --verbose` to see why it was skipped; then `raemote apps add <name> <port>`
The app can't be reached	check it answers `http://localhost:<port>`; HTTPS-only apps are not supported yet
The phone says it is not authorized	it was revoked, or the server's identity changed — run `raemote pair` again and re-scan
Doctor reports the relay unreachable	on a restricted network, set an outbound proxy: `raemote config set network.proxy http://host:port` then `raemote restart`
Safari shows a “Not Secure” page	that is Safari's loopback warning; switch it off in Settings as noted above
Nothing works after editing config	`raemote reload` for most settings, `raemote restart` for network or identity changes

9 Remove it

curl -fsSL https://github.com/raemote/raemote_cli/raw/main/install.sh | sh -s -- --uninstall

Add --purge to also delete ~/.raemote — the server identity and the list of paired devices. Revoking a device from raemote devices is enough to cut off access without uninstalling anything.

Security reports and privacy questions: cool@lyuhj.top · SECURITY.md · PRIVACY.md