Environment Variables

This is the complete reference for every environment variable read by the 10xGraph server. Variables are read via pydantic-settings at startup. All are optional unless marked required.

Environment variables take precedence over defaults. The .env file pointed to by 10xgraph.json’s env field is loaded before the graph module is imported, so variables are available during graph initialization.

Application

The settings model allows extra fields, so unrecognised variables in the environment are tolerated rather than rejected at startup.

Production checklist:

MODE=production
IS_DEBUG=false
LOG_LEVEL=INFO

CORS

Production values:

ORIGINS=https://app.example.com,https://admin.example.com
ALLOWED_HOST=app.example.com

API paths

Disabling docs in production:

DOCS_PATH=
REDOCS_PATH=

Request limits

Security headers

These variables control the SecurityHeadersMiddleware that is applied to every response.

Redis

REDIS_URL is optional everywhere; nothing requires it. Two things use it:

• The ownership authorization cache (L2). The ownership and rbac backends read the redis key in 10xgraph.json first and fall back to this variable. With neither set, or with the redis package not installed, the cache runs in-process only and logs a warning at startup.
• PgCheckpointer. It can use Redis as a hot cache in front of Postgres. That is a performance choice, not a requirement.

The rate limiter does not read REDIS_URL. Configure its connection under rate_limit.redis.url in 10xgraph.json.

Authentication (JWT)

Required when "auth": "jwt" is set in 10xgraph.json.

The server raises ValueError at startup if JWT_SECRET_KEY or JWT_ALGORITHM is missing when JWT auth is configured. With an HS* algorithm and MODE=production, it also refuses a JWT_SECRET_KEY shorter than 32 bytes; in development that is a warning.

A missing, invalid or expired token returns 401 with a WWW-Authenticate: Bearer header. 403 is kept for an authenticated user who lacks a scope or does not own the thread.

Snowflake ID generation

Snowflake IDs give distributed, time-ordered thread and message identifiers. They apply when your graph uses SnowFlakeIdGenerator, which needs the snowflakekit extra.

These are the values the generator actually reads, straight from os.environ, and only when it is constructed with no arguments:

In a multi-instance deployment behind a load balancer, set unique SNOWFLAKE_NODE_ID and SNOWFLAKE_WORKER_ID values per instance to prevent id collisions.

The generator’s constructor is also all-or-nothing: pass no arguments (environment-driven) or all seven. A partial call silently discards your values. See ID Generator.

OpenTelemetry

Media / file storage

These variables configure the media storage backend for file uploads (/v1/files/...).

Restrict the allowlist before exposing uploads to untrusted callers:

MEDIA_ALLOWED_CONTENT_TYPES=image/*,application/pdf

Document text extraction needs the extra: pip install "10xgraph-api[media]". See Multimodal and vision.

Cloud storage (S3 / GCS)

Used when MEDIA_STORAGE_TYPE=cloud.

Error monitoring

LLM provider

Production checklist

Minimum variables to set before a public deployment:

# Runtime
MODE=production
IS_DEBUG=false

# Security
JWT_SECRET_KEY=<random-32+-char-string>   # only if using JWT auth
ORIGINS=https://yourapp.com               # never "*" together with credentials
CORS_ALLOW_CREDENTIALS=true
ALLOWED_HOST=yourapp.com

# Disable docs (optional but recommended)
DOCS_PATH=
REDOCS_PATH=

# Distributed IDs, set unique values per instance
SNOWFLAKE_NODE_ID=1
SNOWFLAKE_WORKER_ID=1

# Media storage (for file uploads)
MEDIA_STORAGE_TYPE=local          # or cloud
MEDIA_STORAGE_PATH=/data/uploads  # writable directory in your container
MEDIA_ALLOWED_CONTENT_TYPES=image/*,application/pdf   # empty allows everything

# Redis (if using Redis rate limiting or Redis-backed checkpointer)
REDIS_URL=redis://redis:6379/0