Configuration
All configuration is done through environment variables in the .env file at the root of your install directory. The cognova init wizard generates this file automatically.
This page is the single source of truth for all Cognova environment variables. Other docs link here rather than duplicating this information.
Required Variables
These must be set for Cognova to start.
| Variable | Description | Example |
|---|---|---|
VAULT_PATH | Absolute path to your markdown vault directory | ~/vault |
BETTER_AUTH_SECRET | Secret key for session signing. Generate with openssl rand -base64 32 | a1b2c3... |
BETTER_AUTH_URL | Base URL of your app (used for auth callbacks) | http://localhost:3000 |
Database
| Variable | Description | Default |
|---|---|---|
DATABASE_URL | PostgreSQL connection string | postgres://postgres:postgres@localhost:5432/cognova |
For local development with Docker:
DATABASE_URL=postgres://postgres:postgres@localhost:5432/cognova
For hosted providers (Neon, Supabase):
DATABASE_URL=postgres://user:password@ep-xxx.us-east-2.aws.neon.tech/cognova?sslmode=require
Admin User
On first startup with an empty database, Cognova seeds a default admin user.
| Variable | Description | Default |
|---|---|---|
ADMIN_EMAIL | Admin login email | admin@example.com |
ADMIN_PASSWORD | Admin login password | changeme123 |
ADMIN_NAME | Admin display name | Admin |
Change the default credentials immediately if you skip these during setup. The defaults are publicly documented.
Network
| Variable | Description | Default |
|---|---|---|
ACCESS_MODE | Access mode: localhost, specific, or any | localhost |
HOST | Bind address. Set to 0.0.0.0 for non-localhost access | (unset) |
When ACCESS_MODE is specific or any, the wizard sets HOST=0.0.0.0 so the app listens on all interfaces.
Agent Personality
| Variable | Description | Default |
|---|---|---|
AGENT_NAME | Name shown in the web UI and used in Claude's identity | Cognova |
AGENT_TONE | Agent communication tone (concise, casual, formal, or a custom string) | casual |
These are set during cognova init and exposed as Nuxt public runtime config.
API Token
| Variable | Description | Default |
|---|---|---|
COGNOVA_API_TOKEN | Fixed API token for CLI tools and skills | (auto-generated) |
On each server startup, Cognova generates a token and writes it to .api-token in the install directory. Skills and hooks read this file to authenticate API calls.
Set this variable only if you need a stable, predictable token (e.g., for external integrations).
Docker-Only Variables
These apply when running Cognova in a Docker container.
| Variable | Description | Default in Compose |
|---|---|---|
COGNOVA_API_URL | Internal URL the agent uses to reach the API | http://localhost:3000 |
The Docker Compose file also maps volumes for the vault and Claude Code config. See Docker deployment for the full Compose reference.
Example .env File
# Database
DATABASE_URL=postgres://postgres:postgres@localhost:5432/cognova
# Vault
VAULT_PATH=~/vault
# Network
ACCESS_MODE=localhost
# Auth
BETTER_AUTH_SECRET=your-generated-secret-here
BETTER_AUTH_URL=http://localhost:3000
# Admin (first startup only)
ADMIN_EMAIL=admin@example.com
ADMIN_PASSWORD=changeme123
ADMIN_NAME=Admin
# Agent personality
AGENT_NAME=Cognova
AGENT_TONE=casual
Editing Configuration
To change variables after installation:
- Edit
<install-dir>/.env - Restart the app:
cognova restart
The .env file is never overwritten by cognova update. Your configuration is preserved across updates.