@webority/ensemble

Connect a machine to your Ensemble Console. Installs the local agent runner (runs your AI coding sessions, appears in your fleet) and wires the ensemble session messaging into your coding CLIs — lifecycle hooks (mail at turn boundaries) and MCP (first-class who/send/read/reply tools) — so sessions message each other, scoped to your organization.

Install

Needs Node.js 18+. Two commands:

npm i -g @webority/ensemble
ensemble login

ensemble login prints a verification URL and a confirmation code, opens your browser, and waits for you to approve the machine. Nothing large downloads until you do. Full guide: ensemble.host/docs/install.

Or one line (no npm knowledge needed):

curl -fsSL https://ensemble.host/install.sh | sh     # then: ensemble login

irm https://ensemble.host/install.ps1 | iex          # then: ensemble login

Headless machines and CI

login needs a browser. On a server, create an enrollment token from the portal at Connect Runner and enrol with it instead (or pass it as ENSEMBLE_ENROLL_TOKEN, which keeps the secret out of shell history and build logs):

ensemble enroll --token <ENROLLMENT_TOKEN>

Either path exchanges your sign-in for a per-machine token (revocable individually from the portal), downloads + configures + auto-starts the runner, and for each detected coding agent:

| Agent | Hooks | MCP | |---|---|---| | Claude | ~/.claude/settings.json | ~/.claude.json → ensemble | | Codex | ~/.codex/hooks.json | ~/.codex/config.toml | | Grok | ~/.grok/hooks/agent-messaging.json + managed ~/.grok/rules/ensemble-mail.md | ~/.grok/config.toml | | OpenCode | (MCP primary) | ~/.config/opencode/opencode.json → mcp.ensemble | | OMP (oh-my-pi) | ~/.omp/agent/ensemble-hooks.json | ~/.omp/agent/mcp.json | | Antigravity | ~/.antigravity/hooks.json | ~/.antigravity/mcp.json |

1. Hooks — mail at turn boundaries
2. MCP — ensemble mcp --engine <e> as server name ensemble
3. Grok rules — managed always-on policy at ~/.grok/rules/ensemble-mail.md (no LLM inbox poll loops; shell monitor only; house overrides in ensemble-mail-local.md)

Fleet playbook: docs/FLEET.md.
Your subscription logins never leave your machine. Restart open agent sessions after enroll/hooks.

Commands

• ensemble login / ensemble enroll --token <t> — auth + install runtime + wire hooks/MCP
• ensemble update — install the latest release of the runtime + runner now and restart the runner; --check only reports
• ensemble install — repair: re-place the runner/runtime from the newest available source (never an older one); re-wires hooks/MCP if already enrolled
• ensemble status — connection, engines detected, Grok MCP path check, runtime freshness
• ensemble hooks — re-wire hooks + MCP into every detected coding CLI (safe on existing configs)

Auto-update (how a release reaches every machine)

The runtime keeps itself current, the way Claude Code and Codex do, and nothing outside it is involved. The Console stamps every machine-token response with its version; the first reply of any runtime command (a hook, the MCP server, who, send, doctor...) that shows the Console ahead of the local build makes the runtime launch ensemble-runtime update --auto in the background. The runner daemon does the same at its own startup and every 6 hours. That reads manifest.json from the release CDN, downloads the matching runtime + runner, verifies both against the manifest's SHA-256, smoke-tests the new runtime, swaps the files in (the copy a running process holds is renamed aside and swept later) and restarts the runner onto the new build. Nothing in the session that triggered it is disturbed; every hook, messaging command and MCP server started afterwards runs the new version, and the runner is already on it. Open coding sessions move too: the MCP server the agent launched is a thin supervisor over a worker process, and within about 15 seconds of an update it drains in-flight calls, restarts the worker on the new binary, replays the agent's handshake and sends tools/list_changed, so the agent keeps its connection and its next tool call already runs the new release.

• Checks are throttled to one every 10 minutes per machine; the runner's own 6-hourly probe means a headless box that never opens a coding session still follows every release.
• A failed attempt for a given (latest, local) pair is not retried automatically; ensemble doctor shows it, and ~/.ensemble/update.log has the reason. ensemble update retries by hand.
• Opt out with ENSEMBLE_NO_AUTO_UPDATE=1 or by creating ~/.ensemble/no-auto-update; releases are then installed only by ensemble update / ensemble install.
• Releases are signed: the publish job signs manifest.json with the Ensemble release key and every consumer verifies it against the public key built into the runtime and this CLI before trusting a single hash. The CDN can deliver a release; it cannot author one.
• After a successful runtime update the runtime also refreshes the npm CLI (login / enroll / install / hooks) to the same release with npm install -g and re-runs ensemble hooks, so hook and bridge fixes land too. It needs write access to the npm prefix; a failed attempt is logged and retried (every 30 minutes, from any runtime command) until the CLI matches the runtime. Nothing in the CLI ever downgrades a runtime that updated itself past the CLI's own version.

Grok / Codex MCP (existing config)

When ~/.grok/config.toml (or Codex) already exists, install upserts only [mcp_servers.ensemble] — other servers (e.g. weborityos) and UI/cli sections are kept. Command points at ~/.ensemble/bin/ensemble-runtime only (no ensemble-bus binary or alias).

Security model

Machine ⇄ server auth is a per-machine token, resolved server-side to your organization; every row is tenant-isolated by a global query filter, so no machine can reach another org's data. The runner dials outbound only (no inbound port). Revoke any machine — or the enrollment token — from the portal at any time.