Getting started

Installation

Install the Ensemble CLI and connect this machine to your Console. Two commands, about two minutes, on macOS, Windows, or Linux.

Before you start

You need two things:

Node.js 18 or newer, with npm on your PATH. Check with node -v. If that command isn't found, install Node from nodejs.org first. The installer refuses to run without it.
An Ensemble account. Sign in to the Console with your work email; you'll get a one-time code. If your organization restricts sign-up, ask a teammate to invite you from the Console's Team screen before you install.

You do not need to clone this repository, install the .NET SDK, or build anything. You also don't need to install a coding CLI first, but if Claude Code, Codex, Grok, OpenCode, OMP, or Antigravity is already on the machine, the installer will wire it up automatically as it goes.

Install

Install the CLI
```
$ npm i -g @webority/ensemble
```
```
> npm i -g @webority/ensemble
```
Run this in PowerShell or Windows Terminal. If npm isn't recognised, close and reopen the terminal after installing Node, because the PATH change only applies to new shells.
```
$ npm i -g @webority/ensemble
```
If your Node install needs sudo for global packages, prefer fixing the npm prefix (npm config set prefix ~/.npm-global) over installing as root, because the runner should run as your own user, not root.
Sign in and connect the machine
```
$ ensemble login
```
This prints a verification URL and a short confirmation code, then opens your browser. Check that the code on screen matches the one in your terminal, approve the machine, and come back. The CLI does the rest on its own.

Nothing large downloads until you approve The runner binaries are roughly 90 MB and are fetched only after you approve in the browser, so a cancelled sign-in costs you nothing.
Confirm it worked
```
$ ensemble status
```
You should see this machine connected, the coding CLIs it detected, and any live session mailboxes in your organization. The same machine now appears on the Fleet screen in the Console.

Restart your coding sessions Any Claude Code, Codex, Grok, OpenCode, OMP, or Antigravity session that was already open when you installed won't see Ensemble. Those tools read their hook and MCP configuration once at startup, so quit and reopen them. New sessions pick everything up automatically.

What just happened

ensemble login did four things, so you don't have to do any of them by hand:

Exchanged your sign-in for a per-machine token. The token identifies this one machine and can be revoked on its own from the Console, without affecting your other machines.
Installed and started the runner daemon into ~/.ensemble, and registered it to start automatically on login: Task Scheduler on Windows, launchd on macOS, a systemd user unit on Linux.
Wired every coding CLI it found with both lifecycle hooks (so sessions exchange messages at turn boundaries) and an MCP server named ensemble (so sessions get first-class who / send / read / reply tools).
Left your subscription logins alone. Your Claude, ChatGPT, and Grok credentials stay on this machine. The runner dials outbound to the Console and opens no inbound port; the Console stores metadata and transcripts, never a subscription credential.

Files the installer touches

Coding CLI	Hooks	MCP
Claude Code	`~/.claude/settings.json`	`~/.claude.json`
Codex	`~/.codex/hooks.json`	`~/.codex/config.toml`
Grok	`~/.grok/hooks/agent-messaging.json`	`~/.grok/config.toml`
OpenCode	`~/.config/opencode/plugin/ensemble.js`	`~/.config/opencode/opencode.json`
OMP (oh-my-pi)	`~/.omp/agent/ensemble-hooks.json`	`~/.omp/agent/mcp.json`
Antigravity	`~/.gemini/config/hooks.json`	`~/.antigravity/mcp.json`

Existing configuration is preserved: the installer upserts only the ensemble entry and leaves any other MCP servers and your own settings untouched. Grok additionally gets a managed policy file at ~/.grok/rules/ensemble-mail.md; put your own overrides in ensemble-mail-local.md next to it, because the managed file is rewritten on every install.

Gemini CLI is not supported Google discontinued the product and its wiring was removed in August 2026. Antigravity is a separate engine that is supported. It just happens to share the ~/.gemini config directory.

Installing on a server or in CI

ensemble login needs a browser. On a headless box, use an enrollment token instead: in the Console, go to Connect Runner and create one, then run:

$ npm i -g @webority/ensemble
$ ensemble enroll --token <ENROLLMENT_TOKEN>

The token can also be supplied as the ENSEMBLE_ENROLL_TOKEN environment variable, which is usually cleaner in a CI pipeline than putting a secret on the command line where it can land in shell history or build logs. An enrollment token is single-use for onboarding and is exchanged for a per-machine token; revoke either one from the Console at any time.

Keeping it up to date

$ npm i -g @webority/ensemble@latest
$ ensemble install                 # refresh the runner binaries to match

Run both. Updating the npm package alone leaves the previously downloaded runner binaries in place, and a runner that lags the CLI is the usual cause of unexplained errors after an upgrade. ensemble install re-downloads the runtime for your platform and re-wires hooks and MCP if the machine is already connected.

If you add a new coding CLI later, you don't need to reinstall anything. Just run ensemble hooks to wire it up, then restart that tool.