# Configuration

Distinguish application addresses, model services, internal credentials, persistent storage, and documentation settings, with explicit conditions for optional capabilities.

## Project runtime

The root .env.example provides addresses for running services directly on one host. Compose connects through container service names, and configuration classes may also default to container-network addresses. Set URLs for the actual launch mode; localhost examples are not container-to-container addresses. Browser access, internal services, and model providers use separate configuration.

| Setting | Purpose and current behavior |
| --- | --- |
| IGRAPH_ADMIN_USER_ID | Defaults to admin and selects the fixed workspace owner. The owner record is created automatically; no user provisioning is needed. Keep it unchanged on upgrades to reuse historical data |
| FRONTEND_BIND_ADDRESS / FRONTEND_PORT | Compose defaults to 127.0.0.1 / 21108; use an SSH tunnel or a controlled entry point remotely |
| AGENT_RUNTIME_AUTHORIZATION | false in the example; this runtime-framework authorization flag does not disable internal service keys or data-scope checks |
| BACKEND_PORT / AGENT_RUNTIME_PORT | Local examples use 21109 / 21112 for the public API and runtime |
| AGENT_RUNTIME_URL | Backend-to-runtime URL; local example http://127.0.0.1:21112, configuration default http://agent-runtime:21112 |
| GRAPH_ENGINE_URL | Backend-to-graph API URL; local example http://127.0.0.1:21111, final default http://graph-engine-api:21111 |
| GRAPH_ENGINE_MCP_URL | Runtime tool discovery and calls; local example http://127.0.0.1:21110/mcp, with MCP_SERVER_URL fallback |
| BACKEND_CONTROL_URL / GRAPH_ENGINE_API_URL | Internal execution-control addresses, not model provider URLs |
| AGENT_RUNTIME_DATABASE_URL | AgentOS PostgreSQL; local example host 127.0.0.1, configuration default host postgres |
| IGRAPH_CONTROL_SERVICE_KEY | Required for the complete deployment; Backend, runtime, graph API, and MCP share one random non-empty ASCII credential without whitespace, even when cancellation is disabled |
| IGRAPH_RUN_CANCEL_ENABLED | true in .env.example; false when unset. Cancellation is exposed through /api/capabilities only after consistent enablement and cross-service checks |
| VITE_API_BASE | Optional browser-facing Backend base URL; defaults to an empty string for same-origin /api and is read at frontend build time |
| VITE_SESSION_STATE_V2 | Enabled by default in the frontend; explicitly false disables the corresponding v2 state handling |
| BACKEND_STREAM_HEARTBEAT_SECONDS | Idle SSE heartbeat, default 15 seconds |
| AGENT_RUNTIME_JOB_POLL_INTERVAL_SECONDS / AGENT_RUNTIME_JOB_WAIT_TIMEOUT_SECONDS | Job polling defaults to 2 seconds; wait timeout defaults to 0 for no extra tool-layer limit, while upstream HTTP timeouts still apply |

The Vite development server listens on 21108 and proxies /api to http://127.0.0.1:21109. The Compose frontend uses its own reverse proxy. A VITE_API_BASE containing a container hostname unreachable from the browser causes request failures; keep the default empty value when using a same-origin proxy.

| Model and learning setting | Purpose and distinction |
| --- | --- |
| LLM_API_KEY / LLM_BASE_URL | Generic model credentials and OpenAI-compatible base URL; provider settings are resolved for the selected model |
| OPENAI_* / CLAUDE_* / ANTHROPIC_* / QWEN_* / DEEPSEEK_* / ARK_* | Provider connection settings; follow .env.example and the model protocol, or manage providers, credentials, and available models in Model services |
| IGRAPH_DEFAULT_MODEL | Runtime fallback model is qwen3.6-plus; GET /api/models reports the workspace default and available catalog |
| EMBEDDING_MODEL | Default text-embedding-3-small; used for reusable knowledge retrieval, not conversation |
| EMBEDDING_API_KEY / EMBEDDING_BASE_URL | Explicit embedding service settings; when unset, credentials and URL fall back through corresponding OPENAI, LLM, and QWEN variables |
| AGENT_RUNTIME_SKILLS_ROOT | Skills directory; defaults to IGRAPH_DATA_ROOT/agent_runtime/skills |
| AGENT_RUNTIME_TRACING / AGNO_TELEMETRY | Default true / false; runtime tracing and telemetry are separate switches |

Model services manages provider connections and the model catalog through /api/model-providers, /api/models, and /api/models/custom. URL and API Key fields open empty. Saving blank fields preserves the existing connection; new values replace it when saved, and removing a saved key requires the explicit clear action. Base URL is the provider endpoint, not the iGraph workspace URL. Embedding models still require provider support. Credentials belong in application configuration, never in the documentation site.

| Workspace setting | Purpose and current behavior |
| --- | --- |
| IGRAPH_DATA_ROOT / IGRAPH_WORKSPACE_ROOT | The data root defaults to data; session workspaces default to its workspaces subdirectory, with an optional explicit shared workspace root. Backend and runtime must access the same persistent storage. |
| IGRAPH_WORKSPACE_SANDBOX_MODE | Defaults to auto and requires working bubblewrap; startup checks fail when unavailable. fallback is an explicit local-development option and is disallowed in environments requiring a sandbox. |
| IGRAPH_WORKSPACE_EXEC_TIMEOUT_SECONDS / IGRAPH_WORKSPACE_OUTPUT_LIMIT | Workspace commands default to a 30-second timeout and a 100000-byte captured-output budget, separate from graph computation budgets. |

## Construction and computation

