NAISYS Hub

← Back to main README

The hub is the central server and source of truth for a NAISYS cluster. Runners and supervisors connect over WebSocket + REST; the hub owns persistence (mail, context logs, cost, variables) so runners are ephemeral and can be restarted or moved between machines without losing state.

Running

Most installations run the hub in-process with the supervisor UI and ERP — see the main README. To run the hub alone:

npm install @naisys/hub
npx naisys-hub

Hosts then connect with npx naisys --hub=https://<server>/hub. If the hub isn't already public, expose it with a reverse proxy or ngrok.

Note: Remote auto-update from the supervisor UI only works when the hub runs attached to a naisys runner (the integrated stack). Running naisys-hub solo skips the runner that performs the update.

Configuration

Standalone hub reads configuration from .env:

• NAISYS_FOLDER - persistent data folder for the hub database, logs, and access key
• SERVER_PORT - HTTP port; defaults to 3300

Features

Core

• WebSocket + REST server with hub-protocol shared types between hub and clients
• Heartbeat service for online runners/supervisors and agent status
• Run-session tracking with keep-alive and authoritative online/offline state
• Per-app host filter (naisys-host vs supervisor-host)

Persistence (doc 001)

The hub owns mail, context logs and attachments, cost history, and variables, so runners stay ephemeral and replaceable.

Multi-machine (doc 005)

• Hub is the single source of truth; runners are ephemeral
• Duplicate host-connection prevention — a new connection supersedes a dead one

Security (doc 010)

• Per-host access keys (SHA-256 hashed on hosts.access_key_hash) — Socket.IO handshake resolves a host by its key; no global shared secret
• Per-user Authorization: Bearer API keys for REST endpoints, also hashed
• Hardened spawning: no shell interpretation, timeouts on execFileSync
• Dynamic runtime API keys minted per agent and re-issued on hub restart
• Redaction service scrubs sensitive variables and runtime keys from logs and mail before they hit the DB
• Hub socket served at /hub for reverse-proxy friendliness (TLS terminated at the proxy)

Deployment

• Reverse-proxy-friendly path strategy (<app>/api/...) and unified port strategy (doc 009)
• npm bin entry points: naisys, naisys-hub, naisys-supervisor, naisys-erp
• Ngrok-friendly (skip-browser-warning header)

License

MIT