NexusCrew

Your tmux fleet. Everywhere.

NexusCrew turns live tmux sessions, AI CLI workers and connected machines into one local-first browser control plane. Your terminals stay real, your tools stay yours, and your infrastructure stays under your control.

Reading this as an AI agent? Start with skills/nexuscrew. It is the entry point: what the system is, what you can actually do through it, which companion skill covers which capability, where the trust boundaries are, and the operational rules that hold across all of them — which tool to reach for and in what order, and what not to do. Every other NexusCrew skill assumes it, and this README alone does not replace it.

One control plane. Every screen.

The desktop deck keeps the whole fleet visible. Open any cell from a phone and NexusCrew gives the same live tmux session a touch-first terminal without moving the session away from its host.

Inside a mobile terminal, the cell control in the key bar opens a bottom-left quick rail of freshly verified live cells. Choose a cell first, then use the separate Open cell action to switch after a final live check; a touch on the rail never changes session by itself. Drag the dedicated handle to arrange cells—the same saved order is used by the main roster and desktop sidebar, and an offline cell returns to its place when it reconnects. The rail refreshes routed Fleet state while open, keeps a degraded cell visible as a warning, and has an explicit all-cells view when you need the complete inventory instead of a quick switch.

_{Real tmux on mobile. Terminal keys, dictation and file handoff stay within reach.}

Install in 30 seconds

Install the package globally:

npm install -g @mmmbuto/nexuscrew@latest

Start it — the first run creates a loopback-only runtime, starts it in the background and opens the authenticated PWA:

nexuscrew

Prerequisites: Linux needs Node.js 18+, tmux (3.4+ recommended) and OpenSSH, installed with your distribution package manager. On macOS:

brew install node tmux

On Android / Termux:

pkg install nodejs-lts tmux openssh

NexusCrew ships scriptless PTY prebuilds for Linux x64/ARM64, macOS x64/ARM64 and Android ARM64. A normal global install does not need a compiler or native install-script approval.

Full installation guide →

What NexusCrew gives you

Live terminals	Attach to real tmux sessions through a real PTY, WebSocket and xterm.js.
Persistent workspaces	Arrange sessions into decks with saved layouts, ordering, pins and per-cell drafts.
Multi-node Fleet	See and control authorized cells across Linux, macOS and Android nodes.
AI-ready cells	Launch Claude Code, Codex, Codex-VL, Grok, VL, Pi, Agy, Kimi Code CLI or a trusted shell with explicit providers and policies.
Mobile-native control	Scroll tmux history, use terminal keys, dictate prompts and move files from a phone.
Operator alerts	Receive visual, push, browser speech and opt-in node-native Audio Share TTS.

The browser is a client, not the session host:

Browser PWA
    │  authenticated HTTP + WebSocket on loopback
    ▼
NexusCrew ── real PTY ── tmux sessions
    │
    ├── supervised OpenSSH ── remote NexusCrew nodes
    │
    └── stdio MCP bridge ── AI CLI workers

Local-first by design

NexusCrew has no hosted control service, required account or public listener. It binds to 127.0.0.1, authenticates the PWA with a local token and leaves session ownership to tmux.

• OpenSSH remains the network and identity authority.
• Provider credentials stay on the node that uses them.
• Pairing links contain no SSH private key, provider key or PWA token.
• File operations reject traversal and symlink escapes.
• Updates preserve tmux sessions and roll back when health checks fail.

Pair only devices you own

A paired admin node is trusted as you are. The admin access preset grants a node the same authority over this machine that you have: it can create sessions, attach to them and type into them as the user running NexusCrew, define engines and cells, and read what the fleet exposes. The user and nexushost access presets grant less authority.

Pair your own devices, and only those. Do not accept a pairing invite from someone else's installation. Choose the access preset deliberately: admin grants owner-equivalent authority; user and nexushost grant less.

Federated ASK creation and closure are delivered only to configured admin peers, hop by hop: each hub applies this rule to its own next peer.

Remote access is intentionally carried through SSH or a VPN you control:

ssh -L 41820:127.0.0.1:41820 user@your-host

Shared mobile peers can use a small, pre-authorized reverse-port pool for recovery from a real reverse-forward collision. NexusCrew never edits SSH policy: the hub operator keeps authorized_keys authoritative, while the product verifies a configured pool before it can rotate within it. See Connect nodes.

Security model →

Documentation

Guide	Covers
Documentation index	Start here for every guide
Installation	Linux, macOS, Termux, first run and upgrades
Fleet and terminals	Cells, engines, providers, decks and mobile input
The cell panel	Giving a cell its own web interface, and why it is loopback-only
Connect nodes	Pairing, SSH routes, sharing and routed aliases
Notifications	Toasts, Web Push and optional spoken alerts
Audio Share and native TTS	Node-native TTS, consent, groups and MCP controls
MCP bridge	Operator tools, cell delivery and client setup
VL micro-device nodes	Outbound pairing and bounded management for constrained native VL nodes
Configuration	Files, environment overrides and local settings
Operations	CLI, boot, backup, updates and diagnostics
Security	Trust boundaries, tokens and credential handling

The repository also includes MCP companion guidance and the machine-readable mcp-companions.json.

Portable skills ship with the package, and nexuscrew is the one to read first — the operational rules (which tool, in what order, what not to do) live there:

Skill	Covers
nexuscrew	Start here — the whole system and the rules across it
nexuscrew-agent	Talking to the human, runtime discovery, delivery to cells
live	Designating and permitting a node's Live host cell
aidesktop	A cell's web panel, and the AI Desktop container recipe
cellforge	Creating, changing and auditing a cell's definition
memory	Persistent agent state
vl-msa	Searchable document memory
crew	Bounded worker delegation
mail-assistant	Mailbox discovery, triage and reading

Platforms

Platform	Architectures	Background integration
Linux	x64, ARM64	systemd user service or detached runtime
macOS	x64, ARM64	LaunchAgent or detached runtime
Android / Termux	ARM64	detached runtime and optional Termux:Boot

Run nexuscrew doctor after installation or when moving configuration between devices.

Development

Run the test suite:

npm test

Build the frontend assets:

npm run build

Run the runtime in the foreground:

node bin/nexuscrew.js serve

Tests that exercise tmux use private sockets and never attach to or terminate the operator's tmux server.

See CHANGELOG.md for released changes.

License

Apache-2.0 © 2026 Davide A. Guglielmi (DioNanos)