@webority/ensemble
v0.6.1
Published
Connect this machine to Ensemble — runs the local agent runner and wires the ensemble session messaging so your coding sessions talk (per-org, isolated).
Maintainers
Readme
@webority/ensemble
Connect a machine to your Ensemble Console. It installs the local agent
runner, wires lifecycle hooks, and registers the Ensemble MCP server in supported coding clients.
MCP exposes the same messaging actions as the CLI; the CLI verbs are canonical so this README does
not maintain a second tool-name inventory — see Ensemble.Runtime/README.md → CLI ↔ MCP parity
for the full mapping (an MCP tool name is always the CLI verb with hyphens replaced by underscores,
e.g. task-give → task_give).
Install
The published package supports Node.js 18+. Repository development uses Node 24 (see docs/RUNNING.md).
npm i -g @webority/ensemble
ensemble loginensemble 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 loginirm https://ensemble.host/install.ps1 | iex # then: ensemble loginHeadless 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 |
- Hooks — mail at turn boundaries
- MCP —
ensemble mcp --engine <e>as server nameensemble - Grok rules — managed always-on policy at
~/.grok/rules/ensemble-mail.md(no LLM inbox poll loops; shell monitor only; house overrides inensemble-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/MCPensemble update— install the latest release of the runtime + runner now and restart the runner;--checkonly reportsensemble install— repair: re-place the runner/runtime from the newest available source (never an older one); re-wires hooks/MCP if already enrolledensemble status— connection, engines detected, Grok MCP path check, runtime freshnessensemble hooks— re-wire hooks + MCP into every detected coding CLI (safe on existing configs)
ensemble help and Ensemble.Runtime/README.md are the canonical messaging command reference.
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 doctorshows it, and~/.ensemble/update.loghas the reason.ensemble updateretries by hand. - Opt out with
ENSEMBLE_NO_AUTO_UPDATE=1or by creating~/.ensemble/no-auto-update; releases are then installed only byensemble update/ensemble install. - Releases are signed: the publish job signs
manifest.jsonwith 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 withnpm install -gand re-runsensemble 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.
