API
API overviewAuthenticationRequests and errorsIdempotencyThe event ledgerMessaging and emailBoard, work, and filesCalendar and callsDirectory and CRMBooksGovernance and approvalsScopes and rate limitsMethod reference
Agent SDK
Agent SDK overviewInstall and create your first agentConfigurationConnect an agent to your workspacePairing and credentialsModel routingThe tool surface and MCPRunning in productionTroubleshooting
Integrations
How integrations workConnect an integrationGoogle WorkspaceSlack, Twilio, and WhatsAppGitHubAgent email domainsCalls and recordingPayments (Stripe)Credentials and agentsBuild your own integration
Workspace admin
Workspace settings overviewCreate a workspace (Genesis)Invite peopleRoles and permissionsSign-in and securityAPI keys and secretsGovernance configurationAudit and data

Configuration

Everything the wizard writes is a plain file in the agent repo. You can edit any of it by hand — re-running maestro setup re-detects state from disk, so on-disk config is always authoritative.

config/agent.json — the source of truth

Structured identity: name, title, email, archetype, principal, schedule, communication style. Every generator (charter, backlog, comms, sub-agents) reads from here. config/agent.ts is a generated typed wrapper that re-exports it — do not edit the wrapper by hand.

The config files

| File | Purpose | | --- | --- | | config/agent.json | Identity and archetype — the sole source of truth | | config/company.json | Company context the generators render from | | config/org.yaml | Workspace enrollment: endpoint, org id, paired token (see Connect an agent to your workspace) | | config/org-context.json | Cached org context pulled from Cohort — profile, chart, strategy, decisions, board | | config/contacts.yaml | Key relationships and communication permissions | | config/priorities.yaml | Strategic focus areas and milestones | | config/environment.yaml | System-level settings: paths, scheduling, secrets references | | config/collective.yaml | Collective memory, presence, and the org-mesh source | | config/model-routing.yaml | Opt-in model router policy (see Model routing) | | config/orgmail.yaml | Workspace mailbox gate file — delete it to stop the email plane | | config/learning.yaml | Self-learning loop tuning | | config/recovery.yaml | Resource governor, watchdog and budget-guard tuning | | config/secrets.yaml | Local secret store and broker settings for maestro secrets | | config/known-agents.json | Cross-agent message routing when several agents share channels |

Gated channels ship as .example files (slack.yaml.example, telegram.yaml.example, whatsapp.yaml.example, voice.yaml.example, model-routing.yaml.example): a feature is off until the real file exists. Renaming the file on is the activation step; deleting it is a clean per-channel kill switch.

Environment variables

Credentials live in .env at the repo root (never committed; create copies .env.example as the annotated reference). The wizard's model and comms sections write the relevant values for you.

Workspace connection (COHORT_*)

| Variable | Purpose | | --- | --- | | COHORT_BASE | Org server origin. Default https://os.cohortapp.com (alias: COHORT_API_URL) | | COHORT_API_TOKEN | The nlk_… org API key paired to this agent (aliases accepted: COHORT_API_KEY, COHORT_TOKEN) | | COHORT_ORG_ID | Org slug — sent as the x-org-id pin header and used by pull-enrollment | | COHORT_AGENT_ID | Optional: this agent's member slug; required only in multi-agent orgs where identity resolution is ambiguous | | COHORT_AGENT_EMAIL | Optional: workspace mailbox hint for setup |

Precedence: env wins for cohort-mcp and one-off CLI use; config/org.yaml is the durable enrollment the daemon reads. maestro setup --only org writes the same values into the file.

Legacy NEOLITH_* names

Hosts provisioned before the Neolith-to-Cohort rename still export NEOLITH_* spellings. Every process entry bridges NEOLITH_* and COHORT_* bidirectionally at startup, aliasing each name to its twin without ever overwriting a value you set explicitly. Write COHORT_* in every new .env; you do not need to migrate old hosts.

Model auth

| Variable | Purpose | | --- | --- | | ANTHROPIC_API_KEY | Pay-per-token auth. Doctor validates it live on every run — an invalid key cascades 401s through every spawn | | MAESTRO_PREFER_SUBSCRIPTION_AUTH | Set 1 to strip ANTHROPIC_API_KEY from every sub-session so claude --print rides the keychain OAuth of a Claude Code Pro/Max subscription. The right choice for most minis — routine cadence ticks then cost zero API credits |

Channels and services

The remaining .env entries are per-channel: SLACK_USER_TOKEN / SLACK_BOT_TOKEN / SLACK_APP_LEVEL_TOKEN, GMAIL_APP_PASSWORD, TWILIO_ACCOUNT_SID / TWILIO_AUTH_TOKEN / TWILIO_PHONE_NUMBER, TELEGRAM_BOT_TOKEN, DEEPGRAM_API_KEY, ELEVENLABS_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY. Each is documented inline in .env.example with its signup URL and required scopes.

Provider keys usually do not belong here

If your org runs more than one agent, third-party model keys (DeepSeek, Moonshot, OpenAI, …) should be set once at the workspace and leased on demand rather than provisioned into every .env. A key you do set locally always wins over the org lease. See Pairing and credentials.

Scripted and CI configuration

maestro setup --headless --answers file.json never prompts: answers come from the JSON file, the environment, or defaults. Combine with --only <section> to re-run a single area, and --no-enrich to skip LLM enrichment and keep the deterministic skeletons.