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:

JSON
{
  "agent": "graph.react:app",
  "env": ".env"
}

In .env:

Terminal
GOOGLE_API_KEY=your-key
JWT_SECRET_KEY=your-secret
MODE=production

At the process level

Terminal
MODE=production 10xgraph dev --no-reload

Application 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. RedisCacheStore shares 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_pool or redis) as the hot cache in front of Postgres; constructing it without one raises ValueError. It does not read REDIS_URL itself, so pass the URL to its constructor in your own code, for example redis_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.

Last updated for v1.0.0Edit this page on GitHubReport an issue