Sidemesh

Sidemesh is a trusted-network control plane for coding-agent sessions. Run the daemon on your development machine, connect from the Flutter app, and manage sessions, approvals, files, git, terminals, and browser tabs from mobile or desktop.

This repository contains:

• src/: the Node.js daemon, CLI, provider adapters, and host-side APIs
• apps/mobile/: the Flutter client
• web/: the landing and documentation site deployed separately

Sidemesh currently supports these provider adapters:

Run sidemesh setup --dev to expose the development-only providers in the setup wizard.

Requirements:

• Node.js >= 22.19.0
• A user-managed Node install such as Homebrew, nvm, or Volta if you want npm install -g to work without sudo
• Flutter, if you want to run the app locally
• A trusted network such as Tailscale or a private LAN

Install the default Codex path:

npm install -g sidemesh @openai/codex

sidemesh up

From the repo instead, for development:

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

What that command does:

1. Persists a default config to ~/.sidemesh/config.json if you do not have one yet.
2. Auto-detects ready providers on your machine and defaults to Codex when it is ready.
3. Checks the selected provider enough to catch obvious command problems before launch.
4. Launches the daemon in the background.
5. Prints the host URL, token, and QR code for the app.

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

For foreground development instead of a managed background daemon:

npm run setup
npm run daemon

Open the app, then either use the QR code printed by sidemesh up, run sidemesh pair, or add the host manually with:

• a label
• a base URL such as http://100.x.x.x:8787 or http://192.168.x.x:8787
• the shared bearer token

To run the Flutter app locally:

cd apps/mobile
flutter pub get
flutter run --flavor dev -t lib/main.dart

The browser build is available at app.sidemesh.com. Because browsers block insecure active content from an HTTPS page, remote hosts must use an HTTPS/WSS address. A loopback http://localhost address remains valid for a daemon running on the same machine. For another machine, publish the daemon only through a trusted-network HTTPS endpoint such as Tailscale Serve; do not expose it directly to the public internet.

The daemon trusts only the hosted Sidemesh web origins and loopback by default. For a self-hosted browser client, add its exact HTTP(S) origin to allowedBrowserOrigins in ~/.sidemesh/config.json, or set a comma-separated SIDEMESH_ALLOWED_BROWSER_ORIGINS value in the daemon environment. This allowlist changes browser CORS and WebSocket origin checks; bearer-token authentication is still required.

Build the browser app locally with:

npm run mobile:web:build

Platform-specific app notes live in apps/mobile/README.md.

On Linux, sidemesh service install uses systemd and typically needs sudo. On macOS, it installs a user LaunchAgent instead.

Server checks:

npm run typecheck
npm run test:server
npm run build

Flutter checks:

cd apps/mobile
flutter test
flutter analyze

Useful repo scripts:

npm run mobile:get
npm run test
npm run secret:scan

Sidemesh is for trusted networks only. Do not expose the daemon directly to the public internet.

Current auth is a shared bearer token:

• all /api/* HTTP routes and websocket endpoints require Authorization: Bearer <token>
• GET /healthz is intentionally unauthenticated for local health checks
• per-device token revocation is not implemented yet

Host-side features such as integrated terminals and browser tabs should stay disabled unless you intentionally need them.

• docs/getting-started.md
• docs/provider-adapter-contract.md
• docs/dependency-runtime-compatibility.md
• CONTRIBUTING.md
• docs/release-playbook.md