Skip to content
Documentation
Reference
Configuration

Configuration

All configuration is done through environment variables in .env and per-agent config.yml files. The djinn setup wizard generates most of these automatically.

Environment Variables

Required

VariableDescriptionExample
OPENROUTER_API_KEYOpenRouter API key (also used for memory embeddings)sk-or-v1-...

That’s the only required variable when using OpenRouter. Everything else has defaults.

When AUTH_ENABLED=true, the following are also required:

VariableDescriptionGenerated By
AUTH_SECRET_KEYJWT signing key (HS256)djinn setup or python3 -c "import secrets; print(secrets.token_urlsafe(64))"
ENGINE_INTERNAL_TOKENService-to-service auth tokendjinn setup or python3 -c "import secrets; print(secrets.token_urlsafe(32))"

LLM Providers

VariableProvider
OPENROUTER_API_KEYOpenRouter (access to all models)
ANTHROPIC_API_KEYAnthropic (Claude)
OPENAI_API_KEYOpenAI (GPT)
GEMINI_API_KEYGoogle (Gemini)
XAI_API_KEYxAI (Grok)
GROQ_API_KEYGroq
MISTRAL_API_KEYMistral
CEREBRAS_API_KEYCerebras
AZURE_OPENAI_API_KEYAzure OpenAI
HF_TOKENHugging Face

Services

VariableDefaultDescription
API_PORT8000API server port
DASHBOARD_PORT3000Dashboard port
REDIS_PORT6379Redis port
POSTGRES_PORT5432PostgreSQL port
MCPO_PORT8001MCP proxy port

Network

VariableDefaultDescription
BIND_HOST0.0.0.0Network bind address. Set to 127.0.0.1 when using Traefik (SSL mode), 0.0.0.0 for direct access.
VITE_API_URLhttp://localhost:8000API URL used by the dashboard. Injected at runtime — no rebuild needed for custom domains.
DOMAINlocalhostDomain name used by Traefik for SSL certificate issuance.

Paths

VariableDefaultDescription
PIPELINES_DIR./pipelinesPipeline YAML directory
AGENTS_DIR./agentsAgent persona directory
DATA_DIR./dataGeneral data directory

Authentication

VariableDefaultDescription
AUTH_ENABLEDfalseMaster toggle for authentication. Set to true for any non-local deployment.
AUTH_SECRET_KEY—Secret key for signing JWT access and refresh tokens (HS256). Required when AUTH_ENABLED=true.
AUTH_TOTP_ISSUERDjinnBotIssuer name displayed in authenticator apps when setting up 2FA.
AUTH_ACCESS_TOKEN_TTL900Access token lifetime in seconds (default: 15 minutes).
AUTH_REFRESH_TOKEN_TTL604800Refresh token lifetime in seconds (default: 7 days).

Security

VariableDescription
SECRET_ENCRYPTION_KEYAES-256-GCM key for encrypting secrets at rest. Without this, secrets use an ephemeral key that resets on restart.
ENGINE_INTERNAL_TOKENShared secret for service-to-service auth. Protects the plaintext secrets endpoint. Also accepted as a first-class API key when auth is enabled. Required when AUTH_ENABLED=true.
MCPO_API_KEYAPI key protecting the mcpo tool proxy.

SSL / Traefik

These are set automatically by djinn setup when SSL is configured:

VariableDescription
TRAEFIK_ENABLEDSet to true when using Traefik reverse proxy.
DOMAINDomain name for SSL certificate (e.g. djinn.example.com).

The Traefik proxy also uses proxy/.env:

VariableDescription
ACME_EMAILEmail for Let’s Encrypt certificate notifications.
DOMAINDomain name (same as main .env).

Slack

VariableDescription
SLACK_CHANNEL_IDDefault channel for pipeline threads
SLACK_{AGENT}_BOT_TOKENPer-agent Slack bot token
SLACK_{AGENT}_APP_TOKENPer-agent Slack app token

User Slack ID — Your Slack member ID for DM notifications from agents is configured in the dashboard under Settings > Slack, not as an environment variable.

Discord

VariableDescription
DISCORD_CHANNEL_IDDefault channel for pipeline threads
DISCORD_{AGENT}_BOT_TOKENPer-agent Discord bot token
DISCORD_{AGENT}_APP_IDPer-agent Discord application ID (optional)

Per-agent credentials go in agents/<id>/discord.yml. See Discord Setup.

Telegram

Telegram bot tokens are managed via the dashboard (Settings > Integrations > Telegram) or per-agent YAML files.

VariableDescription
TELEGRAM_{AGENT}_BOT_TOKENPer-agent Telegram bot token from BotFather

Per-agent credentials go in agents/<id>/telegram.yml. See Telegram Setup.

Signal

VariableDefaultDescription
SIGNAL_DATA_DIR/jfs/signal/datasignal-cli data directory on JuiceFS
SIGNAL_CLI_PATHsignal-cliPath to signal-cli binary
SIGNAL_HTTP_PORT8820HTTP API port for signal-cli daemon

Signal is configured and linked via the dashboard (Settings > Integrations > Signal). See Signal Setup.

WhatsApp

VariableDefaultDescription
WHATSAPP_AUTH_DIR/data/whatsapp/authBaileys auth state directory on JuiceFS

WhatsApp is configured and linked via the dashboard (Settings > Integrations > WhatsApp). See WhatsApp Setup.

GitHub

