Getting Started

What You Need

• Host machine (where you code): macOS, Linux, or Windows with WSL
  • Node.js 22.5+
  • A user-managed Node install such as Homebrew, nvm, or Volta if you want npm install -g to work without sudo
  • For Pi provider: Pi must be installed separately
• Client device: iOS, Android, macOS, or Linux
  • Flutter runtime for the mobile app
• Network: Tailscale, private LAN, or localhost

Install the Daemon

From npm (recommended)

For the default Codex path:

npm install -g sidemesh @openai/codex

From source (recommended for development)

git clone https://github.com/mukhtharcm/sidemesh.git
cd sidemesh
npm install
npm run build
npm link              # makes sidemesh available globally

Configure Providers

For the default Codex path, one command is enough:

sidemesh up

This will:

• Create ~/.sidemesh/config.json if it does not exist yet
• Start the daemon in the background
• Print the base URL, token, and pairing QR code

Use sidemesh setup when you want to customize providers, host features, or advanced settings before starting.

Provider	Extra setup
Codex (default)	Install codex CLI: npm install -g @openai/codex
Pi	Install Pi: npm install -g @mariozechner/pi-coding-agent, then pi /login
Copilot	Install GitHub Copilot CLI and authenticate
Fake	No extra setup; for testing only (--dev flag)

Start the Daemon

Background mode (manual)

sidemesh up          # create config if needed, start, and print pairing details

Use this if you want Sidemesh running in the background without setting up a service. The app can connect normally, but if you use Restart or Update in the app, you may need to start Sidemesh again yourself.

Foreground mode (for debugging)

sidemesh daemon      # runs in terminal, shows live logs

Closing the terminal stops the daemon. Use this mode when you want live logs and do not mind starting it again yourself.

As a system service (recommended for day-to-day use)

Linux (systemd):

sudo sidemesh service install
sudo sidemesh service restart --yes

macOS (LaunchAgent):

sidemesh service install
sidemesh service restart --yes

Use this if you want the app’s Restart and Update buttons to bring the host back on their own.

Connect the Mobile App

Option 1: QR code

1. Use the QR code printed by sidemesh up, or run sidemesh pair on the host
2. Open the Sidemesh app
3. Tap the host editor -> “Scan QR”
4. Point camera at the terminal QR code

Option 2: Manual entry

1. Use the base URL and token printed by sidemesh up, or run sidemesh pair again
2. In the app, tap “Add host manually”
3. Enter:
   • Label: any friendly name
   • Base URL: http://HOST:PORT
   • Token: the bearer token

Example URLs:

• Tailscale: http://100.94.10.20:8787
• LAN: http://192.168.1.50:8787
• Localhost: http://localhost:8787

In-App Restart and Update

From the host details screen, you can choose an update channel, restart the daemon, and run self-update.

• Stable gets tagged releases.
• Bleeding edge gets the newest commits on main for local repo installs.
• If you want the app’s Restart and Update buttons to work reliably, use sidemesh service install.
• If you run sidemesh daemon, sidemesh start, or sidemesh up, update and restart it yourself when needed.

Daily Workflow

1. Start daemon on host: sidemesh up for most manual runs, or let the OS service auto-start
2. Open app on phone/desktop
3. Select host from the host list
4. Create or resume a session
5. Chat with the agent

Useful Commands

Command	Purpose
sidemesh up	Create a default config if needed, start the daemon, and print pairing details
sidemesh setup	Customize providers, host features, and advanced settings
sidemesh doctor	Check provider health
sidemesh status	Show config, PID, health
sidemesh pair	Re-print connection QR
sidemesh stop	Stop background daemon
sidemesh restart --yes	Restart a daemon started with sidemesh start or sidemesh up
sidemesh service restart --yes	Restart the OS service on macOS/Linux