Configuration

architxt reads all settings from server/.env. The file is copied from server/.env.example during npm run setup. Each section below maps to a block in server/src/config.js and lists the supported variables, their defaults, and what they control.

Server

Variable	Default	Purpose
ARCHITXT_PORT	3000	Backend HTTP port.
ARCHITXT_HOST	0.0.0.0	Backend bind host.
ARCHITXT_NODE_ENV	development	Runtime environment label. Can be any string; the backend does not enforce a fixed set.

UI dev server

These only apply when running npm run dev. In production the UI is served from ui/dist/.

Variable	Default	Purpose
ARCHITXT_UI_PORT	3001	Frontend dev-server port.
ARCHITXT_UI_HOST	0.0.0.0	Frontend dev-server bind host.
ARCHITXT_UI_API_BASE_URL	http://localhost:3000	URL the UI uses to reach the backend API.

Database

Variable	Default	Purpose
ARCHITXT_DB_PATH	./database/architxt.db	Path to the SQLite database file.
ARCHITXT_DB_TIMEOUT_MS	10000	SQLite busy-timeout in milliseconds.

SQLite is used via better-sqlite3. The schema is created automatically on first start.

Logging

Variable	Default	Purpose
ARCHITXT_LOG_LEVEL	debug	Winston log level (debug, info, warn, error).
ARCHITXT_LOG_DIR	./logs	Directory for rotating log files.

File storage

Variable	Default	Purpose
ARCHITXT_STORAGE_PATH	./documents	Directory where uploaded document files are stored.
ARCHITXT_TEMP_DIR	./tmp	Temporary directory used during extraction.
ARCHITXT_MAX_FILE_SIZE	104857600	Maximum upload size in bytes (default is 100 MB).

Docling

Variable	Default	Purpose
DOCLING_SERVICE_URL	http://localhost:5001	URL of the Docling docling serve instance.
ARCHITXT_DOCLING_FORCE_OCR	false	Force OCR on every page. Use this when PDFs contain subsetted fonts without ToUnicode CMaps, which produce /g###/ glyph artifacts.

See Prerequisites for Docling setup.

Using an external Docling host (for example a GPU machine)

The default Docker Compose stack builds a local Docling image that runs on CPU. If you have another machine with a GPU and the Docling server running there, you can point architxt at it instead of the local docling container.

1. Make sure the remote Docling server is reachable from the architxt host.
2. Override DOCLING_SERVICE_URL at Docker Compose interpolation time when you start the stack:

DOCLING_SERVICE_URL=http://192.168.1.205:5001 \
  docker compose --profile hindsight up -d

When you use sudo, the exported variable is not forwarded by default. Either run without sudo (if your user is in the docker group) or preserve the environment:

DOCLING_SERVICE_URL=http://192.168.1.205:5001 sudo -E docker compose --profile hindsight up -d

Note: The local docling container will still start because it is part of the hindsight profile, but architxt will send conversion requests to the external host instead. If you want to avoid the unused local container, start only the services you need:

DOCLING_SERVICE_URL=http://192.168.1.205:5001 \
  docker compose --profile hindsight up -d architxt hindsight

Verify the override was applied:

docker compose exec architxt printenv DOCLING_SERVICE_URL

Expected output:

http://192.168.1.205:5001

LLM providers

All provider settings are read from server/.env. The backend registers four named providers and each pipeline stage references one of them by name. At least one provider must be usable. There are no silent fallbacks: missing required values cause the server to exit with a clear error.

Ollama Local

Variable	Default	Purpose
ARCHITXT_OLLAMA_LOCAL_URL	http://localhost:11434	Base URL of your local Ollama instance.
ARCHITXT_OLLAMA_LOCAL_API_KEY	ollamaapikey	API key. Ollama Local usually does not require a real key. Set in .env if you use one.
ARCHITXT_OLLAMA_LOCAL_DEFAULT_MODEL	qwen3.5:4b	Default model when this provider is selected.
ARCHITXT_OLLAMA_LOCAL_TIMEOUT_MS	300000	Request timeout in milliseconds (5 minutes).
ARCHITXT_OLLAMA_LOCAL_CHAT_STYLE	ollama_local	Chat adapter style (ollama_local or openai).

Ollama Cloud

