Run Isomux on this computer#

This is the Host locally guide. To check if this is the right hosting setup for you, check the decision diagram.

Use this guide for a local office on Linux or macOS. You need an internet connection and access to an AI provider. The office runs while its terminal is open and the computer is awake. Apps need Linux with systemd. On macOS the office runs without them.

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.

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.

Your office is ready at http://localhost:4000.

Stop, return, or update#

Press Ctrl+C in the server terminal to stop the office. To return, open a terminal in the Isomux directory and run bun run dev again. Your office data stays in ~/.isomux.

To update, stop the office and run these commands from the Isomux directory:

git pull --ff-only
bun install
bun run dev

The server terminal shows office logs. For an office that starts at boot and works from other devices, pick another setup.

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.