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`	Required. An Anthropic API key your organisation owns. Doctor validates it live on every run — an invalid key cascades 401s through every spawn
`MAESTRO_PREFER_SUBSCRIPTION_AUTH`	Leave unset. It strips `ANTHROPIC_API_KEY` from sub-sessions, and subscription sign-in is not supported for agent seats. Remove it, and any `CLAUDE_CODE_OAUTH_TOKEN`, from older `.env` files

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.