Configuration

Customize Xagent for your environment, use cases, and preferences.

Quick Start

Create a .env file in your project root:

# Database (for docker-compose)
POSTGRES_PASSWORD=xagent_password
PORT=80

# LLM Models
OPENAI_API_KEY=sk-...
DEEPSEEK_API_KEY=sk-...

# Embeddings (for vector memory)
DASHSCOPE_API_KEY=your-dashscope-api-key

# Database encryption
ENCRYPTION_KEY=your-encryption-key

Then start with Docker Compose:

docker compose up -d

Complete Environment Variables

Core Settings

Database

# PostgreSQL (used by docker-compose)
# DATABASE_URL is automatically set
POSTGRES_PASSWORD=xagent_password

# PostgreSQL (manual setup)
DATABASE_URL=postgresql://user:password@host:port/database

# SQLite (for development)
DATABASE_URL=sqlite:///home/xagent/.xagent/xagent.db

Server

# Web service port (default: 80)
# With docker-compose, both frontend and backend
# are accessible through this port
PORT=80

Security

# Database encryption key
# Generate with:
# python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"
ENCRYPTION_KEY=your-encryption-key-here

# JWT auth (quick-start defaults)
XAGENT_JWT_SECRET=replace-with-a-long-random-secret
XAGENT_JWT_ALGORITHM=HS256
XAGENT_ACCESS_TOKEN_EXPIRE_MINUTES=120
XAGENT_REFRESH_TOKEN_EXPIRE_DAYS=7
XAGENT_PASSWORD_MIN_LENGTH=6

XAGENT_JWT_SECRET=replace-with-a-long-random-secret is a placeholder. Replace it before production deployment.

Generate a strong JWT secret with:

python -c "import secrets; print(secrets.token_urlsafe(48))"

Model Providers

OpenAI

OPENAI_API_KEY=sk-...
OPENAI_BASE_URL=https://api.openai.com/v1  # Optional
OPENAI_EMBEDDING_API_KEY=sk-...  # For embeddings

Inference API

# OpenAI-compatible inference APIs
INFERENCE_API_KEY=your-inference-api-key

DeepSeek

DEEPSEEK_API_KEY=sk-...

Anthropic / Claude

ANTHROPIC_API_KEY=sk-ant-...
CLAUDE_API_KEY=sk-ant-...  # Alternative name
CLAUDE_BASE_URL=https://api.anthropic.com  # Optional

Google / Gemini

GOOGLE_API_KEY=your-google-api-key
GEMINI_API_KEY=your-google-api-key  # Alternative name
GEMINI_BASE_URL=https://generativelanguage.googleapis.com  # Optional
GEMINI_VISION_MODEL_NAME=gemini-2.0-flash-exp  # Optional

Zhipu AI

ZHIPU_API_KEY=your-zhipu-api-key
BIGMODEL_API_KEY=your-zhipu-api-key  # Alternative name
ZHIPU_BASE_URL=https://open.bigmodel.cn  # Optional

DashScope (Alibaba Cloud)

# Used for embeddings and reranking
DASHSCOPE_API_KEY=your-dashscope-api-key

Memory Configuration

Xagent supports two memory storage types:

In-Memory Storage (Default)

Fast, non-persistent storage. No configuration required.

LanceDB Storage

Persistent vector storage for semantic search:

# Optional: Override automatic detection
MEMORY_STORE_TYPE=in_memory  # or lancedb

# LanceDB directory (when using lancedb)
MEMORY_LANCEDB_DIR=./memory_store

# Connection TTL (seconds)
LANCEDB_CONNECTION_TTL=300

If embedding API keys are configured, LanceDB is used automatically for memory storage at <project_root>/memory_store/. Without embedding keys, in-memory storage is used.

Tool Configuration

Web Search

# Google Custom Search API
GOOGLE_API_KEY=your-google-api-key
GOOGLE_CSE_ID=your-custom-search-engine-id

Proxy Settings

