Prerequisites

Before you install architxt, make sure you have the runtime stack, document parsing service, at least one LLM provider, and an optional Hindsight server ready.

Runtime

architxt is a Node.js application with an Express backend, a Next.js frontend, and a SQLite database. You only need Node.js and npm to get started.

Requirement	Minimum	Notes
Node.js	22.0.0	Required for native ESM, fetch, and better-sqlite3 binary compatibility
npm	10.0.0	Bundled with Node.js 22+
git	2.30+	For cloning and updates

Verify your versions:

node --version   # Should print v22.x.x or higher
npm --version    # Should print 10.x.x or higher

If Node.js is too old, install via nvm:

nvm install 22
nvm use 22

Docling

The extract pipeline uses Docling to parse PDFs, Word documents, and images into structured markdown. architxt expects Docling to be running as a standalone server via docling serve.

This is optional if you only plan to upload plain text or images handled directly by the vision pipeline, but for most document workflows it is required. A GPU is recommended for Docling processing — CPU-only conversion is much slower and can become a bottleneck when batching large PDFs or slide decks.

Gotenberg

Gotenberg is an optional document-conversion service. When enabled, it converts .doc, .docx, .html, and .htm files to PDF before they are sent to Docling. This is useful when:

• Word documents contain embedded WMF/EMF vector diagrams that Docling does not render correctly.
• HTML files include inline or remote images that Docling reports as Image not available placeholders.

Gotenberg is not required. If it is unreachable, disabled, or returns an error, architxt falls back to sending the original Word or HTML file directly to Docling.

Install and start Gotenberg

The simplest way to run Gotenberg is with Docker:

docker run --rm -p 3031:3000 gotenberg/gotenberg:8

Gotenberg listens on port 3031 by default in architxt configurations to avoid colliding with the architxt UI dev server on port 3001 and other common local services.

Point architxt at the Gotenberg server

In server/.env:

ARCHITXT_GOTENBERG_URL=http://localhost:3031

Enable preprocessing

Two toggles control which formats are routed through Gotenberg:

# Convert Word documents to PDF before Docling (default: true)
ARCHITXT_CONVERT_DOC_DOCX_TO_PDF=true

# Convert HTML pages to PDF before Docling (default: true)
ARCHITXT_CONVERT_HTML_TO_PDF=true

Both default to true, so Gotenberg preprocessing is active as soon as ARCHITXT_GOTENBERG_URL points at a healthy server. Set either toggle to false to send that format directly to Docling instead.

Install and start Docling

# Requires Python 3.10–3.12
pip install docling docling-serve --extra-index-url https://download.pytorch.org/whl/cpu

# Default port is 5001
docling serve

The --extra-index-url installs the CPU-only PyTorch wheel, which is required for correct image extraction. Without it, embedded images may not be extracted properly.

Increase the Docling conversion timeout

docling serve has a default synchronous conversion timeout that may be too short for large PDFs or slide decks. Set DOCLING_SERVE_MAX_SYNC_WAIT when starting the server to extend it:

DOCLING_SERVE_MAX_SYNC_WAIT=240 docling serve

The value is in seconds. Use 240 (4 minutes) as a practical default for mixed document sizes, or increase it further for very large files.

When running under Docker Compose, this variable is set on the docling container automatically. See Installation for how to override it.

Point architxt at the Docling server

In server/.env:

DOCLING_SERVICE_URL=http://localhost:5001

Force OCR when needed

If your PDFs contain subsetted fonts without ToUnicode CMaps, extracted text may show glyph artifacts such as /g###/ tokens. Enable forced OCR to eliminate this corruption:

ARCHITXT_DOCLING_FORCE_OCR=true

This is slower but produces clean text from problematic PDFs.

LLM provider access

At least one LLM provider must be configured. architxt uses LLMs for denoising, vision analysis, research synthesis, and mental-model generation. The backend reads provider settings from server/.env and references each stage by a named provider, not by hard-coded URLs.

Supported provider types:

