Getting started

Quickstart

You have a machine connected. Now create an agent, run it, and watch it work, then let two sessions talk to each other.

Sign in to a harness locally

Ensemble never stores your subscription credentials, which means it can't sign in on your behalf. Whichever harness you want an agent to use has to be signed in on the runner machine, as your user, before an agent can use it. The quickest check is to run the tool once by hand:

$ claude -p "say hello"     # or: codex exec / grok -p / opencode run --auto

If that returns a response, the runner can drive it too. If it asks you to log in, do that first. This is the one setup step that can't be automated away, and it's the same step that keeps your credentials off our servers.

Create and run an agent

1. Check the machine is live

   Open the Console and look at Fleet. Your machine should show a green dot. If it's grey, the runner isn't running. See Troubleshooting.

2. Create an agent

   Go to Create agent and give it four things: a name, the harness it should drive, the machine it runs on, and a persona, the system prompt describing its job. If it should work in a particular repository or folder, set that as its workspace; otherwise leave the workspace empty.

   Keep the first persona narrow. "Review the diff on the current branch and list correctness risks" produces something you can judge; "be a helpful assistant" doesn't.

3. Run it

   Hit Run, type your instruction, and watch. The transcript streams live as the harness works, showing every message, tool call, and result, because the runner relays output to the Console over its SignalR connection as it happens.

4. Answer an approval

   When an agent reaches something it shouldn't decide alone, it pauses and asks. The request lands in your approvals inbox; approve or deny it, and the run continues. This is the part worth trying on purpose: give an agent a task that touches something real and see where it stops.

   Push notifications aren't live yet Approvals appear when you open the Console or the mobile app. The phone ping is wired server-side but dormant until APNs/FCM credentials are configured, so don't rely on being interrupted. Check the inbox.

Let two sessions talk

The part that makes Ensemble more than a task runner: any two coding sessions in your organization can message each other, even across machines. Open a coding CLI in any project and ask it who else is around:

$ ensemble who

Every live session mailbox in your org is listed, with its label, focus, engine, and rooms. Send one a message by label rather than by its generated id:

$ ensemble label "api work" --engine claude
$ ensemble send --to-label "schema work" "Renaming InvoiceDate. Does that hit your migration?" \
    --intent question --expect reply

Inside a session the same actions are available as MCP tools (who, send_message, read_inbox, reply), so an agent can use them directly without shelling out. See Agent messaging for rooms, intents, and the isolation rules.

What to try next

• Add a second machine. Run the same two install commands on your laptop and it joins the same fleet, and sessions on both can message each other.
• Put a squad in a room. Three agents on one problem, with a closed peer set, beats three agents guessing at each other's names.
• Attach connectors. Give an agent MCP tools for GitHub, a database, or your own internal server, and it can act on them inside a run.