Configuration

Environment variables and advanced configuration options for Animus.

Most configuration in Animus happens through the Settings page in the web interface. Environment variables are available for deployment scenarios, Docker, and power users who prefer file-based configuration.

Environment Variables

Animus uses a .env file in the project root. Copy .env.example to get started:

cp .env.example .env

All variables are optional. The defaults work out of the box for local development.

Server

Variable Default Description
NODE_ENV development Runtime environment (development or production)
PORT 3000 Backend server port
HOST localhost Bind address (use 0.0.0.0 for Docker or remote access)
LOG_LEVEL info Logging verbosity (debug, info, warn, error)

Data

Variable Default Description
ANIMUS_DATA_DIR ./data Where databases, models, logs, and media are stored. In Docker this is set to /app/data.

API Keys

Variable Default Description
ANTHROPIC_API_KEY (none) Claude API key. Can also be set through the Settings UI.
OPENAI_API_KEY (none) OpenAI API key. Only needed if using the Codex agent provider.

No API keys are required in .env. The onboarding flow and Settings page let you configure provider credentials through the interface. Setting keys in .env is useful for Docker deployments or headless operation where you want credentials available at startup.

Authentication

Variable Default Description
SESSION_EXPIRY_DAYS 30 How long login sessions last before requiring re-authentication.

Auto-Generated Secrets

The following are generated automatically on first run and stored in data/secrets.json. Do not set them manually:

  • ANIMUS_ENCRYPTION_KEY: AES-256-GCM key for encrypting credentials at rest
  • JWT_SECRET: HMAC key for signing auth tokens

Persona Configuration

The persona defines who your Animus instance is. It is stored in persona.db and edited through the Persona page in the web interface.

Key persona fields:

Field Purpose
name The agent's name
identity Core identity statement
values Guiding principles and beliefs
communication Tone, style, and interaction preferences
boundaries What the agent will and won't do

Database Layout

Animus uses seven SQLite databases, each serving a different lifecycle:

data/databases/
├── system.db       # Users, settings, credentials
├── persona.db      # Identity and personality
├── heartbeat.db    # Tick logs, emotional state
├── memory.db       # Long-term memory entries
├── messages.db     # Conversation history
├── agent_logs.db   # AI provider call logs
└── contacts.db     # Contacts and contact channels

Each database can be independently backed up or reset. For example, resetting memory.db clears all memories without affecting goals or persona.