10xgraph.json configuration reference

In shortEvery key the 10xgraph.json config file accepts, with defaults, types, purposes, and complete examples for rate limiting, auth, and servers.

  • 16 min read
  • 12 sections
  • Updated
  • v1.0.0
  • Markdown

10xgraph.json is the configuration file for the 10xGraph API server and CLI. It specifies which graph to serve, how to authenticate, where state lives, and server behavior. Only the agent key is required; every other key is optional. The file is plain JSON. Edit it by hand or with 10xgraph config (a browser editor).

Projects created before the rename to 10xGraph use agentflow.json. It still works until 2.0: the CLI and the server read it when 10xgraph.json is missing from the same directory. The keys are identical, so migration is a rename (mv agentflow.json 10xgraph.json) or a save from 10xgraph config.

Which keys does it accept?

Key Type Default Purpose
agent string required Compiled graph as module:attribute, for example graph.agent:app
env string none Dotenv file to load before the graph starts, for example .env
auth string, object or null null Authentication: "jwt", or {"method": "custom", "path": "module:Class"}
authorization removed none Refused at startup. Use auth.roles and auth.method: custom. See auth
injectq string or null none Import path of an InjectQ container
store string or null none Import path of a BaseStore for long-term memory
store_allow_tenant_mismatch boolean false Boot even when the store declares different tenant columns than the checkpointer (production refuses otherwise). Use for a store that holds only shared data. See Multi-tenant data
checkpointer string or null none Not applied by the API server. If set, the server logs a warning and ignores it. Pass the checkpointer to compile()
thread_name_generator string or null none random, first_message, none or a module:attr path. See thread_name_generator
id_generator string or null graph’s own uuid, hex, short, int, bigint, timestamp, snowflake or a module:attr path. See id_generator
cache_store object or null in-memory One object that holds the cache store and what it backs: type, url, path, rate_limit, token_revocation. See cache_store
remote_tools array [] Schemas of tools that run in the client
runs object built-in defaults Who names threads, which client input reaches the graph, and run limits
websocket object built-in caps WebSocket connection limits
media object {"delete_with_thread": true} Uploaded-file lifecycle
ag_ui object disabled AG-UI protocol endpoint
observability object absent Logfire, LangSmith, Arize Phoenix and OTLP tracing
metrics object absent Request, task and LLM metrics for Prometheus or Grafana
audit object absent (off) Audit log of who accessed or changed what. See audit
test object absent Defaults for 10xgraph test
evaluation object absent Defaults for 10xgraph eval

Import paths use module:attribute. Unknown top-level keys are kept in the file but ignored, except redis, rate_limit and token_revocation: those do not exist at the top level and stop the load with an error that says they belong inside cache_store.

For what each key does when it is absent, and what 10xgraph init writes, see What is on by default.

thread_name_generator

Value Meaning
absent, null, "" or "none" Threads stay unnamed but are saved. This is the default
"random" A random name
"first_message" The user’s first message, whitespace collapsed, cut to at most 60 characters on a word boundary. A random name when the message has no text
"module:attr" A ThreadNameGenerator subclass or instance. It receives the user’s messages first, then the replies

The server saves every generated name in the background after the run.

id_generator

Value Meaning
absent The graph keeps the generator it was compiled with
"uuid", "hex", "short", "int", "bigint", "timestamp" The matching built-in generator
"snowflake" SnowFlakeIdGenerator. Needs the snowflakekit extra and reads the SNOWFLAKE_* environment variables
"module:attr" A BaseIDGenerator instance, subclass or zero-argument factory

The server binds the generator for the loaded graph, so new thread ids, message ids and memory ids all come from it. It refuses to boot when the graph code also sets a generator (StateGraph(id_generator=...)), and when a PgCheckpointer’s id_type cannot hold the ids the generator makes. Pick one place to set it. See Configure the ID generator.

cache_store

One object. The cache store holds the run locks and caps, idempotency state, token revocation and rate-limit counters.

