Setup Wizard & Configuration
Relevant source files
The following files were used as context for generating this wiki page:
The Setup Wizard & Configuration system in Cogmo is a comprehensive infrastructure management suite designed to handle the initialization and reconfiguration of the agent runtime. It strictly focuses on infrastructure configuration—such as LLM providers, transport channels, and API credentials—rather than user-specific facts, which are handled via in-conversation onboarding.
The system is built to be re-runnable and idempotent, allowing operators to rotate keys, add new models, or reconfigure channels without losing existing data. It provides two primary interfaces: an interactive terminal-based UI (TUI) powered by @clack/prompts and a non-interactive mode for automated deployments.
Sources: design/setup.md:1-12, README.md:46-52
1. System Architecture & Core Logic
Cogmo's configuration logic is decoupled into a setup layer and a persistence layer. The setup tools interact with multiple database-backed stores to ensure that credentials are never stored in plaintext on disk or in environment variables post-initialization.
Persistence Layers
The configuration is distributed across three primary database stores:
- Secrets Store: Encrypted API keys (AES-256-GCM) for LLM providers, Tavily, and other tools.
- LLM Provider Store: Configuration for provider types, base URLs, and model routing.
- Transport Store: Channel configurations (e.g., Telegram) and associated user identities.
Sources: design/setup.md:172-181, src/setup/wizard.ts:881-890
Interaction Flow
The following diagram illustrates the linear sequence of the setup wizard:
2. Interactive Wizard (cogmo setup)
The interactive wizard is the primary entry point for manual configuration. It follows a Keep / Modify / Skip pattern for every step, ensuring it can safely audit existing configurations.
Key Features
- Live Validation: Credentials are validated against live provider endpoints (e.g., Anthropic, OpenAI, Telegram) before being committed to the database.
- Secrets Masking: Previously entered secrets are displayed in a masked format (e.g.,
sk-ant-...XYZA) during re-runs. - Error Handling: Throws
WizardCancelledon user abort (Ctrl+C), ensuring clean exits without corrupting state.
Sources: src/setup/wizard.ts:60-65, design/setup.md:25-31
Configuration Steps Table
| Step | Purpose | Required? | Validation Logic |
|---|---|---|---|
| Seed Defaults | Creates default user and profile rows. | Yes | Checks for existing rows in AgentStore. |
| LLM Provider | Configures Anthropic, OpenAI, or Custom endpoints. | Yes | Pings /v1/models or equivalent. |
| Telegram | Sets up bot token and user allowlist. | No | Calls getMe() to confirm bot identity. |
| Optional Tools | Configures Tavily (search) and fal.ai (images). | No | Live ping for Tavily; fal.ai errors on use. |
| Voice | Configures TTS (OpenAI/ElevenLabs) and STT. | No | 1-word TTS probe ("hi") to verify keys. |
| GitHub Identity | Stores PAT and generates SSH signing keys. | No | Validates PAT via GET /user. |
| Daytona | Configures managed sandbox API keys. | No | daytona.list() probe for org/key access. |
Sources: src/setup/wizard.ts:114-610, design/setup.md:33-55
3. Non-Interactive Mode
For CI/CD pipelines and automated container deployments, Cogmo supports a non-interactive setup mode. This mode reads configuration from environment variables with the COGMO_ prefix.
Security and Seeding
In non-interactive mode, secrets are seeded into the database once and are not read from environment variables on subsequent boots. This prevents long-term exposure of credentials in the environment.
Environment Variable Mapping
| Variable | Mapping / Destination | convention |
|---|---|---|
COGMO_MASTER_KEY | Derived for AES-256-GCM encryption. | Required |
COGMO_LLM_API_KEY | Encrypted secret for primary LLM. | Required |
COGMO_LLM_PROVIDER_TYPE | anthropic, openai, openrouter, or custom. | Required |
COGMO_TELEGRAM_BOT_TOKEN | Encrypted secret for Telegram adapter. | Optional |
COGMO_GITHUB_PAT | Fine-grained PAT for coding delegation. | Optional |
Sources: src/setup/non-interactive.ts:1-50, design/setup.md:104-142, DEPLOYMENT.md:88-105
4. Secret Management & Encryption
Cogmo utilizes a hardware-agnostic encryption scheme to protect credentials at rest.
Master Key Architecture
The system requires a COGMO_MASTER_KEY (32-byte base64 string). This key is used with HKDF (HMAC-based Extract-and-Expand Key Derivation Function) to generate purpose-specific keys for the DrizzleSecretsStore.
Implementation Detail: Secret Storage
// src/setup/wizard.ts:402-411
await deps.runInTx(async (tx) => {
const { id: secretId } = await deps.secretsStore.putSecret(tx, {
name: secretName,
plaintext: apiKey,
description: `${providerType} image provider key (${name})`,
});
// Resulting ID is used as a foreign key in agent/transport stores
});
5. Development Infrastructure
For local development, the system provides a specialized infrastructure script (scripts/dev-infra.ts) that automates the setup of external dependencies using testcontainers.
Component Integration
- Postgres: Used by Cogmo and Hindsight (pgvector).
- Redis: Handles Inngest queues and state.
- Inngest: Local dev server for event-driven orchestration.
- Hindsight: Memory server for vector-based recall.
Sources: scripts/dev-infra.ts:31-55, DEPLOYMENT.md:8-25
Sources: scripts/dev-infra.ts:60-120
6. Conclusion
The Setup Wizard & Configuration module provides a robust foundation for Cogmo's self-hosted nature. By combining interactive guidance with secure, encrypted persistence and live validation, it minimizes deployment friction while ensuring architectural integrity. The system's re-runnability ensures that Cogmo can evolve alongside the user's infrastructure, supporting transitions between different LLM providers and communication channels seamlessly.
Sources: design/setup.md:195-200, README.md:105-112