Environment Variables

Open Astra reads all configuration from environment variables. In development, these are loaded from a .env file in the project root. In production, set them directly in your deployment environment.

⚠The gateway will refuse to start if any required variable is missing. Run npx astra doctor to diagnose configuration issues.

Required variables

These variables are required in server mode (Docker Compose or direct npm start). The npx astra wizard generates them automatically.

Variable	Description	Example
`JWT_SECRET`	Secret used to sign and verify JWT tokens. Must be at least 32 characters.	`a-very-long-random-string`
`TYPESENSE_API_KEY`	Admin API key for Typesense. Set the same value in Typesense startup config.	`change-me`
`INTERNAL_API_KEY`	Secret key for internal service-to-service calls (scheduler, heartbeat).	`another-random-string`
`PG_HOST`	PostgreSQL hostname	`localhost`
`PG_PORT`	PostgreSQL port	`5432`
`PG_DATABASE`	PostgreSQL database name	`astra`
`PG_USER`	PostgreSQL username	`astra`
`PG_PASSWORD`	PostgreSQL password	`astra`

Inference provider keys

At least one provider key must be set. The gateway will not start if zero provider keys are found.

Variable	Provider	Prompt caching
`OPENAI_API_KEY`	OpenAI (GPT-4o, o1, o3)	50–90%
`ANTHROPIC_API_KEY`	Anthropic (Claude)	90%
`GEMINI_API_KEY`	Google Gemini	90%
`GROK_API_KEY`	xAI Grok	75%
`GROQ_API_KEY`	Groq (fast inference)	None
`MISTRAL_API_KEY`	Mistral AI	None
`OPENROUTER_API_KEY`	OpenRouter (multi-provider proxy)	Varies
`OLLAMA_BASE_URL`	Ollama (local models)	None
`VLLM_API_KEY`	vLLM (self-hosted) — optional; also requires `endpoint` in the agent config	None
`AWS_REGION`	AWS Bedrock (also needs `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`)	None

Optional variables

Variable	Default	Description
`PORT`	`3000`	HTTP port for Docker Compose / production deployments
`GATEWAY_PORT`	`8080`	HTTP port used by `npx astra` (dev mode)
`NODE_ENV`	`development`	Set to `production` for production logging
`LOG_LEVEL`	`info`	`debug` \| `info` \| `warn` \| `error`
`TYPESENSE_HOST`	`localhost`	Typesense hostname
`TYPESENSE_PORT`	`8108`	Typesense port
`TYPESENSE_PROTOCOL`	`http`	`http` or `https`
`TYPESENSE_NODES`	—	Comma-separated `host:port` list for Typesense multi-node clusters (e.g. `ts1:8108,ts2:8108`)
`TELEGRAM_BOT_TOKEN`	—	Enable Telegram channel integration
`DISCORD_BOT_TOKEN`	—	Enable Discord channel integration
`SLACK_BOT_TOKEN`	—	Enable Slack channel integration
`SLACK_SIGNING_SECRET`	—	Required with `SLACK_BOT_TOKEN`
`WHATSAPP_PHONE_NUMBER_ID`	—	Enable WhatsApp channel integration
`WHATSAPP_ACCESS_TOKEN`	—	Required with `WHATSAPP_PHONE_NUMBER_ID`
`SIGNAL_API_URL`	—	Enable Signal channel integration
`SIGNAL_PHONE_NUMBER`	—	Required with `SIGNAL_API_URL`
`BLUEBUBBLES_URL`	—	Enable iMessage via BlueBubbles
`BLUEBUBBLES_PASSWORD`	—	Required with `BLUEBUBBLES_URL`
`GOOGLE_CHAT_SERVICE_ACCOUNT_KEY`	—	Enable Google Chat integration (JSON string)
`WEBHOOK_URL`	—	Default outbound webhook for agent events
`WEBHOOK_SECRET`	—	HMAC secret for webhook signature verification

Secrets backend

Variable	Default	Description
`SECRET_BACKEND`	`env`	`env` \| `vault` \| `aws-asm` — see Secrets Management
`VAULT_ADDR`	`http://vault:8200`	HashiCorp Vault base URL (Vault backend only)
`VAULT_TOKEN`	—	Vault authentication token (Vault backend only)
`SECRET_TTL_SECONDS`	`300`	TTL for in-process secret cache

Auth hardening

Variable	Default	Description
`JWT_SECRET_PREV`	—	Previous JWT secret; tokens signed with either current or previous secret are accepted during rotation
`BIND_JWT_TO_DEVICE`	`false`	Bind tokens to a device fingerprint (User-Agent + IP subnet) to prevent replay attacks

gRPC mTLS

Variable	Default	Description
`GRPC_TLS_CERT`	—	Path to the server TLS certificate (PEM). If unset, gRPC starts in insecure mode.
`GRPC_TLS_KEY`	—	Path to the server TLS private key (PEM)
`GRPC_TLS_CA`	—	Path to the CA certificate for client cert verification (mutual TLS)

Memory and caching

Variable	Default	Description
`MEMORY_TTL_DAYS`	`90`	Default TTL for daily_memory and session entries before cold-store archival
`SEMANTIC_CACHE_ENABLED`	`false`	Enable pgvector semantic response cache — reuses responses for queries with cosine similarity ≥ 0.97
`MEMORY_BACKEND_TIMEOUT_MS`	`500`	Per-backend timeout for tiered memory search (Typesense + pgvector)
`SPLADE_ENDPOINT`	—	URL of a SPLADE sparse embedding server for hybrid sparse+dense retrieval

Cold store

Variable	Default	Description
`COLD_STORE_BACKEND`	—	`s3` \| `gcs` \| `local` — see Cold Store
`COLD_STORE_BUCKET`	—	S3 bucket name or GCS bucket name
`COLD_STORE_REGION`	—	AWS region (S3 only)
`COLD_STORE_PREFIX`	—	Key prefix for all snapshot objects (e.g. `astra/memory/`)

Complete example .env

bash

# Core
JWT_SECRET=replace-with-64-char-random-string
TYPESENSE_API_KEY=replace-with-secure-key
INTERNAL_API_KEY=replace-with-secure-key

# PostgreSQL
PG_HOST=localhost
PG_PORT=5432
PG_DATABASE=astra
PG_USER=astra
PG_PASSWORD=astra

# Providers (add at least one)
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GEMINI_API_KEY=AIza...

# Server
PORT=3000
NODE_ENV=development
LOG_LEVEL=info

# Optional: Channels
TELEGRAM_BOT_TOKEN=123456:ABC-DEF...