Install and create your first agent

An agent runs on a dedicated Apple-silicon Mac (macOS 15+) under its own admin macOS account. You can scaffold and configure on any Mac for development, but production expects one machine per agent, always on.

Prerequisites

On a production mini, also keep the machine awake:

sudo pmset -a sleep 0 displaysleep 0 autorestart 1

Create the agent repo

npx @cohortapp/agent-sdk create jacob-ai
cd jacob-ai
maestro setup

@cohortapp/agent-sdk is published on the public npm registry, so npx fetches the current release; there is nothing to install first. To keep the CLI on your PATH between projects, install it globally:

npm install -g @cohortapp/agent-sdk
cohort create jacob-ai

create scaffolds a complete agent repository:

1. Copies the framework — scripts/, lib/, agents/, workflows/, policies/, plugins/, schedules/, teams/, docs/, mcp/, desktop-control/.
2. Copies the agent templates — CLAUDE.md, the config/agent.json stub, config/*.yaml skeletons, and .claude/ (settings, hooks, slash commands). The scaffolded .mcp.json wires the cohort-mcp org tool surface into interactive Claude sessions.
3. Creates the operational directory tree (config, knowledge, memory, state, logs, outputs) and generates queue, dashboard and schema templates.
4. Generates package.json with the operational scripts (daemon, healthcheck, emergency-stop, upgrade, doctor, …), copies .env.example and .gitignore, initializes git, and runs npm install.

The CLI binaries

Installing the package links six bins. cohort, maestro and agent-sdk are the same file (the last is what makes npx @cohortapp/agent-sdk … work); the neolith pair are legacy aliases from the pre-rename fleet:

Run the setup wizard

maestro setup is a deterministic, resumable, self-verifying wizard — Node code drives the orchestration, and the LLM is invoked only as a bounded enrichment step for company-specific prose. It runs as ordered sections, checkpoints to state/setup/progress.json, and on re-run resumes at the first incomplete section. config/agent.json is the source of truth; the checkpoint is just a hint.

1. Identity and company

   Name, title, the function-by-altitude archetype, and the principal the agent reports to; then the company interview (or a docs/company-context/ folder, or local repos to read) — written to config/agent.json and config/company.json.

2. Model and communications

   Choose API-key auth and enter your organisation's Anthropic API key; then wire each messaging channel you want — workspace messaging, email, Slack, SMS, WhatsApp, Telegram, voice — with credentials verified inbound.

3. Operating model and enrichment

   Deterministic generators produce the operating charter, a seeded backlog, 40–60 role-specific sub-agents, skills, workflows, cadences and launchd plists from the archetype. Enrichment then fills the company-specific prose slots with bounded, validated LLM calls.

4. Org, learning, recovery, verify

   Enroll against your Cohort workspace (see Connect an agent to your workspace), enable the self-learning loop and the recovery watchdog, and finish with a live capability probe that prints an N/M table with a remedy line per failure.

Useful flags: maestro setup <section> runs one section; --status prints each section's detected state; --headless --answers file.json drives it non-interactively; --dry-run previews. The wizard exits non-zero only on hard failures (no identity, unresolvable archetype, Claude API unreachable) — optional channels are reported but never fatal.

Verify

maestro doctor

Doctor verifies the installation end to end — framework files, cadence-bus wiring, launchd plists, config, state, .env, dependencies, and (once enrolled) live Cohort connectivity. It exits non-zero with actionable remediation when something is wrong. See Troubleshooting for the full check list.