Key Type Default Purpose
type string memory memory (per process), redis or custom. Absent cache_store or type is memory
url string empty Type redis only. Empty uses the REDIS_URL environment variable. A set value wins, as a literal or $VAR / ${VAR} (an unset variable is a config error), so the cache store can use a different Redis than the checkpointer. Valkey, Dragonfly and KeyDB work too
path string none Type custom only, required. module:attr of a BaseCacheStore instance or zero-argument factory. See Bring your own backend
rate_limit object absent (off) Request rate limiting. See rate_limit
token_revocation boolean or object false Refuse revoked tokens. true, or {"enabled": true, "token_lifetime": <seconds>, "user_ttl": <seconds>}. user_ttl defaults to 30 days; null keeps entries forever. Needs auth. A string value is a config error

REDIS_URL alone never selects Redis; only type: "redis" does. Type redis without the redis package refuses to boot (pip install "10xgraph-api[redis]"). Unknown keys inside cache_store are config errors that list the valid ones.

auth

Value Meaning
null or absent No authentication. Every request runs as anonymous, and the server logs a warning
"jwt" Verify bearer JWTs. Needs JWT_SECRET_KEY and JWT_ALGORITHM, and PyJWT (pip install "10xgraph-api[jwt]"). The string must be exactly jwt; any other string, such as JWT, is refused at startup
{"method": "custom", "path": "auth.agent_auth:AgentAuth"} Load a BaseAuth subclass. Both method and path are required

See Server authentication for the full guide.

Role-based access keys sit next to method and apply to any auth class. They are refused when auth is off.

Key Type Purpose
roles_claim string Token claim that lists the caller’s role names. Use this or permissions_claim, not both
permissions_claim string Token claim that lists permissions directly
tenant_claims array Token claims that name the caller’s tenant, for example ["org_id"]. They must match the tenant columns of the checkpointer and store
roles object Role name to {"permissions": [...], "reach": "own" | "tenant" | "all", "inherits": [...]}. reach is required on every role
default_role string Role for a token with no role claim
system_identities object Named identities for background jobs, each with roles and tenant

With "auth": "jwt" and no role keys, every authenticated caller gets the default permission set (everything except admin:*) and reach own. Permissions are resource:action strings from one registry: graph (read, invoke, stream, stop, fix), threads, store (read, write, delete), files (read, upload, delete), config:read, tasks (trigger, read, cancel) and admin (read, write). resource:* and * are wildcards. Reach says whose data a caller can read, list, delete and stop: own, tenant or all. Runs and writes to state and messages always stay on the caller’s own threads, whatever the reach.

A top-level authorization key is refused at startup. Move its rules into auth.roles; see authentication and authorization.

runs

Key Type Default Purpose
runs.thread_ids "server" or "client" "server" Who may name a new thread. See below
runs.config_keys array of strings or null null (any key) Allow-list for the keys of a request’s config
runs.state_keys array of strings or null [] (no key) State keys a client may set in initial_state, PUT state and AG-UI state. Empty or unset: none
runs.max_concurrent_per_user integer or null 10 HTTP graph runs one verified user may have in flight at once
runs.timeout number or null 300 in production, no limit in development Longest a single graph run may take, in seconds
runs.max_parallel_tool_calls integer or null null (core decides) Tool calls one model turn may run at once
JSON
{
  "agent": "graph.react:app",
  "runs": {
    "thread_ids": "server",
    "config_keys": ["locale", "tenant_hint"],
    "state_keys": ["preferences"],
    "max_concurrent_per_user": 10,
    "timeout": 600,
    "max_parallel_tool_calls": 10
  }
}

thread_ids

With "server" (the default), a request may only name a thread that already exists. To start a new thread, omit thread_id from config, or send "new" over /v1/graph/ws. The server picks the id and returns it. Read it from meta.thread_id on invoke, or from thread_id on each stream chunk.

