Skip to content
Octoboard Docs

Browser over Tailscale

Open Octoboard in a browser on another computer through your own Tailscale network, without SSH or a remote desktop. The host is the computer that runs Octoboard: a Mac, a Windows PC or a Linux server running octoboardd. SSH sign-in (Remote Login on macOS) can stay off.

Not sure this is the way for you? See Choose how to connect.

Browser on your computer → relay on your computer (127.0.0.1) ⟷ Tailscale ⟷ relay on the host (127.0.0.1) → Octoboard

New to this?
  • Tailscale: a service that links your devices into a private network over the internet, wherever they are. You sign in to it with your own account.
  • Tailnet: your Tailscale network: the devices signed in to your Tailscale account.
  • 127.0.0.1 (loopback): an address that always means “this same computer”.
  • Port: a number that picks one program on a computer, like a door number. 127.0.0.1:3369 is port 3369 on this computer.
  • socat: a small, free program that passes a connection from one place to another. Here it’s the relay.
  • Tailscale Serve: a Tailscale command that shares a port with your tailnet only. Its cousin, Tailscale Funnel, would share it with the whole internet; never use it here.
  • Terminal: the window you type commands into: Terminal on macOS, PowerShell on Windows.

For safety, Octoboard only accepts a browser that opens it at 127.0.0.1, an address that always means “this same computer” (also called loopback). So you can’t just type the host’s Tailscale address into the browser. Instead, you run a small relay program on each computer: on your computer it makes the host look local at 127.0.0.1; on the host it hands the connection to Octoboard. Tailscale carries the traffic between the two.

  • Tailscale on both computers, signed in to the same tailnet. Use a tailnet that holds only your own devices: every device it lets reach the host can reach the port you share.

  • socat on each computer that is a Mac or runs Linux. A Windows computer doesn’t need it.

    Install Homebrew first if you don’t have it (macOS ships no tool that can do this job), then run this in Terminal:

    Terminal window
    brew install socat
  • Two or three windows left open while you work: the relay and Tailscale Serve on the host (except the relay on Windows), and the relay on your computer (except on Windows).

  1. Get the browser address, which carries the key that signs the browser in.

    In Octoboard, open Settings › Remote access, turn on Allow remote access and select Allow to confirm. Two tabs then appear below the switch. On the Browser tab, select Copy address under Step 2: Browser address.

    Get the address to the other computer in a way only you can read, such as a note to yourself: it works like a password.

    Skip Step 1: SSH forward. The app’s settings mention SSH in several places; you can ignore that here, since this guide uses only the browser address.

    Keep Octoboard running: if you quit it, remote access stops.

  2. Start the relay on the host, which connects a port on the host’s 127.0.0.1 to Octoboard. This port is the host port in the steps below.

    Run this in Terminal and leave the window open. It listens on 127.0.0.1:3370 alone.

    Terminal window
    socat TCP-LISTEN:3370,bind=127.0.0.1,reuseaddr,fork UNIX-CONNECT:"$HOME/.octoboard/browser.sock"

    The host port is 3370.

  3. Share the host port with your tailnet with Tailscale Serve, and leave the window open. Never use Tailscale Funnel, which would put it on the public internet.

    Terminal window
    tailscale serve --tcp=3370 tcp://127.0.0.1:3370

    With the Tailscale app from the App Store, run the command as /Applications/Tailscale.app/Contents/MacOS/Tailscale in place of tailscale. With the standalone app, install the command first from its settings, under CLI integration.

    To check, run tailscale serve status in another window: it should list the host port.

  1. Find the host in the Tailscale app on this computer, and note its name (such as my-mac) or its address (a number like 100.x.y.z).

  2. Start the relay on this computer, which makes the host appear at 127.0.0.1:3369 here. If port 3369 is already taken on this computer, pick another port and change it in the browser address too.

    In the command below, replace <host> with the host’s name or address, and <host port> with the host port.

    Terminal window
    socat TCP-LISTEN:3369,bind=127.0.0.1,reuseaddr,fork TCP:<host>:<host port>

    For example, for a Mac host named my-mac:

    Terminal window
    socat TCP-LISTEN:3369,bind=127.0.0.1,reuseaddr,fork TCP:my-mac:3370

    Run it in Terminal and leave the window open.

  3. Open the browser address you copied on the host. It starts with http://127.0.0.1:3369/.

You’ll know it worked when Octoboard opens in the browser tab without asking you to sign in.

  • The page doesn’t load: one of the windows was closed, or its command stopped. Check that the relays and Tailscale Serve are still running, and that tailscale serve status on the host lists the host port.
  • socat says “Address already in use”: that port is taken on that computer. Pick another port; on your computer, change it in the browser address too.
  • The page is refused or blank: check that you opened the address at 127.0.0.1, not the host’s Tailscale name or 100.x.y.z address.
  • The relay on the host prints “Connection refused” or “No such file or directory” when you open the page: Allow remote access is off, or Octoboard isn’t running on the host (on Linux, octoboardd isn’t running).
  • On the computer you browsed from: stop socat with Ctrl+C, or on Windows delete the forward in PowerShell run as administrator:

    Terminal window
    netsh interface portproxy delete v4tov4 listenaddress=127.0.0.1 listenport=3369
  • On the host: stop the Tailscale Serve command and socat with Ctrl+C. Check with tailscale serve status that nothing is shared any more; if the port is still listed, remove it with tailscale serve --tcp=3370 off (on Windows, tailscale serve --tcp=3369 off).

  • On a Mac or Windows host, turn off Allow remote access when you no longer need it. This closes the browser entry and disconnects every page opened with the key.

  • If the address may have leaked, give it a new key with Rotate key on the Browser tab, or on Linux with octoboardd address --rotate. Pages open with the old address are disconnected.

  • The address is the password: its key gives full control of Octoboard on the host, running any command included. It lasts until you rotate it. It stays in the browser’s history and bookmarks, and syncs to your other devices if browser sync is on.
  • Who can reach it: anyone who reaches the host port and has the key. The relays listen on 127.0.0.1 only, so other devices on the host’s or your local network can’t reach them; Tailscale Serve makes the host port reachable from your tailnet only, as far as its access rules allow.
  • Only on computers nobody else signs in to: another user account on the host or on your computer can connect to these 127.0.0.1 ports, and while a relay isn’t running it can take its port and receive the key when your browser reconnects. With Connect over SSH, a Mac or Linux host doesn’t have this weakness, and neither does your own computer when you use the desktop app. In a browser your computer still has it, because the SSH forward listens on a 127.0.0.1 port there too.
  • Never Funnel: Tailscale Funnel would publish the port to the whole internet.