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. The Linux app supervisor requires systemd; this guide does not set up background app services on macOS.

Install Isomux#

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

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

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.

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 is reachable from other devices, choose another setup above.

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.