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.

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)