Naming an id that does not exist answers 404 on invoke, stream, /v1/graph/ws and the checkpointer write routes. It is the same 404 as for an id another user owns, so a caller cannot tell whether an id is taken.

AG-UI (POST /v1/ag-ui) and realtime (/v1/graph/live) follow the same setting. An AG-UI threadId or a live thread_id the server never issued is refused (404 on AG-UI; on live an error event with code THREAD_NOT_FOUND and close code 1008). A blank or "new" id, or no id, makes the server create the thread: AG-UI returns it in RUN_STARTED, and live sends it in a session_started event. Frontends that make their own ids, such as CopilotKit by default, need "client".

With "client", any request may start a thread under an id it picks. With owner-only access the first user to write an id owns it. A user who claims a guessable id such as default first locks out its intended owner, and an unknown id answers differently from a taken one. Use "client" only if you accept that.

config_keys and state_keys

The two lists behave differently.

config_keys is open by default. When set, a request whose config carries any key not on the list is rejected with 422. thread_id and run_id are always allowed. When the key is null or absent, any key passes except the ones the server owns, which it drops. Keys the server sets itself, such as ag_ui on the AG-UI endpoint and remote_tools, are added after this check, so you never list them, and a client cannot send them.

state_keys is closed by default, like remote_tools: only the keys you list may be set by a client, in initial_state, in PUT /v1/threads/{id}/state and in the AG-UI state field. When the key is null, [] or absent, a client can set none, and any other key answers 422 with a message that names the key and points here. context in PUT state is always allowed, because it has its own rules for messages. A client that sends no state needs no setting.

JSON
{
  "agent": "graph.react:app",
  "runs": { "state_keys": ["preferences", "selected_job_id"] }
}

List only keys a client may be trusted with. A tool or node that trusts a value such as role or plan from state must not have that key on the list. current_node is a state key too: list it only if clients may start a run at a chosen node.

Upgrading from a version where an unset state_keys accepted any key: list every key your clients send, or their requests now get 422.

max_concurrent_per_user

Caps the HTTP graph runs (invoke, stream and AG-UI) one verified user may have in flight at once. The count is shared by all workers when a shared cache store is configured (cache_store.type redis or custom) and kept per process otherwise. Over the cap the request gets 429. 0 or null means no cap. Requests without a verified user (auth off) are not capped. The value must be a non-negative integer.

timeout

A run that passes the limit is cancelled. Invoke answers 504, and a stream, /v1/graph/ws run or AG-UI run ends with an error. The message reads Graph run passed the runs.timeout limit of 300s and was cancelled. Raise "runs.timeout" in 10xgraph.json to allow longer runs. An explicit number wins in either mode, and an explicit null means no limit. The key must be a positive number or null. Realtime sessions have no limit.

max_parallel_tool_calls

Caps how many tool calls one model turn may run at once. The server puts it into every run’s config, and clients cannot set it. When unset, core uses the TENXGRAPH_MAX_PARALLEL_TOOL_CALLS environment variable, or 10 if that is not set. The key must be a positive integer or null.

rate_limit

cache_store.rate_limit turns on rate limiting for REST requests. /ping is always excluded. Set "enabled": false to keep the block without enforcing it.

Key Type Default Purpose
enabled boolean true Turn limiting on or off
requests integer 100 Requests allowed per window. Must be above 0
window integer 60 Window length in seconds. Must be above 0
by string ip Count per ip, user or global
exclude_paths array [] Extra paths to skip
fail_open boolean true Allow requests when the cache store errors. false denies them with 503 RATE_LIMIT_UNAVAILABLE
trusted_proxy_headers boolean false Honour X-Forwarded-For. Only behind a proxy you control
trusted_proxy_hops integer 1 Proxies you control, counted from the right of X-Forwarded-For. At least 1
trusted_proxies array [] IPs or CIDR ranges your proxies connect from. Others cannot spoof the header

