.env.example

# ═══════════════════════════════════════════════════════════════════════════════
# Astra — Environment Configuration
# ═══════════════════════════════════════════════════════════════════════════════
#
# Quick start:
#   1. cp .env.example .env
#   2. Fill in required values (marked REQUIRED below)
#   3. make dev-start
#
# `ASTRA_ALLOW_INSECURE_DEFAULTS=1` lets missing required keys fall back to
# bundled insecure defaults — convenient for dev, NEVER use in production.
#
# Related config files:
#   .models.yaml.example  — LLM model definitions (providers, pricing, tags)
#   gateway.example.yaml  — Gateway bridge configuration (WeChat, CLI profiles)

# ── Database: MatrixOne ────────────────────────────────────────────────────
# MatrixOne is MySQL-protocol compatible. Any MySQL client works.
# Default dev setup: `make dev-deps-up` starts MatrixOne on port 6001.
MATRIXONE_HOST=localhost
MATRIXONE_PORT=6001
MATRIXONE_USER=root
MATRIXONE_PASSWORD=111
# MySQL endpoint TLS policy used by development commands. `auto` probes with
# a harmless authenticated request, prefers TLS when usable, and deliberately
# falls back for a local plaintext MatrixOne endpoint. Use `disabled` only for
# a known non-TLS endpoint, or `required` when TLS is mandatory. The adapter
# selects only flags supported by the installed client.
# ASTRA_MYSQL_TLS_MODE=auto

# Logical database name. Effective name = ${ASTRA_DATABASE_PREFIX}${ASTRA_DATABASE}.
# Useful for multi-tenant or test isolation (e.g. prefix=test_ → test_astra_runtime).
ASTRA_DATABASE=astra_runtime
#ASTRA_DATABASE_PREFIX=test_

# Auto-create the database on first startup. Set to 1 to enable.
# Safe for dev; in production, pre-create the database manually.
ASTRA_AUTO_CREATE_DATABASE=1

# Bootstrap catalog for CREATE DATABASE statement. Only change if your MatrixOne
# setup uses a non-default system catalog. Default: mysql.
#ASTRA_DATABASE_BOOTSTRAP_CATALOG=mysql

# Separate database for `make test-online` to avoid polluting dev data.
# Default: astra_runtime_test.
#ASTRA_TEST_DATABASE=astra_runtime_test

# Enable DB integration tests (required for `make test-online`).
ASTRA_TEST_DB_IT=1

# ── Application ────────────────────────────────────────────────────────────
# Development only: permits bundled insecure defaults for JWT secret, encryption
# key, and runtime root secret. NEVER enable in production.
ASTRA_ALLOW_INSECURE_DEFAULTS=1

# Logging: standard RUST_LOG format (tracing ecosystem).
# Examples:
#   RUST_LOG=warn,astra_runtime=debug          — debug API server
#   RUST_LOG=warn,astra_runtime=debug,sqlx=debug — include SQL queries
#   RUST_LOG=info                              — production default

# ── API Server ─────────────────────────────────────────────────────────────
# Local development listens on loopback. Set 0.0.0.0 explicitly only when an
# external client must connect and network access is otherwise controlled.
ASTRA_API_HOST=127.0.0.1
ASTRA_API_PORT=17001

# CORS: comma-separated allowed origins.
# Unset or "*" allows any origin (fine for dev, restrict in production).
# Example: ASTRA_CORS_ORIGINS=http://localhost:3536,http://127.0.0.1:3536
#ASTRA_CORS_ORIGINS=

# ── Auth: JWT & Encryption (REQUIRED in production) ────────────────────────
#
# All three secrets below MUST be set in production. In dev, if
# ASTRA_ALLOW_INSECURE_DEFAULTS=1, the server falls back to built-in values.
#
# ASTRA_JWT_SECRET: signs access/refresh tokens.
#   Requirements: minimum 32 characters.
#   Generate: openssl rand -hex 32
ASTRA_JWT_SECRET=your-jwt-secret-min-32-characters-long-change-me

# JWT algorithm. Supported: HS256 (default), HS384, HS512.
ASTRA_JWT_ALGORITHM=HS256

# Access token TTL. Code default: 10080 minutes (7 days) for dev convenience.
# Production recommendation: 15-60 minutes.
#ASTRA_JWT_ACCESS_TTL_MINUTES=60

# Refresh token TTL. Used to issue new access tokens without re-login.
ASTRA_JWT_REFRESH_TTL_DAYS=7

# ASTRA_TOKEN_ENCRYPTION_KEY: encrypts stored LLM provider API keys at rest.
#   Requirements: a high-entropy secret. Astra derives its Fernet key from it.
#   Generate: openssl rand -hex 32
#   Keep it unchanged: existing provider credentials cannot be decrypted otherwise.
ASTRA_TOKEN_ENCRYPTION_KEY=