Variable	Default	Purpose
ARCHITXT_OLLAMA_CLOUD_URL	https://ollama.com/v1	Managed Ollama endpoint URL.
ARCHITXT_OLLAMA_CLOUD_API_KEY	(empty)	Your Ollama Cloud API key. Set in .env.
ARCHITXT_OLLAMA_CLOUD_DEFAULT_MODEL	kimi-k2.7-code:cloud	Default model when this provider is selected.
ARCHITXT_OLLAMA_CLOUD_TIMEOUT_MS	300000	Request timeout in milliseconds.
ARCHITXT_OLLAMA_CLOUD_CHAT_STYLE	openai	Chat adapter style.

OpenAI Compatible

Variable	Default	Purpose
ARCHITXT_OPENAI_URL	https://api.openai.com/v1	OpenAI or OpenAI-compatible base URL.
ARCHITXT_OPENAI_API_KEY	(empty)	Your API key. Set in .env.
ARCHITXT_OPENAI_DEFAULT_MODEL	gpt-4o	Default model when this provider is selected.
ARCHITXT_OPENAI_TIMEOUT_MS	60000	Request timeout in milliseconds.
ARCHITXT_OPENAI_CHAT_STYLE	openai	Chat adapter style.

Anthropic

Variable	Default	Purpose
ARCHITXT_ANTHROPIC_URL	https://api.anthropic.com/v1	Anthropic API base URL.
ARCHITXT_ANTHROPIC_API_KEY	(empty)	Your Anthropic API key. Set in .env.
ARCHITXT_ANTHROPIC_DEFAULT_MODEL	claude-3-sonnet-20240229	Default model when this provider is selected.
ARCHITXT_ANTHROPIC_TIMEOUT_MS	180000	Request timeout in milliseconds.
ARCHITXT_ANTHROPIC_CHAT_STYLE	openai	Chat adapter style.

Vision / diagram description

Variable	Default	Purpose
ARCHITXT_VISION_ENABLED	true	Run diagram and image analysis during extraction.
ARCHITXT_VISION_PROVIDER	ollama_cloud	Provider name for vision calls.
ARCHITXT_VISION_MODEL	gemma4:31b-cloud	Model used for diagram/image description.
ARCHITXT_VISION_TIMEOUT_MS	300000	Request timeout in milliseconds.
ARCHITXT_VISION_PROMPT	(built-in)	Custom task prompt override.
ARCHITXT_VISION_SYSTEM_PROMPT	(built-in)	Custom system prompt override.
ARCHITXT_DIAGRAM_TEMPERATURE	0.0	Sampling temperature for diagram description.
ARCHITXT_DIAGRAM_BATCH_SIZE	2	Images per batch.
ARCHITXT_DIAGRAM_MAX_BATCHES	-1	Maximum batches to process (-1 for unlimited).
ARCHITXT_DIAGRAM_CONCURRENCY	3	Concurrent batches.

Diagram description prompts

You can override the built-in diagram-description prompts that are sent to the vision model. If a variable is left empty, architxt uses the default prompt.

Variable	Default	Purpose
ARCHITXT_VISION_PROMPT	(built-in)	Task prompt that describes how to extract systems, connections, and tables from diagrams.
ARCHITXT_VISION_SYSTEM_PROMPT	(built-in)	System prompt that sets the assistant role for image analysis.

Document denoise (LLM)

Variable	Default	Purpose
ARCHITXT_DENOISE_LLM_ENABLED	true	Use an LLM to clean spacing and glyph artifacts in extracted text.
ARCHITXT_DENOISE_LLM_PROVIDER	ollama_cloud	Provider name for denoise calls.
ARCHITXT_DENOISE_LLM_MODEL	gpt-oss:20b-cloud	Model used for LLM denoising.
ARCHITXT_DENOISE_LLM_TIMEOUT_MS	600000	Request timeout in milliseconds (10 minutes).
ARCHITXT_DENOISE_LLM_PROMPT	(built-in)	Custom task prompt override.
ARCHITXT_DENOISE_LLM_SYSTEM_PROMPT	(built-in)	Custom system prompt override.
ARCHITXT_DENOISE_LLM_TEMPERATURE	0.1	Sampling temperature.

Document denoise prompts

You can override the built-in LLM denoising prompts. If a variable is left empty, architxt uses the default prompt.

Variable	Default	Purpose
ARCHITXT_DENOISE_LLM_PROMPT	(built-in)	Task prompt that tells the model how to fix intra-word spacing and copy tables/images verbatim.
ARCHITXT_DENOISE_LLM_SYSTEM_PROMPT	(built-in)	System prompt that sets the assistant role for text cleanup.

Document denoise (basic cleanup)

These toggles are independent of the LLM denoiser and run rule-based cleanup on every extraction.

