Skip to main content

Installation

You can run architxt in two ways:

  • Docker Compose (recommended) — one command, includes optional Docling and Hindsight services.
  • Local development — run the backend and UI directly from source.

Choose Docker Compose if you just want to use architxt. Choose local development if you are modifying the code.

Requirements​

  • Docker Engine ≥ 24 and Docker Compose ≥ 2
  • OR Node.js ≥ 22 and npm 10+ for local development
  • Git

Docker Compose lets you start architxt together with everything it can use: a PDF/document parser (Docling) and a memory server (Hindsight).

1. Clone the repo​

git clone <your-architxt-repo>
cd architxt

2. Create your environment file​

Copy the example file:

cp server/.env.example server/.env

Edit server/.env with your LLM credentials. architxt supports multiple LLM providers; see Configuration for the full list and how to switch between them.

The quickest way to get started is with Ollama Cloud:

ARCHITXT_OLLAMA_CLOUD_API_KEY=your-ollama-cloud-key
HINDSIGHT_API_LLM_API_KEY=your-ollama-cloud-key-if-using-hindsight

Add the Hindsight key only if you are starting architxt with the hindsight Docker Compose profile.

3. Pick a profile​

architxt ships with three Docker Compose profiles. Pick the one that matches what you need.

ProfileWhat it startsUse this when...
(none)architxt + SQLiteYou only want the core app, no document parsing or memory.
doclingarchitxt + SQLite + DoclingYou want to upload and parse PDFs, Word docs, etc.
hindsightarchitxt + SQLite + Docling + HindsightYou want the full stack: documents + long-term memory.

Start a profile with:

# Core only
docker compose up --build -d

# Core + document parsing
docker compose --profile docling up --build -d

# Full stack
docker compose --profile hindsight up --build -d

The docling service is built from the included docling.Dockerfile, which pins the Docling versions that work well with architxt. The image is CPU-only by default. On first start the container downloads OCR/table models and warms up the pipeline; this can take 1–2 minutes before the service reports healthy. Wait for Application startup complete in the Docling logs before uploading documents.

If you have another machine with a more powerful CPU or a GPU, you can run Docling there instead and point architxt at it. Set DOCLING_SERVICE_URL at Docker Compose interpolation time:

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

See Configuration: external Docling host for details.

Docling sync operations time out after 1200 seconds (20 minutes) by default. To change this, set DOCLING_SERVE_MAX_SYNC_WAIT before running compose. This is read by Docker Compose at interpolation time, not from server/.env.

DOCLING_SERVE_MAX_SYNC_WAIT=2400 \
  docker compose --profile hindsight up --build -d

4. Open the UI​

Once all services report healthy — especially Docling, which can take 1–2 minutes on first start — open:

http://localhost:3000

What gets created automatically​

When the containers start for the first time:

  • The SQLite database file at the path set by ARCHITXT_DB_PATH (default ./database/architxt.db).
  • All required tables and seed data.

If you use the hindsight profile and set these variables in server/.env:

ARCHITXT_HINDSIGHT_DEFAULT_URL=http://hindsight:8888
ARCHITXT_HINDSIGHT_DEFAULT_BANK=architxt

architxt also creates:

  1. A Hindsight server entry pointing to http://hindsight:8888.
  2. A Hindsight memory bank named architxt.

This means the full stack works after a single docker compose command. You only need to add your LLM credentials.

Option 2: Local development​

Use this if you are changing architxt's code.

Requirements​

  • Node.js ≥ 22
  • npm 10+
  • A Docling server if you want PDF parsing (see Prerequisites)
  • A Hindsight server URL and API token if you want memory

Clone and install​

git clone <your-architxt-repo>
cd architxt
npm run setup

npm run setup checks the Node version, installs dependencies in server/ and ui/, creates the required directories, copies server/.env.example to server/.env if it does not exist, and builds the UI.

Start the application​

npm run dev

This starts both the backend API and the frontend UI. Open http://localhost:3000 in your browser.

Verify the backend​

The API is available at http://localhost:3001 by default. Visit /api-docs to see the OpenAPI/Swagger UI.

Useful Docker Compose commands​

These commands work from the architxt project root.

View logs​

# All services
docker compose --profile hindsight logs -f

# Just architxt
docker compose --profile hindsight logs -f architxt

# Just Hindsight
docker compose --profile hindsight logs -f hindsight

# Just Docling
docker compose --profile hindsight logs -f docling

# With timestamps
docker compose --profile hindsight logs -f --timestamps architxt

Check service health​

docker compose --profile hindsight ps

Rebuild after code changes​

docker compose --profile hindsight up --build -d

Stop everything​

docker compose --profile hindsight down

To also remove the database and uploaded documents, add:

docker compose --profile hindsight down -v

⚠️ -v removes named volumes. This deletes Hindsight's embedded database and any data inside Docker volumes.

Reset only the architxt database​

To wipe just the SQLite database volume while keeping documents, logs, and optional Hindsight data:

docker compose --profile hindsight rm -s -f architxt
docker volume rm architxt-database
docker compose --profile hindsight up -d

This recreates architxt.db and re-runs seeding on the next start.

Common issues​

"optional dependency failed to start"​

If you see a warning like:

optional dependency "hindsight" failed to start: container architxt-hindsight is unhealthy

it means Docker Compose thinks Hindsight is not healthy. First, check the Hindsight logs:

docker compose --profile hindsight logs -f hindsight

If Hindsight is actually running and printing ✅ Hindsight is running!, the healthcheck command may not be working in your image. Make sure you are using an image that includes the healthcheck endpoint on port 8888.

First start takes a long time​

Docling downloads machine-learning models on first boot. This can take 2–5 minutes depending on your internet connection. architxt now starts before Docling is fully ready, so the UI is available sooner; document parsing will work once Docling finishes.

ImportError: libxcb.so.1 on Docling startup​

If Docling crashes during startup with:

ImportError: libxcb.so.1: cannot open shared object file: No such file or directory

it is using a cached image built before the opencv-python-headless fix. Rebuild the Docling image with --no-cache:

docker compose --profile hindsight down docling
docker compose --profile hindsight build --no-cache docling
docker compose --profile hindsight up -d docling

Wait for Application startup complete before uploading documents.

Hindsight bank is not created​

Check that these variables are set in server/.env, not just in your shell:

cat server/.env | grep ARCHITXT_HINDSIGHT

Expected output:

ARCHITXT_HINDSIGHT_DEFAULT_URL=http://hindsight:8888
ARCHITXT_HINDSIGHT_DEFAULT_BANK=architxt

Then check the architxt seed logs:

docker compose --profile hindsight logs architxt | grep -i "hindsight-seed\|default Hindsight"

If the bank creation still fails, make sure Hindsight itself is healthy and that you have set HINDSIGHT_API_LLM_API_KEY in server/.env.

I changed server code and nothing happened​

Code changes inside server/ or ui/ are baked into the Docker image. You must rebuild:

docker compose --profile hindsight up --build -d

env_file values are ignored​

If variables in server/.env seem to have no effect, make sure you did not set the same variable in a docker-compose.yml environment: block with an empty default. Empty values in environment: override env_file values. architxt does not set empty defaults for Hindsight seed variables.

Next steps​