# ASTRA_RUNTIME_ROOT_SECRET: root secret for purpose-separated runtime signatures.
#   Requirements: minimum 32 characters.
#   Generate: openssl rand -hex 32
ASTRA_RUNTIME_ROOT_SECRET=your-runtime-root-secret-min-32-characters-change-me

# ── LLM ────────────────────────────────────────────────────────────────────
# LLM models are managed server-side via .models.yaml (see .models.yaml.example).
#
# Workflow:
#   1. cp .models.yaml.example .models.yaml   # edit API keys
#   2. astra admin model load .models.yaml    # import to DB
#   3. astra admin model check <name>         # activate after connectivity probe
#   4. astra admin config set reasoning_offering_id <id>  # optional: judge/summary Offering
#
# If no reasoning model is set, the server uses the cheapest active model.

# Optional runtime tuning (safe to leave unset — sensible defaults apply):
#ASTRA_MAX_HISTORY_TOKENS=           # Max tokens of conversation history sent to LLM
#ASTRA_COMPRESSION_THRESHOLD=        # Token count triggering history compression
#ASTRA_RETRIEVAL_TOP_K=              # Number of memory/RAG results to include
#ASTRA_MAX_TURN_INPUT_TOKENS=        # Hard cap on single-turn input tokens
#ASTRA_CAPTURE_TRACES=1              # Enable LLM exchange trace capture (for debugging)
# Durable harness snapshot DB history follows runtime.toml trace config
# (`trace.profile = "dev"` or the `harness_snapshots` trace category).

# Provider admission is off by default. Enable it when many pods/CLIs share one
# external LLM quota and you want fail-fast internal rejection instead of a
# provider-side 429 storm.
#ASTRA_LLM_PROVIDER_ADMISSION_MODE=db_fixed_window
#ASTRA_LLM_PROVIDER_ADMISSION_RPM=60
#ASTRA_LLM_PROVIDER_ADMISSION_TPM=
# Provider admission scope/window/cleanup and run admission timeout are runtime
# policy, not deployment knobs.

# The built-in Work admission judge runs concurrently with each primary turn
# by default, then is awaited only at a durable/effectful boundary. This keeps
# tracked requests from silently becoming untracked tool calls without adding
# judge latency to the ordinary primary path. `capacity_aware` keeps this
# correctness boundary enabled while provider admission accounts for its
# quota; unrelated optional judges remain capacity-gated. Under Auto,
# `disabled` makes semantic admission unavailable and therefore fails closed;
# clients that deliberately omit classification must request FixedDefault.
# Use `always` to ignore capacity gating for all eligible auxiliary features.
#ASTRA_AUX_LLM_POLICY=capacity_aware

# ── Memoria (Memory Service) ──────────────────────────────────────────────
# Memoria provides persistent semantic memory (store/retrieve/search).
# Started automatically by `make dev-deps-up`.
#
# MEMORIA_BASE_URL: HTTP endpoint of the Memoria API.
MEMORIA_BASE_URL=http://127.0.0.1:8100
# Development compose uses the same immutable, owner-auth capable image as
# the all-in-one deployment example. Keep this value when creating .env so a
# missing local override cannot silently select an incompatible `latest` tag.
MEMORIA_IMAGE=matrixorigin/memoria@sha256:702389efe1d67e3074f024b5c721dc83fc215e9b66cb7b0362dc4e8077c9d061
# Stable identity authority (defaults to the normalized API URL).
# MEMORIA_ISSUER=https://memoria.example.com
# Server-owned login website; leave unset for self-hosted password login.
# MEMORIA_WEB_URL=https://thememoria.ai

# MEMORIA_MASTER_KEY: API authentication key (minimum 16 characters).
MEMORIA_MASTER_KEY=change-me-min-16-chars
# Explicitly allow authenticated local users without a scoped Memoria binding
# to use the deployment master through the owner-scoped Memoria-Owner scheme.
# Existing scoped bindings and their none/read_only consent always win. Keep
# disabled for hosted deployments and Memoria v0.5.1 or older.
# This template is for local development with the repository-pinned Memoria.
MEMORIA_SELF_HOSTED_MASTER_ACCESS=1

# MEMORIA_EMBEDDING_PROVIDER: which embedding backend Memoria uses.
#   Values: openai  — any OpenAI-compatible embedding API (default)
#           mock    — deterministic embeddings for local evaluation/tests (no API needed; not production retrieval)
MEMORIA_EMBEDDING_PROVIDER=openai