The counters live in the API’s cache store. With the in-memory store they count per process, so with N workers the real limit is requests times N and it resets on restart. Set cache_store.type to redis for any multi-worker deployment. Unknown keys inside rate_limit are config errors that list the valid ones.

websocket, ag_ui and observability

Key Type Default Purpose
websocket.max_connections integer or null 1000 Concurrent connections. Shared by all workers when a shared cache store is configured, per process otherwise. 0 or null means unlimited
websocket.max_connections_per_user integer or null 10 Per verified user. 0 or null means unlimited
websocket.realtime_models array of strings [] Models a /v1/graph/live client may request
ag_ui.enabled boolean false Mounts POST /v1/ag-ui. Needs the ag-ui extra
ag_ui.allow_client_tools boolean true Offer tools sent by the AG-UI client to the model

observability

The destinations below are AI tracing (observability) publishers. They receive graph, node, LLM and tool spans, AI errors included. Event publishers (Kafka, Redis, RabbitMQ, console) are not set in this file: you bind them in code, and they also receive task lifecycle events. Request, task and LLM numbers belong to metrics, which never goes through publishers. See Publishers, AI tracing and metrics.

Key Type Default Purpose
observability.level string full spans, standard or full. full (default) sends prompts, completions, tool I/O and graph state to the trace backend and may record PII. standard drops prompts, completions and tool I/O but keeps graph state on node spans. spans is timing and structure only. If the graph already has an observability publisher, the server reuses it and ignores this block, level included
observability.user_id_mode string raw How traces carry the user id: raw, hash or mask. See Hide the user id in traces
observability.logfire object none Keys include enabled, service_name, send_to_logfire, console
observability.langsmith object none Keys include enabled, project, endpoint
observability.otlp.enabled boolean false Send AI traces to any OTLP HTTP endpoint. See Send traces to an OTLP endpoint
observability.otlp.endpoint string or null null OTLP HTTP base URL, /v1/traces appended. With null, OTEL_EXPORTER_OTLP_TRACES_ENDPOINT must be set
observability.otlp.use_metrics_endpoint boolean false Use the metrics OTLP endpoint (metrics.otlp.endpoint, else the standard OTLP env variables) as the trace endpoint. Needs metrics enabled with export: "otlp"
observability.phoenix object none Keys include enabled, project, endpoint. See Send traces to Arize Phoenix

OTLP auth headers come from OTEL_EXPORTER_OTLP_HEADERS in the environment. Tokens stay in the environment: LOGFIRE_TOKEN, LANGSMITH_API_KEY and PHOENIX_API_KEY are never read from the file. Phoenix also reads PHOENIX_COLLECTOR_ENDPOINT and PHOENIX_PROJECT (or PHOENIX_PROJECT_NAME) when endpoint or project is not set. With user_id_mode set to hash, TENXGRAPH_TRACE_USER_ID_KEY (also from the environment) makes the hash keyed. See What is in your traces and events.

metrics

Off by default. See Metrics with Prometheus and Grafana.

Key Type Default Purpose
metrics.enabled boolean false Turn metrics on
metrics.export string none otlp (push) or prometheus (scrape). Required when enabled is true
metrics.otlp.endpoint string or null null OTLP HTTP base URL, /v1/metrics appended. Required for otlp unless OTEL_EXPORTER_OTLP_METRICS_ENDPOINT is set
metrics.prometheus.path string /metrics API scrape route. Needs no auth and skips the trusted-host check
metrics.prometheus.worker_port integer 9464 Port of the worker’s scrape server
metrics.latency_buckets_ms array of numbers 50, 100, 250, 500, 1000, 2500, 5000, 10000, 30000, 60000, 120000 Duration histogram buckets in milliseconds. Positive and strictly ascending

Needs pip install '10xgraph-api[metrics]'. Auth headers come from OTEL_EXPORTER_OTLP_HEADERS, never from the file. OTEL_SERVICE_NAME sets the service name.

audit