# HTTP/HTTPS proxy
HTTP_PROXY=http://proxy.example.com:8080
HTTPS_PROXY=http://proxy.example.com:8080
http_proxy=http://proxy.example.com:8080
https_proxy=http://proxy.example.com:8080

Image Processing

# Concurrent image processing tasks
CONCURRENT=5

Background Jobs

If you enable asynchronous jobs for long-running ingestion, indexing, or other deferred work, configure the worker runtime and broker:

XAGENT_CELERY_ENABLED=true
XAGENT_CELERY_BROKER_URL=redis://redis:6379/0
XAGENT_CELERY_RESULT_BACKEND=redis://redis:6379/0

XAGENT_BACKGROUND_JOB_VISIBILITY_TIMEOUT_SECONDS=3600
XAGENT_BACKGROUND_JOB_MAX_RETRIES=3
XAGENT_BACKGROUND_JOB_STALE_SECONDS=86400
XAGENT_BACKGROUND_JOB_SWEEP_INTERVAL_SECONDS=300

The bundled Docker Compose deployment includes Redis plus worker processes for this mode. If you disable background jobs, keep the rest of the stack aligned with your deployment choice.

Authentication Providers

Google OIDC

Use Google as an external login provider:

GOOGLE_OIDC_CLIENT_ID=your-google-client-id
GOOGLE_OIDC_CLIENT_SECRET=your-google-client-secret
GOOGLE_OIDC_REDIRECT_URI=https://your-domain/api/auth/google/callback
FRONTEND_URL=https://your-domain
OIDC_LOGIN_TTL_SECONDS=600
OIDC_EXCHANGE_TTL_SECONDS=300

FRONTEND_URL should match the user-facing URL of your Xagent deployment so browser redirects and auth hand-offs resolve correctly.

Tracing & Observability

Langfuse

Track and debug agent executions:

LANGFUSE_HOST=http://127.0.0.1:3000
LANGFUSE_PUBLIC_KEY=your-public-key
LANGFUSE_SECRET_KEY=your-secret-key

Frontend Configuration

For Next.js frontend, create .env.local:

# Backend API URL
NEXT_PUBLIC_API_URL=http://localhost:8000

# WebSocket URL
NEXT_PUBLIC_WS_URL=ws://localhost:8000

# Theme (optional: dark, light, blue, green, purple, cyber, cyberLight)
NEXT_PUBLIC_THEME=dark

# Branding (optional)
NEXT_PUBLIC_APP_NAME=Xagent
NEXT_PUBLIC_APP_SUBTITLE=下一代智能体操作系统
NEXT_PUBLIC_LOGO_PATH=/xagent_logo.svg

# Colors (optional)
NEXT_PUBLIC_GRADIENT_FROM=blue-400
NEXT_PUBLIC_GRADIENT_VIA=blue-500
NEXT_PUBLIC_GRADIENT_TO=indigo-500

Example Configuration Files

Docker Compose (.env)

# ===========================================
# Core Settings
# ===========================================
POSTGRES_PASSWORD=xagent_password
PORT=80

# ===========================================
# LLM Models
# ===========================================
OPENAI_API_KEY=sk-...
INFERENCE_API_KEY=your-inference-api-key
DEEPSEEK_API_KEY=sk-...

# ===========================================
# Embeddings
# ===========================================
DASHSCOPE_API_KEY=your-dashscope-api-key
OPENAI_EMBEDDING_API_KEY=your-openai-api-key

# ===========================================
# Encryption
# ===========================================
ENCRYPTION_KEY=RQMpe38gK3m0szjpSmTNw_sP3Y54r6hDc6JewBoPKXc=

# ===========================================
# Optional: Background Jobs
# ===========================================
XAGENT_CELERY_ENABLED=true
XAGENT_CELERY_BROKER_URL=redis://redis:6379/0
XAGENT_CELERY_RESULT_BACKEND=redis://redis:6379/0
XAGENT_BACKGROUND_JOB_VISIBILITY_TIMEOUT_SECONDS=3600
XAGENT_BACKGROUND_JOB_MAX_RETRIES=3
XAGENT_BACKGROUND_JOB_STALE_SECONDS=86400
XAGENT_BACKGROUND_JOB_SWEEP_INTERVAL_SECONDS=300

