Environment Variables
In shortReference for every environment variable the 10xGraph API server recognizes, grouped by area such as auth, CORS, logging, and Snowflake ID settings.
- 16 min read
- 16 sections
- Updated
- v1.0.0
- Markdown
The 10xGraph API server and CLI read configuration from environment variables. This page lists every variable with its default and effect, grouped by area. Set server variables in a .env file referenced by 10xgraph.json or in the process environment. CLI variables control terminal output.
Setting server variables
Via .env file
In 10xgraph.json:
{
"agent": "graph.react:app",
"env": ".env"
}In .env:
GOOGLE_API_KEY=your-key
JWT_SECRET_KEY=your-secret
MODE=productionAt the process level
MODE=production 10xgraph dev --no-reloadApplication variables
| Variable | Default | Description |
|---|---|---|
APP_NAME |
MyApp |
Application name shown in logs |
APP_VERSION |
0.1.0 |
Application version |
MODE |
development |
production (or prod), or development (or dev, local). Trimmed and case-insensitive. Unset means development. Any other value stops the server at startup, and 10xgraph dev exits with code 2; the message lists the accepted values. Drives several defaults, including debug mode (on in development, off in production), the run timeout and the strict startup checks. |
STRICT_PRODUCTION_CHECKS |
on in production | In production, refuse to start on a wildcard ALLOWED_HOST, a wildcard ORIGINS, or an enabled DOCS_PATH or REDOCS_PATH. Set false to log warnings instead. Has no effect outside production. |
LOG_LEVEL |
INFO |
Logging level: DEBUG, INFO, WARNING, ERROR |
LOG_FORMAT |
text |
json writes every application log line as one JSON object (ts, level, logger, message, plus request_id, transport and user_id when known and exc_info for an exception). Secret redaction still applies. 10xgraph build sets json in the generated production env. See Observability. |
SUMMARY |
10xGraph Backend |
One-line service summary shown in the OpenAPI schema |
LOGGER_NAME |
10xgraph-api |
Name of the root logger the server writes under. Read at import time, so it must be a process environment variable; setting it in .env is too late. |
GRAPH_PATH |
10xgraph.json |
Path to the config file the ASGI app loads. 10xgraph dev --config sets this for you; set it directly when running the app under an external server such as Gunicorn or Uvicorn. |
The settings model allows extra variables, so unknown names in the environment are tolerated rather than rejected.
Startup check variables
| Variable | Default | Description |
|---|---|---|
STARTUP_CHECKS |
true |
Before serving, ping every configured backend and refuse to start while one stays unreachable. Applies in development and production. false skips the check and logs a warning. |
STARTUP_CHECK_TIMEOUT_SECONDS |
30 |
Seconds the check keeps retrying an unreachable backend (with a short backoff) before it gives up, so services started together can come up in any order. Must be 0 or more. |
The check calls aping() on the checkpointer (Postgres, its schema version and its Redis cache), on the store when one is bound, and on the API’s cache store. It does not check the model provider. The checkpointer and the store are fatal when they stay down. The cache store is fatal only when a fail-closed feature uses it (cache_store.token_revocation on with auth, or cache_store.rate_limit on with fail_open set to false); otherwise the server logs one warning and starts. When the server exits, the message names each backend and its endpoint, never credentials. See Startup check and Backend unreachable at startup.
Security headers
Applied by the security-headers middleware when SECURITY_HEADERS_ENABLED is true.
| Variable | Default | Description |
|---|---|---|
SECURITY_HEADERS_ENABLED |
true |
Add security headers to all responses |
HSTS_ENABLED |
true |
Add Strict-Transport-Security |
HSTS_MAX_AGE |
31536000 |
HSTS max age in seconds (one year) |
HSTS_INCLUDE_SUBDOMAINS |
true |
Add includeSubDomains to the HSTS header |
HSTS_PRELOAD |
false |
Add preload to the HSTS header. Only enable if you intend to submit the domain to the preload list; it is hard to undo. |
FRAME_OPTIONS |
DENY |
X-Frame-Options value: DENY, SAMEORIGIN, or ALLOW-FROM |
CONTENT_TYPE_OPTIONS |
nosniff |
X-Content-Type-Options value |
XSS_PROTECTION |
1; mode=block |
X-XSS-Protection value |
REFERRER_POLICY |
strict-origin-when-cross-origin |
Referrer-Policy value |
PERMISSIONS_POLICY |
null |
Permissions-Policy value. Unset uses the middleware’s built-in default. |
CSP_POLICY |
null |
Content-Security-Policy value. Unset uses the middleware’s built-in default. |
CORS variables
| Variable | Default | Description |
|---|---|---|
ORIGINS |
* |
Comma-separated allowed origins. Set to specific domains in production. |
ALLOWED_HOST |
* |
Allowed Host header values |
CORS_ALLOW_CREDENTIALS |
true |
Whether cross-origin requests may carry cookies or auth headers |
Authentication variables
| Variable | Description | Required for |
|---|---|---|
JWT_SECRET_KEY |
Secret key for JWT signing and verification. No default. | auth: "jwt" |
JWT_ALGORITHM |
JWT algorithm. Default HS256. Allowed values: HS256, HS384, HS512, RS256, RS384, RS512, ES256, ES384, ES512, PS256, PS384, PS512 and EdDSA, spelled exactly. none, an empty value or any other value stops startup. |
auth: "jwt" |
JWT_ISSUER |
Required iss claim. Unset or empty: the issuer is not checked and a token with any iss, or none, is accepted. Set: the token must carry iss and it must match exactly, else 401 INVALID_TOKEN. |
Optional |
JWT_AUDIENCE |
Required aud claim. Unset or empty: a token without aud is accepted, but a token that carries aud is refused (401 INVALID_TOKEN). Set: the token must carry aud and it must match, else 401 INVALID_TOKEN. |
Optional |
JWT_SECRET_KEYS |
Extra verification keys for rotation, as a JSON list of {"kid": "...", "key": "..."} objects or plain strings. Tried beside JWT_SECRET_KEY, which keeps working unchanged. Unset by default. See rotate the signing key. |
Optional |
JWT_MAX_TOKEN_AGE_SECONDS |
Refuse a token older than this many seconds by its iat claim, and refuse a token with no iat. Unset (off) by default. |
Optional |
Both must be set when 10xgraph.json has "auth": "jwt"; the config load raises a ValueError otherwise and the server does not start. JWT support also needs the extra: pip install "10xgraph-api[jwt]". The server checks at startup that PyJWT is installed and stops if it is missing.
Redis variables
| Variable | Default | Description |
|---|---|---|
REDIS_URL |
null |
Redis connection URL, for example redis://localhost:6379/0. Feeds cache_store of type redis when it has no url. Not read by the API in any other case |
REDIS_SOCKET_TIMEOUT |
5.0 |
Seconds a Redis call may take before it fails, so a Redis that stops answering does not hang the request. 0 turns the timeout off. |
REDIS_CONNECT_TIMEOUT |
5.0 |
Seconds to wait when opening a Redis connection. 0 turns it off. |
REDIS_MAX_CONNECTIONS |
50 |
Pool size of each Redis client the API opens. 0 means no bound. |
REDIS_POOL_TIMEOUT |
5.0 |
Seconds a request waits for a free pooled connection. 0 means no timeout. |
REDIS_KEY_PREFIX |
"" |
Put in front of every key the API writes to Redis (run locks and caps, idempotency, token revocation, rate limiting), so two deployments sharing one Redis cannot read each other’s entries. The core checkpointer has its own redis_key_prefix option for its cache keys. To separate a whole deployment, set both to the same value. |
REDIS_HEALTH_CHECK_INTERVAL |
30.0 |
Seconds between health checks of an idle connection. 0 turns them off. |
The REDIS_* limits apply to the Redis client behind the API’s cache store (RedisCacheStore).
REDIS_URL is optional everywhere. The API reads it only when cache_store has "type": "redis" and no url (or a url such as ${REDIS_URL} that expands it). REDIS_URL alone never selects Redis: with no cache_store the API uses the in-memory store even when the variable is set. A cache_store.url you set wins over the variable, so the cache store can use a different Redis than your checkpointer. The server logs one INFO line at boot that names the store and the config key it came from.
- The cache store.
RedisCacheStoreshares run locks, run and WebSocket caps, idempotency, token revocation and rate limiting between workers. With the in-memory type they live in each process. Valkey, Dragonfly and KeyDB work through the same URL. PgCheckpointer. It requires a Redis connection (redis_url,redis_poolorredis) as the hot cache in front of Postgres; constructing it without one raisesValueError. It does not readREDIS_URLitself, so pass the URL to its constructor in your own code, for exampleredis_url=os.environ["REDIS_URL"]. The durable data lives in Postgres.
The rate limiter has no Redis setting of its own; it uses the cache store.
Snowflake ID variables
Read only by SnowFlakeIdGenerator, and only when it is constructed with no arguments.
| Variable | Default | Description |
|---|---|---|
SNOWFLAKE_EPOCH |
1723323246031 |
Custom epoch in milliseconds |
SNOWFLAKE_TOTAL_BITS |
64 |
Total bits in the generated id |
SNOWFLAKE_TIME_BITS |
39 |
Bits reserved for the timestamp |
SNOWFLAKE_NODE_BITS |
7 |
Bits reserved for the node id |
SNOWFLAKE_NODE_ID |
0 |
This node’s id |
SNOWFLAKE_WORKER_BITS |
5 |
Bits reserved for the worker id |
SNOWFLAKE_WORKER_ID |
0 |
This worker’s id |
See ID Generator for the constructor contract.
Observability
| Variable | Default | Description |
|---|---|---|
OTEL_ENABLED |
false |
Enable OpenTelemetry tracing |
OTEL_SERVICE_NAME |
10xgraph-api |
Service name reported in spans |
OTEL_EXPORTER_OTLP_ENDPOINT |
null |
OTLP collector endpoint. Unset: spans print to the console in development; with MODE=production nothing is exported and a warning is logged |
OTEL_EXPORTER_OTLP_HEADERS |
none | Standard OpenTelemetry variable. Auth headers for OTLP trace and metric export from the observability.otlp and metrics blocks, as key=value,key2=value2 |
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT |
none | OTLP HTTP trace URL, used when observability.otlp.endpoint is null. OTEL_EXPORTER_OTLP_ENDPOINT is not used for this |
OTEL_EXPORTER_OTLP_METRICS_ENDPOINT |
none | OTLP HTTP metrics URL, used when metrics.otlp.endpoint is not set |
OTEL_SEMCONV_STABILITY_OPT_IN |
http |
The server sets it to http when unset, so HTTP metrics use the stable names. See Metrics with Prometheus and Grafana |
OTEL_LEVEL |
full |
Trace detail: spans, standard, or full. full sends message content and graph state to the trace backend; standard keeps graph state but drops prompts, completions and tool I/O; spans is timing and structure only |
OpenTelemetry needs the extra: pip install "10xgraph-api[otel]", which also brings the FastAPI instrumentation and the OTLP exporter.
Logfire and LangSmith are configured through the observability block in 10xgraph.json; their secrets (LOGFIRE_TOKEN, LANGSMITH_API_KEY) come from the environment.
Error tracking and sampling
| Variable | Default | Description |
|---|---|---|
SENTRY_DSN |
null |
Sentry DSN for error tracking (optional) |
SENTRY_TRACES_SAMPLE_RATE |
0.1 |
Fraction of requests to trace. Range: 0.0 to 1.0. A value of 0.1 means 10% of requests are traced. Set to 0.0 to disable tracing without disabling error tracking. |
SENTRY_PROFILES_SAMPLE_RATE |
0.0 |
Fraction of traced requests to profile. Range: 0.0 to 1.0. Profiling is expensive; most deployments use 0.0 or a very low rate like 0.01. Requires SENTRY_TRACES_SAMPLE_RATE > 0. |
For Sentry integration, install: pip install "10xgraph-api[sentry]".
Media and multimodal
| Variable | Default | Description |
|---|---|---|
MEDIA_STORAGE_TYPE |
local |
memory, local, or cloud |
MEDIA_STORAGE_PATH |
./uploads |
Directory used by the local store |
MEDIA_MAX_SIZE_MB |
25.0 |
Maximum upload size in megabytes |
DOCUMENT_HANDLING |
extract_text |
extract_text, pass_raw, or skip |
MEDIA_ALLOWED_CONTENT_TYPES |
"" |
Comma-separated MIME allowlist for uploads. Empty means allow every type. Entries may be exact (image/png) or wildcard subtype (image/*). |
MEDIA_REQUIRE_OWNER |
Unset (on in production, off in development) | Deny access to files with no recorded owner (uploaded before ownership tracking was enabled, or while auth was disabled). An explicit true or false always wins. |
MEDIA_MAX_FILES_PER_USER |
0 |
Maximum number of stored files per user, checked on upload. 0 means no limit. Off by default; set a positive number to turn it on. With a quota on, every upload reads the metadata of each stored file. Needs a store that can list its files (memory and local); on the cloud store the quota is skipped and a warning is logged. |
MEDIA_MAX_USER_STORAGE_MB |
0 |
Maximum total storage per user in megabytes, checked on upload. 0 means no limit. Off by default; set a positive number to turn it on. Same cost and store requirement as MEDIA_MAX_FILES_PER_USER. |
MEDIA_MAX_IMAGE_PIXELS |
50000000 |
An image with more pixels than this is refused before it is stored. 0 means no limit. Needs Pillow; without it the check is skipped. |
MEDIA_MAX_PDF_MB |
10 |
A larger PDF is refused with 413 before text extraction. 0 means no limit. Applies while DOCUMENT_HANDLING=extract_text. |
MEDIA_MAX_PDF_PAGES |
500 |
A PDF with more pages is refused with 413 before text extraction. 0 means no limit. Applies while DOCUMENT_HANDLING=extract_text. |
MEDIA_INLINE_MAX_BYTES |
50000 |
Inline base64 media in a run request larger than this is moved into the media store and replaced by a reference. 0 turns this off. |
MEDIA_SWEEP_INTERVAL_SECONDS |
3600 |
Seconds between sweeps that delete files a crash left behind. Local store only. 0 turns the sweeper off. |
MEDIA_CLOUD_PROVIDER |
aws |
aws or gcp. Cloud storage only. |
MEDIA_CLOUD_BUCKET |
"" |
Bucket name |
MEDIA_CLOUD_REGION |
us-east-1 |
Bucket region |
MEDIA_CLOUD_PREFIX |
10xgraph-media |
Key prefix inside the bucket |
MEDIA_CLOUD_ACCESS_KEY_ID |
null |
AWS access key |
MEDIA_CLOUD_SECRET_ACCESS_KEY |
null |
AWS secret key |
MEDIA_CLOUD_SESSION_TOKEN |
null |
AWS session token |
MEDIA_CLOUD_PROJECT_ID |
null |
GCP project id |
MEDIA_CLOUD_CREDENTIALS_JSON |
null |
GCP service-account credentials JSON |
MEDIA_SIGNED_URL_TTL_SECONDS |
3600 |
Lifetime of a signed direct URL |
MEDIA_SIGNED_URL_REFRESH_BUFFER_SECONDS |
60 |
Re-sign this many seconds before expiry |
Document text extraction needs the extra: pip install "10xgraph-api[media]".
See Files and multimodal for how these fit together.
Request limits
| Variable | Default | Description |
|---|---|---|
MAX_REQUEST_SIZE |
10485760 (10MB) |
Maximum request body size in bytes |
MAX_NESTING_DEPTH |
64 |
Deepest nesting of objects and lists accepted in client messages (metadata, raw, content blocks), initial_state, config, resume and filters. Deeper input is refused with 422 before the graph runs. Allowed range 1 to 900 |
IDEMPOTENCY_TTL_SECONDS |
86400 |
How long a finished run is remembered under its Idempotency-Key. The header is opt-in. See idempotency keys. |
Client dicts and lists (config, initial_state, resume, metadata, filters) also have fixed structure caps (the nesting depth is MAX_NESTING_DEPTH above) that have no setting: 1000 keys per object, 10000 items per list and 200000 values in all. A larger body gets 422 VALIDATION_ERROR.
MAX_REQUEST_SIZE is enforced by HTTP middleware and applies to requests that declare a Content-Length. It does not cover WebSocket frames (bounded separately at 1 MiB per frame on /v1/graph/live) or chunked uploads (bounded by MEDIA_MAX_SIZE_MB as the body is read).
API path variables
| Variable | Default | Description |
|---|---|---|
ROOT_PATH |
/ |
Root path prefix (useful for reverse proxy sub-paths) |
DOCS_PATH |
/docs |
Swagger UI path (set to empty to disable) |
REDOCS_PATH |
/redocs |
ReDoc path (set to empty to disable) |
Server concurrency
| Variable | Default | Description |
|---|---|---|
WEB_CONCURRENCY |
Unset (2 in the generated Dockerfile) |
Number of Gunicorn workers. Gunicorn reads this variable natively; without it Gunicorn runs one worker. The Dockerfile from 10xgraph build sets ENV WEB_CONCURRENCY=2; override it at deploy time, for example docker run -e WEB_CONCURRENCY=8 .... |
Only Gunicorn reads this variable, for example when started as gunicorn -k uvicorn_worker.UvicornWorker tenxgraph_api.src.app.main:app. The development server (10xgraph dev) does not use it.
Shutdown
| Variable | Default | Description |
|---|---|---|
SHUTDOWN_GRACE_SECONDS |
10 |
Seconds the lifespan lets active runs finish on their own when it calls graph.aclose(). |
SHUTDOWN_STOP_SECONDS |
10 |
Seconds to wait after the stop request; each run saves its thread INTERRUPTED. |
SHUTDOWN_TIMEOUT_SECONDS |
30 |
Seconds for the hard cancel and the background drain. |
TENXGRAPH_GRACEFUL_SHUTDOWN_SECONDS |
540 |
Seconds the worker waits for open responses after SIGTERM before it cancels them. Read by TenxGraphUvicornWorker, the Gunicorn worker class of the generated image. A value that is not a positive integer falls back to 540. Keep it below the Gunicorn --graceful-timeout (600 in the generated image) so the lifespan shutdown can finish before the kill. Open NDJSON streams get a final “interrupted” chunk 5 seconds before this deadline. |
LLM provider variables
Set these based on the provider you use on your Agent. They are read at client creation time.
LLM timeout
| Variable | Default | Description |
|---|---|---|
TENXGRAPH_LLM_TIMEOUT |
600.0 |
Default request timeout in seconds applied to every LLM client. Must be a positive number. The deprecated AGENTFLOW_LLM_TIMEOUT is read only when this one is unset or empty. See Configure Agent for the programmatic API. |
OpenAI (provider="openai")
| Variable | Description |
|---|---|
OPENAI_API_KEY |
API key from https://platform.openai.com |
Google Gemini (provider="google")
The Google provider supports two backends: the Gemini API (default) and Vertex AI. See Google integration.
Gemini API (Google AI Studio):
| Variable | Description |
|---|---|
GEMINI_API_KEY |
API key from https://aistudio.google.com (preferred) |
GOOGLE_API_KEY |
Fallback name for the Gemini API key |
Vertex AI (enable with use_vertex_ai=True on the agent or GOOGLE_GENAI_USE_VERTEXAI=true):
| Variable | Default | Description |
|---|---|---|
GOOGLE_GENAI_USE_VERTEXAI |
unset | Set to true to route the Google provider through Vertex AI process-wide |
GOOGLE_CLOUD_PROJECT |
unset | Required. GCP project ID with the Vertex AI API enabled |
GOOGLE_CLOUD_LOCATION |
us-central1 |
GCP region for Vertex AI calls |
GOOGLE_APPLICATION_CREDENTIALS |
unset | Path to a service-account JSON key (Application Default Credentials) |
Anthropic (provider="anthropic" or provider="anthropic_vertex" or provider="anthropic_bedrock")
| Variable | Description |
|---|---|
ANTHROPIC_API_KEY |
API key from https://console.anthropic.com |
For Vertex AI models, see Anthropic integration.
CLI variables
These variables control how the 10xgraph command-line interface renders output: animation, the full-screen frame, and Unicode symbols. A flag is on when the value is 1, true, yes, or on (case-insensitive). There is no TENXGRAPH_THEME variable; the CLI theme is fixed.
| Variable | Default | Description |
|---|---|---|
TENXGRAPH_NO_SPINNER |
false |
Disable the animated spinner and other command animation. Set to 1, true, yes, or on to disable animation. Falls back to AGENTFLOW_NO_SPINNER if set. |
TENXGRAPH_FULLSCREEN |
false |
Opt in to the full-screen terminal frame (pinned header and footer, branded intro). Off by default: output goes to normal scrollback. Same as the --fullscreen flag. |
TENXGRAPH_NO_FULLSCREEN |
false |
Force the full-screen frame off even when TENXGRAPH_FULLSCREEN is set. Falls back to AGENTFLOW_NO_FULLSCREEN if set. |
TENXGRAPH_ASCII |
false |
Disable Unicode symbols in output; use ASCII equivalents instead. Set to 1, true, yes, or on for ASCII-only mode. Falls back to AGENTFLOW_ASCII if set. Useful in terminals with poor Unicode support. |
Each CLI variable has a deprecated AGENTFLOW_* equivalent that is used only when the TENXGRAPH_* name is not set. The AGENTFLOW_* names will be removed in 10xGraph 2.0.