Variable	Default	Purpose
ARCHITXT_DENOISE_ENABLED	true	Run basic text cleanup.
ARCHITXT_DENOISE_REMOVE_PAGE_NUMBERS	true	Strip page numbers.
ARCHITXT_DENOISE_REMOVE_CONFIDENTIAL	true	Strip confidential headers.
ARCHITXT_DENOISE_REMOVE_DOC_IDS	true	Strip internal document IDs.
ARCHITXT_DENOISE_UNESCAPE_HTML	true	Unescape HTML entities.
ARCHITXT_DENOISE_UNESCAPE_MARKDOWN_PUNCT	true	Unescape Markdown punctuation.
ARCHITXT_DENOISE_NORMALIZE_WS	true	Collapse excessive whitespace.
ARCHITXT_DENOISE_REMOVE_NON_ASCII	true	Remove non-ASCII characters.
ARCHITXT_DENOISE_MAX_NEWLINES	3	Maximum consecutive newlines to keep.

Daemons

Variable	Default	Purpose
SPAWN_EXTRACT_DAEMON	true	Start the background document extraction worker.
SPAWN_HINDSIGHT_POLL_DAEMON	true	Start the background Hindsight operation poller.
ARCHITXT_EXTRACT_DAEMON_POLL_INTERVAL_MS	5000	How often the extract daemon polls for new uploads.
ARCHITXT_EXTRACT_DAEMON_ORPHAN_THRESHOLD_MINUTES	600	Minutes before a stuck extraction is considered orphaned.
ARCHITXT_HINDSIGHT_POLL_INTERVAL_MS	5000	How often the Hindsight poller checks pending operations.
ARCHITXT_HINDSIGHT_STALE_THRESHOLD_MS	300000	Milliseconds before a pending Hindsight operation is marked stale.

Workspace agent chat

These settings control the LLM used by the Workspace Chat panel when it classifies intent, recalls memories, and synthesizes answers.

Variable	Default	Purpose
ARCHITXT_AGENT_PROVIDER	ollama_cloud	Provider name for chat agent calls.
ARCHITXT_AGENT_API_KEY	(empty)	API key. Only needed if the selected provider requires one.
ARCHITXT_AGENT_BASE_URL	(empty)	Override the provider's base URL.
ARCHITXT_AGENT_MODEL	(provider default)	Model used for chat intent classification and synthesis.
ARCHITXT_AGENT_TEMPERATURE	0.7	Sampling temperature.
ARCHITXT_AGENT_TIMEOUT_MS	300000	Request timeout in milliseconds (5 minutes).
ARCHITXT_AGENT_CLASSIFY_INTENT_MAX_TOKENS	2048	Maximum tokens when the agent classifies the intent of a chat message. Reasoning models consume tokens before emitting JSON, so low limits can cause empty responses.

Contextual graph sync daemon

Variable	Default	Purpose
ARCHITXT_CONTEXTUAL_GRAPH_SYNC_DAEMON_ENABLED	false	Start the background contextual-graph sync daemon.
ARCHITXT_CONTEXTUAL_GRAPH_SYNC_DAEMON_POLL_INTERVAL_MS	60000	Poll interval for managed bank sync jobs.

Hindsight servers

In production or local development, Hindsight connections are added after starting architxt via Settings → Servers or the /api/v1/servers API:

• base_url — the Hindsight server URL.
• api_key — your API token.
• name — a readable label.

See Prerequisites for Hindsight setup and recommended bank models.

Docker Compose auto-seeding

When using the hindsight profile, architxt can automatically register a Hindsight server and create a memory bank on first boot. Set these variables in server/.env:

Variable	Default	Purpose
ARCHITXT_HINDSIGHT_DEFAULT_URL	(empty)	URL of the default Hindsight server to register. In the hindsight profile this is typically http://hindsight:8888.
ARCHITXT_HINDSIGHT_DEFAULT_BANK	(empty)	Name of the memory bank to create in the default Hindsight server, e.g. architxt.

When both are set:

1. architxt inserts a server record for ARCHITXT_HINDSIGHT_DEFAULT_URL if one does not already exist.
2. architxt calls PUT /v1/default/banks/{ARCHITXT_HINDSIGHT_DEFAULT_BANK} to create the bank.
3. The server and bank appear in the Hindsight page selectors.

This removes the manual server/bank setup step in Docker Compose. You still need to add Hindsight credentials in server/.env (see the Hindsight section in .env.example).

Next steps

• Install architxt
• Learn the AQL query language.