# ===========================================
# Optional: Google OIDC
# ===========================================
GOOGLE_OIDC_CLIENT_ID=your-google-client-id
GOOGLE_OIDC_CLIENT_SECRET=your-google-client-secret
GOOGLE_OIDC_REDIRECT_URI=https://your-domain/api/auth/google/callback
FRONTEND_URL=https://your-domain
OIDC_LOGIN_TTL_SECONDS=600
OIDC_EXCHANGE_TTL_SECONDS=300

# ===========================================
# Optional: Web Search
# ===========================================
GOOGLE_API_KEY=your-google-api-key
GOOGLE_CSE_ID=your-cse-id

# ===========================================
# Optional: Tracing
# ===========================================
LANGFUSE_HOST=http://127.0.0.1:3000
LANGFUSE_PUBLIC_KEY=pk-...
LANGFUSE_SECRET_KEY=sk-...

Local Development (.env)

# Database (SQLite for local development)
DATABASE_URL=sqlite:///home/xagent/.xagent/xagent.db

# Models
OPENAI_API_KEY=sk-...
DEEPSEEK_API_KEY=sk-...

# Embeddings
DASHSCOPE_API_KEY=your-dashscope-api-key

# Encryption
ENCRYPTION_KEY=your-encryption-key

# Port
PORT=8000

# Optional: Background Jobs
XAGENT_CELERY_ENABLED=false

# Optional: Google OIDC
FRONTEND_URL=http://localhost:3000

# Optional: Tracing
LANGFUSE_HOST=http://127.0.0.1:3000
LANGFUSE_PUBLIC_KEY=pk-...
LANGFUSE_SECRET_KEY=sk-...

Security Best Practices

Generate strong keys — Use cryptographic tools for secrets
Restrict permissions — chmod 600 .env
Environment isolation — Different keys for dev, staging, production
Regular rotation — Update secrets periodically
Use vaults — AWS Secrets Manager, HashiCorp Vault for production

Channels

Deployment

Configuration

Configuration

Quick Start

Complete Environment Variables

Core Settings

Database

Server

Security

Model Providers

OpenAI

Inference API

DeepSeek

Anthropic / Claude

Google / Gemini

Zhipu AI

DashScope (Alibaba Cloud)

Memory Configuration

In-Memory Storage (Default)

LanceDB Storage

Tool Configuration

Web Search

Proxy Settings

Image Processing

Background Jobs

Authentication Providers

Google OIDC

Tracing & Observability

Langfuse

Frontend Configuration

Example Configuration Files

Docker Compose (.env)

Local Development (.env)

Security Best Practices

Next Steps

​Configuration

​Quick Start

​Complete Environment Variables

​Core Settings

​Database

​Server

​Security

​Model Providers

​OpenAI

​Inference API

​DeepSeek

​Anthropic / Claude

​Google / Gemini

​Zhipu AI

​DashScope (Alibaba Cloud)

​Memory Configuration

​In-Memory Storage (Default)

​LanceDB Storage

​Tool Configuration

​Web Search

​Proxy Settings

​Image Processing

​Background Jobs

​Authentication Providers

​Google OIDC

​Tracing & Observability

​Langfuse

​Frontend Configuration

​Example Configuration Files

​Docker Compose (.env)

​Local Development (.env)

​Security Best Practices

​Next Steps

Configuration

Quick Start

Complete Environment Variables

Core Settings

Database

Server

Security

Model Providers

OpenAI

Inference API

DeepSeek

Anthropic / Claude

Google / Gemini

Zhipu AI

DashScope (Alibaba Cloud)

Memory Configuration

In-Memory Storage (Default)

LanceDB Storage

Tool Configuration

Web Search

Proxy Settings

Image Processing

Background Jobs

Authentication Providers

Google OIDC

Tracing & Observability

Langfuse

Frontend Configuration

Example Configuration Files

Docker Compose (.env)

Local Development (.env)

Security Best Practices

Next Steps