# MEMORIA_EMBEDDING_MODEL: model name passed to the embedding API.
#   Examples: BAAI/bge-m3, text-embedding-3-small, text-embedding-ada-002
MEMORIA_EMBEDDING_MODEL=BAAI/bge-m3

# MEMORIA_EMBEDDING_DIM: output vector dimension. Must match the model's output.
#   Common values: 384 (mini), 768 (base), 1024 (bge-m3), 1536 (ada-002), 3072 (3-large)
MEMORIA_EMBEDDING_DIM=1024

# MEMORIA_EMBEDDING_API_KEY: API key for the embedding provider.
#   Leave empty if using a local/self-hosted embedding service without auth.
MEMORIA_EMBEDDING_API_KEY=

# MEMORIA_EMBEDDING_BASE_URL: base URL for the embedding API.
#   Examples:
#     https://api.openai.com/v1              — OpenAI
#     https://dashscope.aliyuncs.com/compatible-mode/v1  — DashScope
#     http://localhost:11434/v1              — Ollama (local)
MEMORIA_EMBEDDING_BASE_URL=

# ── Personal BYOK endpoint policy ────────────────────────────────────────
# Personal OpenAI-compatible BYOK endpoints: public HTTPS by default.
# Opt into the existing administrator host/port registry with trusted-domains.
# Both modes reject private/metadata targets, pin public DNS, and disable redirects.
# ASTRA_BYOK_ENDPOINT_POLICY=public-https
# Cloud BYOK rejects deployment-owned model inference for all end users.
# Memoria identities are always personal BYOK, even in self-hosted mode.
# ASTRA_DEPLOYMENT_MODE=self-hosted
# Custom BYOK DNS queries go directly to system-configured DNS servers, avoiding
# OS Fake-IP caches. DNS priority is preserved rather than racing nameservers.
# Optionally choose reachable DNS IPs (comma-separated, ports optional).
# ASTRA_BYOK_DNS_SERVERS=10.0.0.53,10.0.0.54:53
# If UDP DNS is intercepted, explicitly select TCP-only DNS (no UDP fallback).
# ASTRA_BYOK_DNS_SERVERS=tcp://10.0.0.53:53
# Default is direct egress. Optional operator-owned HTTP(S) CONNECT or SOCKS5 proxy.
# Ambient HTTP_PROXY/HTTPS_PROXY/ALL_PROXY are not used for custom BYOK endpoints.
# The proxy must accept validated public IP targets; origin TLS/SNI remains unchanged.
# ASTRA_BYOK_PROXY_URL=http://127.0.0.1:7890

# ── Skill Selector Rerank (optional) ──────────────────────────────────────
# Optional LLM-based reranker for skill selection. Uses any OpenAI-compatible
# chat completions endpoint. Leave all unset to disable (keyword matching only).
#ASTRA_SKILL_SELECTOR_RERANK_BASE_URL=
#ASTRA_SKILL_SELECTOR_RERANK_API_KEY=
#ASTRA_SKILL_SELECTOR_RERANK_MODEL=

# ── Edge / Multi-Agent (optional) ─────────────────────────────────────────
# For distributed multi-agent deployments where edge executors register with
# a central registry and receive delegated tasks.
#ASTRA_EDGE_REGISTRY=               # Registry URL (e.g. http://central:17001)
#ASTRA_EDGE_HEARTBEAT_SECS=120      # Heartbeat interval to registry
#ASTRA_EDGE_EXECUTOR_ID=            # Unique executor identifier
#ASTRA_EDGE_AGENT_ID=               # Agent ID this executor serves

# ── GitHub Integration (optional) ─────────────────────────────────────────
# Personal access token for GitHub operations (PR review, issue reading, etc.).
# Read directly by the CLI's git tools. Requires: repo, read:org scopes.
#GITHUB_TOKEN=

# ── CLI Overrides (optional) ──────────────────────────────────────────────
# Override CLI defaults for local development. These only affect the `astra` CLI,
# not the API server.
#ASTRA_CLI_USER_ID=                # User ID for local task/session ownership metadata
#ASTRA_CLI_SESSION_ID=             # Resume or pin the CLI to a specific session UUID
#ASTRA_CLI_SESSION_NAME=           # Human-friendly session name when starting a new session
#ASTRA_CLI_AUTO_APPROVE=            # Auto-approve tool calls (comma-separated tool names, or "all")
#ASTRA_CLI_ALLOWED_TOOLS=           # Whitelist of allowed tools (comma-separated)
#ASTRA_CLI_DISALLOWED_TOOLS=        # Blacklist of disallowed tools (comma-separated)
#ASTRA_CLI_ADD_DIRS=                # Additional directories to include in context
#ASTRA_CLI_CREDENTIALS_DIR=         # Custom credentials storage directory