Isomux docs Run a public office with Tailscale Funnel
GitHub

Run a public office with Tailscale Funnel#

This is the Public Tailscale Funnel guide. To check if this is the right hosting setup for you, check the decision diagram.

Use an existing Linux computer or Linux server with systemd, a normal user account with sudo access, and an internet connection. You also need an AI provider account. Keep the computer powered on. Funnel gives the office a public HTTPS address without a domain or router forwarding. Visitors do not need Tailscale, but they still need an Isomux sign-in link.

Install Isomux#

Run these steps on the computer that will run the office, in a terminal under its normal user account.

  1. Install Node.js 24 LTS, version 24.15.0 or later, using the instructions for your operating system. The built-in terminal needs Node.js as well as Bun. Open a new terminal after installation.

  2. Install Git and the native build tools. On Ubuntu or Debian:

    sudo apt update
sudo apt install -y git curl unzip python3 build-essential

    On macOS, run xcode-select --install and complete the installer.

  3. Install Bun:

    curl -fsSL https://bun.sh/install | bash

    Open a new terminal so that the shell can find Bun. Check both runtimes:

    node --version
bun --version

    Node must report v24.15.0 or later in the Node 24 series; Bun must be at least version 1.2.

  4. Download Isomux into a new directory and start it:

    git clone https://github.com/nmamano/isomux.git
cd isomux
bun install
bun run dev

    Leave this terminal open. If the native build fails, check the build recovery instructions.

A Chrome-family browser installed on this computer also enables page-preview cards and app screenshots. It is optional for office setup.

Create the first owner#

On the computer running Isomux, open http://localhost:4000 in a browser. Enter your display name and submit the form. The office opens.

If the server has no browser, keep its Isomux terminal running. On your laptop, open another terminal and run the following, replacing USER and SERVER with your server login and address:

ssh -L 4000:localhost:4000 USER@SERVER

Keep this connection open and visit http://localhost:4000 in your laptop's browser to create the owner. Port 4000 on your laptop must be free.

The office accepts its first owner only through this local connection. Set up remote access after you have opened the office as its owner.

Keep the office running#

These steps use Linux with systemd. Keep the computer powered on and disable sleep in its power settings.

After you have created the owner, press Ctrl+C in the terminal running bun run dev. In that terminal, from the Isomux directory, run:

mkdir -p "$HOME/.config/systemd/user"
cat > "$HOME/.config/systemd/user/isomux.service" <<UNIT
[Unit]
Description=Isomux office
After=network.target
StartLimitIntervalSec=0

[Service]
WorkingDirectory="$PWD"
Environment="PATH=$HOME/.bun/bin:$(dirname "$(command -v node)"):/usr/local/bin:/usr/bin:/bin"
ExecStart="$HOME/.bun/bin/bun" run dev
Restart=on-failure
RestartSec=5s
OOMPolicy=continue

[Install]
WantedBy=default.target
UNIT
systemctl --user daemon-reload
systemctl --user enable --now isomux
sudo loginctl enable-linger "$USER"
systemctl --user status isomux --no-pager

The status should show active (running) after the UI builds. Lingering keeps the service running after logout and starts it at boot. If startup fails, read its log with journalctl --user -u isomux -n 50 --no-pager.

Install Tailscale on your devices#

Create a Tailscale account. On the Linux server, run:

curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up

Open the sign-in link printed in the terminal and add the server to your account. Install Tailscale on your laptop and phone, and sign in to the same account on each device. Keep Tailscale connected.

Open the Tailscale DNS settings. Enable MagicDNS and HTTPS Certificates. HTTPS certificates put the server's *.ts.net name in public certificate records, even when access stays private.

On the server, allow your Linux user to manage Tailscale:

sudo tailscale set --operator="$USER"

Make the office public#

Funnel depends on Tailscale's service and its bandwidth limits. Sign in as a Tailscale owner, admin, or network admin for the authorization step below.

On the server, inspect the current mappings:

tailscale serve status
tailscale funnel status

A port is all-private Serve or all-public Funnel. If port 443 has mappings besides Isomux at localhost:4000, stop. Decide whether to remove each mapping or move it to another port before you continue. Do not expose another service by accident.

Run this command yourself in the server terminal. Claude agents refuse recognized tunnel commands:

tailscale funnel --bg http://localhost:4000

If the command prints an authorization link, open it in your browser and approve enabling Funnel. Tailscale adds the required funnel attribute to the tailnet policy. The default permits tailnet members to use Funnel. To enable it through the admin console instead, open Access controls, expand Funnel, and select Add Funnel to policy. Preserve any existing access policy.

Copy the public HTTPS address from the output. You can read it again with tailscale funnel status. Tailscale relays the connection; TLS terminates on your computer. The *.ts.net name is public and appears in certificate records. See the Funnel reference for custom policy and service limits.

Sign in at the new address#

In the local office, open Settings → Office → Access. Enable External access, paste the HTTPS office address into Public URL, and save. Copy the sign-in link that the pane gives you before restarting.

On the server, run:

systemctl --user restart isomux

Open the copied sign-in link in the browser where you will use the office. Keep the HTTPS office address as your bookmark; sign-in links work only once.

Test the address on a phone with Wi-Fi and Tailscale turned off. A request from the server itself does not prove that public access works.

Connect a provider and send a message#

In the office, open Settings → You → Individual connections.

  • For Claude or Codex, select the provider's sign-in control and complete the instructions shown. If Isomux asks to install the Claude CLI, complete that step first. Codex is bundled with Isomux.
  • For OpenCode, open or create an OpenCode agent and choose a model. Its model picker offers Free, Pay-as-you-go, and Subscription options. A Free model provides a starting path without a paid provider connection.
  • For a provider API key, add its environment variable in Individual connections: ANTHROPIC_API_KEY, OPENAI_API_KEY, or OPENCODE_API_KEY, as applicable.

Open an agent that uses the connected provider and send a short message. A reply confirms that the office can use your provider account. Provider charges and subscription limits are separate from hosting.

For Claude through Amazon Bedrock or another connection method, use the provider reference.

Add people and devices#

For another device of your own, open Settings → You → Sign-in links and create a device link. Open it on that device.

To invite another person, open Settings → Office → Invites, enter their name, select a role and room access, and issue an invite. Send the link privately. Only invite people you trust: members and their agents can run commands on the server with the office's operating-system permissions.

On iPhone, open the office in Safari and select Share → Add to Home Screen. On Android, open the HTTPS office address in Chrome and use its install option.

App addresses#

Funnel exposes the office port only. Tailscale names do not provide wildcard app hostnames, so this setup does not give each app a public address. App port links remain usable from devices with direct or private Tailscale access to the server. Choose the domain setup if each app needs its own public HTTPS address.

Updates and logs#

To update, finish active agent work first. On the server, from the Isomux checkout, run:

systemctl --user stop isomux
git pull --ff-only
bun install
systemctl --user start isomux

The service rebuilds the UI when it starts. Reload the browser after it starts. A stop or restart interrupts active agent turns.

Read office logs with:

journalctl --user -u isomux -n 50 --no-pager

For memory protection, browser control, and deployment boundaries, see the hosting reference.

Backups#

Isomux stores seven daily backups of ~/.isomux/ in the server's backup directory on the same disk as the office, so copy them elsewhere if you need protection from server loss. Current backup health and the exact directory are at GET /api/backup/status.