Isomux docs Run an office at your own domain
GitHub

Run an office at your own domain#

This is the Your computer and domain guide. To check if this is the right hosting setup for you, check the decision diagram.

Use an existing Ubuntu or Debian Linux computer with systemd, a normal user account with sudo access, an AI provider account, and a domain you control. Keep the computer powered on. This setup uses Caddy to serve the office and app addresses over HTTPS.

You need a public IP address that accepts inbound TCP ports 80 and 443. If your internet provider uses carrier-grade NAT, use the Funnel guide or a VPS instead. The public address exposes your home or server IP.

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.

Point the domain at your computer#

  1. Give the computer a stable address on your home network, using your router's DHCP reservation settings.
  2. Forward TCP ports 80 and 443 on the router to that computer. On a rented server, allow those ports in the provider firewall instead.
  3. In the domain's DNS settings, point an A record for office at your public IPv4 address. Add *.office with the same address for apps.
  4. Allow ports 80 and 443 in the computer's firewall. Keep office port 4000 and app ports closed to the public internet. If the public IP changes, update both DNS records, or configure your DNS provider's dynamic DNS client.

Replace office.example.com in the next steps with your chosen domain. Do not add an AAAA record unless you have also configured IPv6 routing and the IPv6 firewall.

Install and configure Caddy#

On the server, install Caddy using its official Debian/Ubuntu package repository:

sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo chmod o+r /usr/share/keyrings/caddy-stable-archive-keyring.gpg
sudo chmod o+r /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install -y caddy

Official Caddy installation instructions.

If Caddy already serves another site, preserve its configuration and combine these entries with it. For a new Caddy installation, open sudo nano /etc/caddy/Caddyfile and replace the example configuration with:

{
    admin off
    on_demand_tls {
        ask http://127.0.0.1:4000/__isomux/tls-ask
    }
}

office.example.com {
    respond /__isomux/tls-ask 404
    reverse_proxy 127.0.0.1:4000
}

*.office.example.com {
    tls {
        on_demand
    }
    reverse_proxy 127.0.0.1:4000
}

Save the file. In nano, press Ctrl+O, Enter, and then Ctrl+X. Validate it and restart Caddy:

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl restart caddy

Caddy obtains certificates automatically. Isomux admits certificates only for registered app names. The Caddy admin API is disabled; apply later configuration changes with a restart.

Use https://office.example.com as the HTTPS office address.

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.

Check the address from a phone on cellular data. If it fails, check DNS, router forwarding, both firewalls, and sudo journalctl -u caddy -n 50 --no-pager.

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.

Apps and maintenance#

Registered apps get separate HTTPS addresses, such as notes.office.example.com. Caddy obtains each app certificate when it is first opened. The wildcard DNS record must continue to point at this computer.

You manage the firewall, Caddy updates, DNS, and any request-log retention. This manual setup does not install the VPS updater or its hardening checks.

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.