Provider	Required variables	Notes
Ollama Local	ARCHITXT_OLLAMA_LOCAL_URL	Self-hosted models on your machine. No API key needed.
Ollama Cloud	ARCHITXT_OLLAMA_CLOUD_API_KEY	Managed Ollama endpoint. Get a key from ollama.com.
OpenAI Compatible	ARCHITXT_OPENAI_API_KEY	OpenAI or any OpenAI-style API endpoint.
Anthropic	ARCHITXT_ANTHROPIC_API_KEY	Claude models via Anthropic's API.

The minimum environment block is:

# Local Ollama example — only a URL is required
ARCHITXT_OLLAMA_LOCAL_URL=http://localhost:11434

# Or add a cloud key
ARCHITXT_OLLAMA_CLOUD_API_KEY=your-key-here

Default models

Each provider has a default model that is used when a stage does not override it:

Provider	Default model	Variable
Ollama Local	qwen3.5:4b	ARCHITXT_OLLAMA_LOCAL_DEFAULT_MODEL
Ollama Cloud	kimi-k2.7-code:cloud	ARCHITXT_OLLAMA_CLOUD_DEFAULT_MODEL
OpenAI	gpt-4o	ARCHITXT_OPENAI_DEFAULT_MODEL
Anthropic	claude-3-sonnet-20240229	ARCHITXT_ANTHROPIC_DEFAULT_MODEL

Stage-specific model overrides

Some pipeline stages can use a different provider or model from the defaults. The most common overrides are:

Stage	Default provider	Default model	Variable
Vision / diagram description	ollama_cloud	gemma4:31b-cloud	ARCHITXT_VISION_MODEL
Document denoise (LLM)	ollama_cloud	gpt-oss:20b-cloud	ARCHITXT_DENOISE_LLM_MODEL

Set the matching *_PROVIDER and *_MODEL variables in server/.env if you want to route a specific stage elsewhere. The backend uses fail-fast config validation, so an invalid or missing required value exits immediately with a clear error.

Timeout defaults

Provider	Default timeout
Ollama Local	300 seconds
Ollama Cloud	300 seconds
OpenAI	60 seconds
Anthropic	180 seconds
Vision	300 seconds
Denoise LLM	600 seconds

Increase the matching ARCHITXT_*_TIMEOUT_MS variable if you process large documents or run on slower hardware.

Hindsight

Hindsight is a vector-memory server. architxt pushes documents, entity labels, mental models, and directives to a Hindsight bank, and pulls existing knowledge back into the working graph. It is a critical dependency for the full knowledge workflow: without it you can upload and inspect individual documents, but you cannot build contextual graphs, run mental models, or perform cross-document reasoning.

Hindsight is required for:

• Enterprise semantic search across documents.
• Cross-document reasoning and mental models.
• Contextual-graph sync and refresh.
• Evidence-backed synthesis with exact memory IDs.

What you need

Requirement	Purpose
Hindsight server URL	Base URL of the running Hindsight instance, e.g. http://localhost:8080
API token	Bearer token for authentication
Target bank	The bank that will hold your architxt corpus

You configure Hindsight as a server record inside architxt rather than in server/.env. After starting architxt, use Settings → Servers or the /api/v1/servers API to add:

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

Once a server is saved, you can select its banks from the Hindsight Sync page.

Recommended start models

When you configure a Hindsight bank for use with architxt, set the default models for retain and reflect operations to gpt-oss:120b-cloud. These operations handle ingestion and reasoning over your corpus, and the larger model gives more reliable extraction and synthesis.

Operation	Recommended model
Retain	gpt-oss:120b-cloud
Reflect	gpt-oss:120b-cloud

For detailed setup instructions, including how to install Hindsight and configure a bank, see the Hindsight install guide. It is also recommended to install the Hindsight Control Plane UI so you can inspect banks, memories, and operations outside of architxt.

Pre-install checklist

• Node.js 22+ and npm 10+ installed.
• Python 3.10–3.12 available if you plan to run Docling.
• Gotenberg installed and running on port 3031 if you want .doc/.docx/.html preprocessing.
• Docling installed and docling serve reachable on the URL you will set in server/.env.
• At least one LLM provider configured with a working endpoint or API key.
• Hindsight server running and ability to create your first bank.

Next steps

• Install architxt
• Configure environment variables