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 Git. On Ubuntu or Debian:

    sudo apt update
sudo apt install -y git curl unzip

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

  2. Install Bun:

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

    Open a new terminal so that the shell can find Bun. Check its version:

    bun --version

    Bun must be at least version 1.3.11.

  3. 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.

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

Create the first owner#

When Isomux starts with no owner, it prints a setup link in its terminal and log, such as http://localhost:4000/setup#key=.... On the computer running Isomux, open that link 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 open the setup link in your laptop's browser. Port 4000 on your laptop must be free.

The link carries the setup key, which is also in ~/.isomux/setup-key on the server. The office accepts its first owner only with this key. Set up remote access after you have opened the office as its owner.

Keep the office running#

These steps use Linux with systemd. Turn off sleep in the 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:$HOME/.local/bin:/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 the pinned Caddy Debian package from its GitHub release. The commands verify its SHA512 checksum before installation.

(
set -eu
sudo rm -f /etc/apt/sources.list.d/caddy-stable.list /usr/share/keyrings/caddy-stable-archive-keyring.gpg
sudo apt update
sudo apt install -y curl ca-certificates
version=2.11.7
arch=$(dpkg --print-architecture)
case "$arch" in amd64|arm64) ;; *) echo "Unsupported architecture: $arch" >&2; exit 1 ;; esac
asset="caddy_${version}_linux_${arch}.deb"
base="https://github.com/caddyserver/caddy/releases/download/v${version}"
stage=$(mktemp -d)
trap 'rm -rf "$stage"' EXIT
chmod 755 "$stage"
cd "$stage"
curl -fsSL "$base/$asset" -o "$asset"
curl -fsSL "$base/caddy_${version}_checksums.txt" -o checksums.txt
awk -v asset="$asset" '$2 == asset { if (length($1) != 128 || $1 ~ /[^0-9a-fA-F]/ || NF != 2) exit 1; print $1 "  " asset; found++ } END { if (found != 1) exit 1 }' checksums.txt > selected.sha512
sha512sum --check selected.sha512
chmod 644 "$asset"
sudo apt install -y "./$asset"
)

These commands remove the old Caddy repository files without removing Caddy. For later Caddy upgrades, repeat them with the version from the Caddy releases page.

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 Integrations → Model providers.

  • For Claude or Codex, select the provider's sign-in control and follow the steps. Both ship 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. Free models need no paid account.
  • For a provider API key, add its environment variable on the Variables tab: 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, first create them: in Settings, select New member at the end of the Members list, fill in the form and select Create member. Then open Settings → Office → Invites, select them and create a sign-in link. 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.