VariableDescription
GITHUB_TOKENPersonal access token for git operations
GITHUB_APP_IDGitHub App ID
GITHUB_APP_CLIENT_IDGitHub App client ID
GITHUB_APP_WEBHOOK_SECRETWebhook signature verification
GITHUB_APP_PRIVATE_KEY_PATHPath to App private key PEM
GITHUB_APP_NAMEGitHub App name

Engine

VariableDefaultDescription
MOCK_RUNNERfalseUse mock agent runner for testing
USE_CONTAINER_RUNNERtrueUse Docker containers for agents
AGENT_RUNTIME_IMAGEghcr.io/basedatum/djinnbot/agent-runtime:latestDocker image used by the engine to spawn agent containers. Override to use a locally-built or custom image.
LOG_LEVELINFO (API), DEBUG (engine)Logging level (DEBUG, INFO, WARNING, ERROR)
DJINNBOT_VERSIONlatestCurrent version (for update checking)

JuiceFS + RustFS Storage

VariableDefaultDescription
RUSTFS_ACCESS_KEYdjinnbot-rustfs-adminS3 access key for RustFS object storage.
RUSTFS_SECRET_KEYchange-me-to-a-strong-secret-keyS3 secret key for RustFS. Change in production.
JUICEFS_VOLUME_NAMEdjinnbotJuiceFS volume name (stored in Redis DB 2).
JUICEFS_CACHE_SIZE20480JuiceFS local read cache in MB (default 20 GB). Adjust based on available disk.
JFS_META_URLredis://redis:6379/2JuiceFS metadata engine URL (set in docker-compose, not .env).
JFS_AGENT_CACHE_SIZE2048Cache size in MB for agent container JuiceFS mounts.

Memory Search (QMDR / ClawVault)

These control the semantic search engine used for agent memory retrieval. Set automatically by the engine and API containers.

VariableDefaultDescription
QMD_OPENAI_API_KEY${OPENROUTER_API_KEY}API key for embedding and reranking models.
QMD_OPENAI_BASE_URLhttps://openrouter.ai/api/v1Base URL for the embedding/reranking provider.
QMD_EMBED_PROVIDERopenaiEmbedding provider type.
QMD_OPENAI_EMBED_MODELopenai/text-embedding-3-smallEmbedding model for memory vector search.
QMD_RERANK_PROVIDERopenaiReranking provider type.
QMD_RERANK_MODEllmReranking mode (llm for LLM-based reranking).
QMD_OPENAI_MODELopenai/gpt-4o-miniModel used for LLM-based reranking.
QMD_QUERY_EXPANSION_PROVIDERopenaiProvider for query expansion.

Voice — STT & TTS

VariableDefaultDescription
WHISPER_MODEL_SIZEbasefaster-whisper model size (tiny, base, small, medium, large-v3). Larger = more accurate, slower.
WHISPER_MODEL_DIR/jfs/cache/whisper-modelsDirectory for cached whisper models (persisted on JuiceFS).

Programmatic Tool Calling (PTC)

VariableDefaultDescription
PTC_ENABLEDfalseEnable Programmatic Tool Calling. Reduces context usage by 30-40%+ by replacing JSON tool schemas with a compact Python SDK. See Programmatic Tool Calling.
PTC_TIMEOUT120Default timeout in seconds for exec_code Python execution.

Camoufox Browser

VariableDefaultDescription
CAMOFOX_URLhttp://127.0.0.1:9377Camoufox REST API URL inside agent containers.
CAMOFOX_API_KEY—Optional API key for the Camoufox instance.
CAMOFOX_COOKIES_DIR/home/agent/cookiesDirectory where granted cookie files are mounted.

Agent Configuration (config.yml)

Per-agent settings in agents/<id>/config.yml:

# LLM Models
model: anthropic/claude-sonnet-4
thinking_model: anthropic/claude-sonnet-4
thinking_level: 'off'          # off, low, medium, high
thinking_model_thinking_level: 'off'

# Context-specific model overrides
planning_model: openrouter/x-ai/grok-4.1-fast
executor_model: openrouter/x-ai/grok-4.1-fast

# Slack / Discord
thread_mode: passive            # passive or active

# Pulse (autonomous mode)
pulse_enabled: false
pulse_interval_minutes: 30
pulse_offset_minutes: 3
pulse_max_consecutive_skips: 5
pulse_container_timeout_ms: 120000
pulse_columns:
  - Backlog
  - Ready
pulse_transitions_to:
  - planning
  - ready
  - in_progress
pulse_blackouts:
  - label: Nighttime
    start_time: '23:00'
    end_time: '07:00'
    type: recurring
pulse_one_offs: []

# Agent coordination
coordination:
  max_concurrent_pulse_sessions: 2
  wake_guardrails:
    cooldown_seconds: 300
    max_daily_session_minutes: 120
    max_wakes_per_day: 12
    max_wakes_per_pair_per_day: 5

# Tool control
skills_disabled: []            # List of skill names to disable

All agent config can also be edited through the dashboard Settings and Agent pages.

Global Settings (Dashboard)

The Settings page in the dashboard provides UI access to:

  • Default working model — model for pipeline steps and chat
  • Default thinking model — model for extended reasoning
  • Pulse interval — global pulse frequency
  • Provider API keys — add/update provider credentials
  • Custom providers — configure OpenAI-compatible endpoints
  • Memory scoring — configure memory relevance weights
  • User provider keys — personal API keys per user (override system keys)
  • Authentication — manage user accounts, API keys, 2FA, and OIDC providers
  • API keys — generate and manage API keys for CLI and programmatic access
  • Two-factor authentication — enable/disable TOTP 2FA with recovery codes
CLI ReferencePipeline YAML Reference