Connect OC Remote securely with pairing, Tailscale, or HTTPS

OC Remote sends credentials, prompts, attachments, commands, and session data to the OpenCode endpoint you configure. HTTPS encrypts that traffic in transit and is the right choice for any public route.

Direct HTTP is intentionally limited to loopback, private IPv4 and IPv6 networks, link-local addresses, and Tailscale's private address range. This supports trusted LAN and Tailnet setups without allowing a cleartext public hostname.

1. Start and inspect stable V2

opencode service start
opencode service status

Stable V2 defaults to port 49374 on macOS, Linux, and WSL, and45278 on Windows. Use the status output instead of assuming the default.

2. Choose how the iPhone reaches the host

Trusted LAN

A numeric private address such as http://192.168.1.42:49374 can work while the phone is on the same trusted network. HTTP does not encrypt the traffic, so do not route it over an untrusted network.

Tailscale

A direct 100.64.0.0/10 Tailnet address is accepted as a private route. For a trusted HTTPS hostname, publish the current service port with Tailscale Serve and generate the pairing link with that URL:

tailscale serve --bg 49374
opencode pair --url https://<machine>.<tailnet>.ts.net

Public HTTPS reverse proxy

If the phone reaches the server through a public hostname, terminate TLS with a certificate the device trusts. A minimal Caddy route looks like this:

code.example.com {
  reverse_proxy 127.0.0.1:49374
}

Nginx uses the same pattern:

server {
  listen 443 ssl;
  server_name code.example.com;
  # Configure a certificate and key the phone trusts.

  location / {
    proxy_pass http://127.0.0.1:49374;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
  }
}

3. Create a reachable pairing link

Use opencode pair when the generated candidates are already reachable. If it prints a loopback URL, pass the LAN, Tailnet, or HTTPS origin explicitly:

opencode pair --url https://code.example.com

A 127.0.0.1 URL on the phone points to the phone itself. OC Remote can also redeem the one-time code after you enter a separately reachable Tailscale URL in the connection editor.

4. Pair and verify

In Settings → Connection, scan the QR code or paste the pairing link. Links work once and expire after five minutes. OC Remote validates the redeemed token against an authenticated route before saving it in the iOS Keychain.

Manual URL, username, and password entry remains available for classic V1 and dedicatedopencode serve setups. Remove a connection in the app to delete its saved Keychain credential.

Continue with the complete iPhone setup, or learn how to handle a waiting agent.