Skip to main content
Asta uses environment variables to configure API keys, security settings, and runtime behavior. All configuration happens in backend/.env.

​
Setup

  1. Copy the example file: 
    cp .env.example backend/.env
  2. Edit backend/.env with your values
  3. Restart the backend for changes to take effect
backend/.env is in .gitignore and never committed. Only .env.example is tracked in git.

​
AI Providers

Configure one or more AI providers. Asta falls back through the provider chain (Claude → Ollama → OpenRouter) if a provider fails.
​
GROQ_API_KEY
string
Groq API key for fast inference. Get one at console.groq.com
​
GEMINI_API_KEY
string
Google Gemini API key (also accepts GOOGLE_AI_KEY). Get one at aistudio.google.com
​
ANTHROPIC_API_KEY
string
Anthropic Claude API key. Required for Claude provider. Get one at console.anthropic.com
​
OPENAI_API_KEY
string
OpenAI API key. Get one at platform.openai.com
​
OPENROUTER_API_KEY
string
OpenRouter API key (access to 300+ models). Get one at openrouter.ai/keys
​
HUGGINGFACE_API_KEY
string
Hugging Face API token for image generation fallback (FLUX.1-dev). Get one at huggingface.co/settings/tokens
​
OLLAMA_BASE_URL
string
default:"http://localhost:11434"
Ollama server URL for local models

​
Channels

​
TELEGRAM_BOT_TOKEN
string
Telegram bot token from @BotFather
​
ASTA_TELEGRAM_ALLOWED_IDS
string
Comma-separated numeric Telegram user IDs allowed to use the bot. Empty = allow all.Example: 6168747695,1234567890

​
Workspace

​
ASTA_WORKSPACE_DIR
string
Path to OpenClaw-style workspace directory (contains AGENTS.md, USER.md, TOOLS.md, SOUL.md, and skills/).If empty, Asta uses workspace/ at project root and creates it automatically.

​
Security

​
ASTA_ALLOWED_PATHS
string
Comma-separated allowed directories for file access. No trailing slashes.Example: /Users/you/Documents,/Users/you/notes
​
ASTA_EXEC_ALLOWED_BINS
string
Comma-separated binary names Asta can run (e.g. memo,things). Empty = exec disabled.Skills that need a binary show install steps on the Skills page and auto-add the bin when enabled.
​
ASTA_EXEC_SECURITY
string
default:"allowlist"
Exec security mode:
  • allowlist (default): only allowlisted bins can run
  • full: allow any command (dangerous; use only if you trust the agent)
  • deny: disable exec completely
​
ASTA_API_TOKEN
string
API bearer token for remote access (e.g. via Cloudflare Tunnel). Empty = no auth required.
​
ASTA_CORS_ORIGINS
string
Comma-separated extra CORS origins for LAN or Tailscale access.Example: http://192.168.1.113:5174,http://100.x.x.x:5173

​
Subagents

​
ASTA_SUBAGENTS_AUTO_SPAWN
boolean
default:"true"
Automatically spawn background subagent runs for explicit/complex long-task prompts
​
ASTA_SUBAGENTS_MAX_CONCURRENT
number
default:"3"
Max concurrent running child sessions
​
ASTA_SUBAGENTS_MAX_DEPTH
number
default:"1"
Max nesting depth (1 = no nested subagents)
​
ASTA_SUBAGENTS_MAX_CHILDREN
number
default:"5"
Max concurrent children per parent run
​
ASTA_SUBAGENTS_ARCHIVE_AFTER_MINUTES
number
default:"60"
Auto-archive keep-mode child sessions after N minutes (0 disables)

​
Vision

​
ASTA_VISION_PREPROCESS
boolean
default:"true"
  • true (default): analyze image with a vision model first, then pass analysis to the main agent model
  • false: skip preprocessor and send image directly only when the selected provider supports vision
​
ASTA_VISION_PROVIDER_ORDER
string
default:"openrouter,claude,openai"
Comma-separated vision provider order (first configured key wins)
​
ASTA_VISION_OPENROUTER_MODEL
string
default:"nvidia/nemotron-nano-12b-v2-vl:free"
OpenRouter vision model used by preprocessor (default is free Nemotron VL)

​
Voice Calls (Pingram)

​
ASTA_OWNER_PHONE_NUMBER
string
Your phone number for voice reminders (E.164 format: +15551234567)
​
ASTA_PINGRAM_CLIENT_ID
string
Pingram client ID from app.notificationapi.com
​
ASTA_PINGRAM_CLIENT_SECRET
string
Pingram client secret
​
ASTA_PINGRAM_API_KEY
string
Optional API key from Pingram dashboard (used as Bearer for sender)
​
ASTA_PINGRAM_NOTIFICATION_ID
string
default:"cron_alert"
Notification template ID in Pingram
​
ASTA_PINGRAM_TEMPLATE_ID
string
Template ID for voice calls
​
ASTA_MEMORY_SEARCH_MODE
string
default:"search"
Memory search mode:
  • search (default): fast lexical-first, with RAG fallback only when no local hit
  • hybrid: lexical + RAG on every query

​
Debug & Developer

​
DEBUG
boolean
default:"false"
Enable debug logging
​
ASTA_DB_PATH
string
default:"./asta.db"
SQLite database path
​
ASTA_CHROMA_PATH
string
default:"./chroma_db"
ChromaDB path for RAG memory
​
ASTA_SHOW_TOOL_TRACE
boolean
default:"false"
Show tool usage at the bottom of assistant replies (debugging)
​
ASTA_TOOL_TRACE_CHANNELS
string
default:"web"
Channels for the trace (comma-separated), e.g. web,telegram

​
Example Configuration

# AI providers
ANTHROPIC_API_KEY=sk-ant-api03-...
OPENROUTER_API_KEY=sk-or-v1-...
OLLAMA_BASE_URL=http://localhost:11434

# Channels
TELEGRAM_BOT_TOKEN=1234567890:ABC...
ASTA_TELEGRAM_ALLOWED_IDS=6168747695

# Security
ASTA_ALLOWED_PATHS=/Users/you/Documents,/Users/you/notes
ASTA_EXEC_ALLOWED_BINS=memo,things
ASTA_EXEC_SECURITY=allowlist

# Workspace
ASTA_WORKSPACE_DIR=/Users/you/asta-workspace

# Debug
DEBUG=false
ASTA_SHOW_TOOL_TRACE=false
Changes to environment variables require a backend restart to take effect.

​
Configuration File Location

The configuration logic is defined in backend/app/config.py. This file:
  • Loads variables from backend/.env
  • Provides type-safe settings via the Settings Pydantic model
  • Handles defaults and validation
  • Exposes settings via get_settings()

Build docs developers (and LLMs) love

Get started for freeTalk to us