Off unless set. One JSON line per event with ids and results only: no prompts, answers, message text, file contents or tokens. 10xGraph stores nothing; your log pipeline collects and retains the lines. See Audit log.

Key Type Default Purpose
audit.enabled boolean false Turn the audit log on. The Full setup writes true
audit.sinks array of strings ["log"] "log" writes JSON lines to the tenxgraph_api.audit logger on stdout. "publisher" also sends events through the configured publisher (best effort). "module:Class" loads a BaseAuditSink subclass
audit.include_reads boolean true false keeps denials, auth failures and changes, and drops allowed reads and invokes to cut volume

Unknown keys inside audit are config errors. With auth off, events carry user_id: null and the server warns at boot.

media

Key Type Default Purpose
media.delete_with_thread boolean true Delete an uploaded file when the last message or thread that references it is deleted. false keeps recording links but never deletes a file automatically

Files uploaded before link tracking existed are never deleted automatically, whatever this is set to. See Delete a file and file lifecycle. The setting is also in 10xgraph config.

remote_tools

Each entry declares a tool the model can call that runs in the client. Unknown fields are rejected and tool names must be unique.

Key Type Required Purpose
node string yes Graph node the tool belongs to
name string yes Tool name
description string yes Description shown to the model
parameters object no JSON Schema with type: "object". Defaults to no properties

test and evaluation

Key Type Default Purpose
test.path string pytest discovery Test directory or file
test.coverage boolean false Run with coverage
test.coverage_threshold integer none Fail below this percentage
evaluation.directory string evals Where eval files live
evaluation.output_dir string eval_reports Report directory
evaluation.threshold number none Minimum pass rate, 0 to 1
evaluation.parallel boolean false Run cases concurrently
evaluation.max_concurrency integer 4 Concurrent cases when parallel
evaluation.open_report boolean true Open the HTML report in the browser when 10xgraph eval ends

Environment variables

The server reads configuration from environment variables, which are listed in full in the environment variables reference. Common ones include MODE, JWT_SECRET_KEY, JWT_ALGORITHM, ORIGINS, MAX_REQUEST_SIZE, REDIS_URL, LOG_FORMAT (text or json), SENTRY_DSN, and OTEL/observability settings. Set them as process environment variables or in a .env file referenced by the env key in 10xgraph.json.

What does a complete config look like?

10xgraph.json
{
  "agent": "graph.agent:app",
  "env": ".env",
  "auth": "jwt",
  "injectq": "graph.agent:container",
  "store": null,
  "thread_name_generator": "first_message",
  "id_generator": "uuid",
  "cache_store": {
    "type": "redis",
    "rate_limit": {
      "enabled": true,
      "requests": 100,
      "window": 60,
      "by": "user",
      "trusted_proxy_headers": true,
      "trusted_proxy_hops": 1,
      "exclude_paths": ["/docs"],
      "fail_open": true
    },
    "token_revocation": true
  },
  "websocket": { "max_connections": 500, "max_connections_per_user": 5 },
  "ag_ui": { "enabled": false },
  "observability": { "level": "standard", "logfire": { "enabled": false } },
  "test": { "path": "tests", "coverage": true, "coverage_threshold": 80 },
  "evaluation": { "directory": "evals", "output_dir": "eval_reports", "threshold": 0.75 }
}

Frequently asked questions

Which key is required in 10xgraph.json?
Only agent, a string in module:attribute form that points at your compiled graph. Every other key is optional.
Where does the CLI look for the config file?
It searches the working directory and its parents for the path you pass with --config (default 10xgraph.json). With the default name, each directory is checked for 10xgraph.json first and the older agentflow.json second. Without a path, test and eval also try .agentflow.json and agentflow.config.json.
Does agentflow.json still work?
Yes, until 2.0. When 10xgraph.json is missing, the CLI and the server read agentflow.json from the same directory. Rename the file to 10xgraph.json when convenient; the keys are identical.
Last updated for v1.0.0Edit this page on GitHubReport an issue