Graph Engine runs construction with separate model, budget, and experience configuration. Budget values below come from .env.example as deployment starting points; use the construction page and API of the same deployment for request options and limits. Relational construction can explicitly use a rules baseline, while text entity extraction requires a usable LLM service.

| Setting | Example / default behavior |
| --- | --- |
| GRAPH_CONSTRUCTION_MODE | Defaults to llm; missing model configuration fails explicitly, and rules must be selected explicitly |
| GRAPH_CONSTRUCTION_MODEL / GRAPH_CONSTRUCTION_API_KEY / GRAPH_CONSTRUCTION_BASE_URL | Optional construction-specific model and service settings, otherwise resolved from provider configuration |
| GRAPH_CONSTRUCTION_QUERY_COUNT / GRAPH_CONSTRUCTION_MAX_ITERATIONS | Examples 15 / 6 for query-set and iteration budgets |
| GRAPH_CONSTRUCTION_MAX_TOOL_CALLS / GRAPH_CONSTRUCTION_MAX_SECONDS | Examples 24 / 900 for tool-call and total-time budgets |
| GRAPH_CONSTRUCTION_BENCHMARK_REPEATS | Example 3 for benchmark repetitions |
| GRAPH_CONSTRUCTION_CONCURRENCY | Example 1 per Graph Engine process; one concurrent construction per user |
| GRAPH_CONSTRUCTION_EXPERIENCE_ENABLED / GRAPH_CONSTRUCTION_DOMAIN_CATEGORY | Default true / auto; reuse user-specific domain strategies and validate them against current data |
| GRAPH_COMPUTE_CONCURRENCY | Graph computation process pool; default min(4, cpu_count) |
| AGENT_TOOL_MAX_CONCURRENCY | Per-turn tool scheduling defaults to 4, clamped to 1–32; separate from the graph process pool |
| GRAPH_HEAVY_PER_USER_CONCURRENCY | Heavy tasks such as training and inference default to 1 per user |
| LLM_TIMEOUT_SECONDS | Example model request timeout of 180 seconds |
| MCP_ENABLE_REPORTING_TOOLS | Reporting tools enabled by default; false / off / 0 disables them |

A persistent deployment also needs durable PostgreSQL, Graph Engine data, skills, and session workspaces. Large-graph computation, NebulaGraph, upload quotas, and text extraction have their own settings. Check .env.example, graph-computation documentation, and the actual error instead of trying to resolve every capacity issue by increasing construction timeout.

Partitioned large graphs use durable jobs and workers, separately from the ordinary graph-algorithm process pool. LARGE_GRAPH_EMBEDDED_WORKER defaults to true for direct startup; Compose disables the embedded worker and starts a separate graph-engine-worker. Preparation converts supported text edge lists or triples into partitioned snapshots; not every binary graph format supports this preparation path.

| Large-graph and data-entry setting | Current default and purpose |
| --- | --- |
| LARGE_GRAPH_NODE_THRESHOLD / LARGE_GRAPH_EDGE_THRESHOLD | Default 1 million nodes / 5 million edges; reaching either activates the corresponding large-graph constraints |
| LARGE_GRAPH_UPLOAD_BYTES_THRESHOLD | Default 256 MiB; supported text uploads route to streaming large-graph preparation before a full read |
| LARGE_GRAPH_BINARY_UPLOAD_BYTES_THRESHOLD | Default 64 MiB; preflight limit for inputs such as npz / pt / json that cannot use partitioned preparation, avoiding full deserialization |
| LARGE_GRAPH_PARTITIONS | Example 16 for preparation and partitioned computation |
| LARGE_GRAPH_UPLOAD_MAX_BYTES / LARGE_GRAPH_USER_UPLOAD_QUOTA_BYTES | Graph data service defaults to 100 GiB per file and 200 GiB per user; these are not universal limits for every browser upload endpoint |
| IGRAPH_MAX_UPLOAD_BYTES | Backend chat attachments default to 50 MiB, separately from graph-service large-file limits |
| BACKEND_SERVER_DATASETS_DIR | Server-provided dataset directory; defaults to server_datasets under the data root and may be mapped to persistent storage in Compose |
| BACKEND_SERVER_DATASET_PREPROCESS_MIN_BYTES / BACKEND_SERVER_DATASET_SCAN_SECONDS | Text edge-list preprocessing threshold defaults to 64 MiB, with a 30-second scan interval; threshold 0 enables preprocessing for all text edge lists |

- [Graph Engine and large-graph execution](/en/graph-engine/): Understand preparation, partitioned snapshots, workers, and algorithm boundaries; see .env.example for the complete configuration list.

The construction panel lets you select a model or enter a custom model ID and save a separate URL and API key for TXT extraction and AI-assisted table construction. GET /api/construction-models returns the list; GET / POST /api/construction-model-settings reads or saves the connection. Blank fields retain saved or server settings; an explicit clear action removes a saved key. In Compose, settings are stored by default in /data/configuration/construction-model.json, not in dataset options or construction reports.

Settings such as PER_USER and USER_UPLOAD_QUOTA still count by storage owner. In single-user mode these limits apply to the default workspace, without creating accounts or assigning login permissions.

## Documentation-site settings

The independent documentation site does not use model API keys, database connections, IGRAPH_CONTROL_SERVICE_KEY, or VITE_API_BASE. docs-site/wrangler.jsonc configures the site name, compatibility date, and dist asset directory. Optional SITE_URL generates absolute canonicals and a sitemap at build time and must be the actual documentation HTTPS origin without a path, query, or fragment. Cloudflare publishing credentials upload static files; they are not iGraph application credentials.