Install the Sovereign Brain

Eight containers. One brain. Each container maps to a brain region — from memory to speech to reasoning. This guide takes you from a bare server to a fully operational sovereign AI.

1. Prerequisites

Hardware

No GPU required. All models are ONNX-optimized for CPU inference. GPU accelerates the generation brain but is not needed for search, translation, classification, or voice.

Software

• Ubuntu 22.04 LTS or any Linux with Docker 24+ and Docker Compose v2
• Ports 443 (HTTPS) and 8060 (admin) available on your LAN
• Pauhu license key (provided with your subscription — email sales@pauhu.eu)

What is NOT required

• No cloud accounts or API keys
• No external database servers — databases are embedded in the containers
• No configuration management tools (Ansible, Terraform) — Docker Compose handles everything
• No DNS — accessible on your LAN by IP address. DNS is optional for HTTPS with your own certificate.

2. Quickstart

From a clean server to a running brain in four commands. Allow 15 minutes on recommended hardware (10 minutes on NVMe with pre-bundled delivery).

# 1. Load the container images (from SFTP download or USB delivery)
docker load -i pauhu-sovereign-brain-v1.tar.gz

# 2. Create the data directory
mkdir -p /opt/pauhu/data

# 3. Start the brain
docker compose -f docker-compose1.yaml -f docker-compose-pauhu.yaml \
  --profile production --profile pauhu up -d

# 4. Verify all 8 containers are healthy
docker compose -f docker-compose1.yaml -f docker-compose-pauhu.yaml ps

Expected output after step 4:

NAME               STATUS    PORTS
pauhu-compass      healthy   8060/tcp
pauhu-fid          healthy   8050/tcp
pauhu-nmt          healthy   8080/tcp
pauhu-specialist   healthy   8070/tcp
pauhu-tts          healthy   8000/tcp
pauhu-gateway      healthy   8090/tcp
pauhu-mcp          healthy   3100/tcp
pauhu-llm-adapter  healthy   8001/tcp   (optional, sovereign-llm profile)

Open http://<your-server>:8090 to access the search interface. Navigate to /pauhu for the admin panel.

Quick verification

# Search for EU AI Act (via nginx reverse proxy)
curl -s http://localhost/api/compass?q=artificial+intelligence+regulation | head -20

# Translate to Finnish
curl -s -X POST http://localhost/api/translate \
  -H "Content-Type: application/json" \
  -d '{"text": "The regulation enters into force", "target": "fi"}'

# Ask a question (FiD grounded answer)
curl -s -X POST http://localhost/api/fid \
  -H "Content-Type: application/json" \
  -d '{"message": "Does the EU AI Act apply to procurement systems?"}'

# Check container health
curl -s http://localhost/health/compass
curl -s http://localhost/health/fid
curl -s http://localhost/health/translate

3. Brain mapping diagram

Each of the 8 containers maps to a region of the brain. This is not a metaphor — it is the actual system architecture. The Sovereign Brain page explains the neuroscience analogy in detail.

  LEFT HEMISPHERE (comprehension)          RIGHT HEMISPHERE (synthesis)
  ┌─────────────────────────┐              ┌─────────────────────────┐
  │                         │              │                         │
  │  pauhu-compass          │              │  pauhu-fid              │
  │  (Wernicke's area)      │              │  (right temporal lobe)  │
  │  Hybrid search,       │              │  Model-agnostic FiD,    │
  │  4.8M docs in 26ms      │              │  grounded answers       │
  │                         │              │                         │
  │  pauhu-specialist       │              │  pauhu-nmt              │
  │  (angular gyrus)        │              │  (right prosody)        │
  │  21 domain classifiers  │              │  552 language pairs     │
  │                         │              │                         │
  │                         │              │  pauhu-tts              │
  │                         │              │  (Broca's homologue)    │
  │                         │              │  Voice in 24 languages  │
  └────────────┬────────────┘              └────────────┬────────────┘
               │                                        │
               └──────────┐    ┌────────────────────────┘
                          │    │
                    ══════════════════
                    ║ pauhu-gateway  ║
                    ║   THALAMUS     ║
                    ║ (sensory relay)║
                    ══════════════════
                          │
          ┌───────┐       │       ┌──────────┐
          │Docker │       │       │ pauhu-mcp│
          │volumes│  HIPPOCAMPUS  │ (context)│
          │4.8M + │       │       │ IATE +   │
          │2.4M   │       │       │ EUR-Lex  │
          └───────┘       │       └──────────┘
                 ┌────────┴────────┐
                 │  CEREBELLUM     │
                 │  Deontic gate      │
                 │  cascade        │
                 │  (sequencing)   │
                 └────────┬────────┘
                          │
                 ┌────────┴────────┐
                 │   BRAINSTEM     │
                 │  Docker runtime │
                 └─────────────────┘

The 8 containers

Container resources

4. Model swap guide

All AI models in the Sovereign Brain are ONNX files stored in the data volume. You can swap any model without rebuilding containers.

Where models live

/opt/pauhu/data/models/
├── fid/                     # Generation brain (FiD mT5-base)
│   ├── encoder.onnx         # 580M parameter encoder, INT8 quantized
│   ├── decoder.onnx         # Decoder with cross-attention
│   ├── tokenizer.model      # 64K SentencePiece (32K base + 32K IATE)
│   └── manifest.json        # SHA-256 checksums
├── specialist/              # 21 domain classifiers
│   ├── law.onnx
│   ├── environment.onnx
│   ├── procurement.onnx
│   ├── ... (18 more)
│   └── manifest.json
├── nmt/                     # Translation models (552 pairs)
│   ├── en-fi.onnx
│   ├── fi-en.onnx
│   ├── en-de.onnx
│   ├── ... (549 more)
│   └── manifest.json
└── tts/                     # Voice models (24 languages)
    ├── en.onnx
    ├── fi.onnx
    ├── ... (22 more)
    └── manifest.json

Swap a model

# 1. Stop the container that uses the model
docker compose stop pauhu-fid

# 2. Replace the ONNX file
cp /path/to/new/encoder.onnx /opt/pauhu/data/models/fid/encoder.onnx
cp /path/to/new/decoder.onnx /opt/pauhu/data/models/fid/decoder.onnx

# 3. Update the manifest with new checksums
sha256sum /opt/pauhu/data/models/fid/*.onnx > /opt/pauhu/data/models/fid/manifest.json

# 4. Restart the container
docker compose start pauhu-fid

# 5. Verify the new model loads
curl -s http://localhost/health/fid | python3 -m json.tool

Swap a domain specialist

# Replace only the law domain model with a retrained version
docker compose stop pauhu-specialist
cp /path/to/law-v2.onnx /opt/pauhu/data/models/specialist/law.onnx
sha256sum /opt/pauhu/data/models/specialist/law.onnx >> /opt/pauhu/data/models/specialist/manifest.json
docker compose start pauhu-specialist

Add a new translation pair

# Add Irish (ga) ↔ English (en) model
cp ga-en.onnx /opt/pauhu/data/models/nmt/ga-en.onnx
cp en-ga.onnx /opt/pauhu/data/models/nmt/en-ga.onnx
docker compose restart pauhu-nmt

Bring your own LLM

The FiD container is model-agnostic — the retrieval-grounding-citation pattern is the product, the model is swappable. For an additional sovereign LLM (Llama, Mistral, Phi, ALLaM, SwissGPT), enable the pauhu-llm-adapter container:

# Enable the sovereign LLM profile
docker compose -f docker-compose1.yaml -f docker-compose-pauhu.yaml \
  --profile production --profile pauhu --profile sovereign-llm up -d

# Configure in .env:
MODEL_PROVIDER=onnx-local        # or: openai-compatible
MODEL_NAME=your-model-name
MODEL_PATH=/models/your-model    # volume-mounted

The gateway routes LLM requests through the same evidence bridge — the LLM receives only verified passages from the compass container, not raw user input. Three adapter patterns: OpenAI-compatible API, local ONNX model, or edge inference.

5. Admin panel

The admin panel (http://<your-server>/pauhu) is served by pauhu-gateway and provides a web interface for managing your Sovereign Brain installation.

Dashboard

The main dashboard shows real-time status of all 8 containers:

• Health status: green (healthy), yellow (degraded), red (down) for each container
• Resource usage: CPU, RAM, and disk for each container
• Query metrics: queries per minute, average response time, cache hit rate
• Data freshness: age of the most recent document in each of the 20 data sources

Query logs

Every query is logged locally with a SHA-256 audit hash. The admin panel lets you:

• Search query history by date range, user, or content
• View the complete audit trail for any query: which documents were retrieved, which passages crossed the bridge, and what the generation brain produced
• Export audit logs in JSON or CSV format for your compliance team

Container management

• Start/Stop: start or stop individual containers without affecting others
• Restart: restart a container (e.g., after a model swap)
• Logs: view real-time logs for any container
• Version: see the current model version and SHA-256 checksum for each container

Access control

The admin panel requires authentication. On first launch, it generates a random admin password and prints it to the container logs:

# View the initial admin password
docker compose logs pauhu-gateway | grep "Admin password"

# Change the admin password
curl -X POST http://localhost/pauhu/api/admin/password \
  -H "Authorization: Bearer <current-password>" \
  -H "Content-Type: application/json" \
  -d '{"new_password": "your-secure-password"}'

6. Feed subscriptions

The cloud version of Pauhu receives continuous updates from 20 EU institutional sources via 23 automated sync jobs. In a sovereign deployment, you control when and how data updates arrive.

Update methods

Configure automatic updates

# In /opt/pauhu/.env
PAUHU_LICENSE_KEY=your-license-key
PAUHU_UPDATE_ENDPOINT=https://staging.pauhu.eu/v1/sovereign
PAUHU_UPDATE_SCHEDULE=0 2 * * 1    # Weekly, Monday at 02:00
PAUHU_UPDATE_SOURCES=all            # Or: eurlex,ted,curia (comma-separated)

The compass container checks for updates on the schedule you define. It downloads only delta packages (new and modified documents), verifies SHA-256 checksums, and applies them to the local databases. The search indexes are rebuilt automatically.

Apply a manual update

# Transfer the update package to the server
scp pauhu-update-2026-03.tar.gz admin@your-server:/opt/pauhu/updates/

# Apply the update
docker exec pauhu-compass /update /updates/pauhu-update-2026-03.tar.gz

# Verify the update
docker exec pauhu-compass /health/data-freshness

Subscribe to specific sources

You can subscribe to all 20 sources or a subset. Configure in the admin panel under Settings → Feed Subscriptions, or via the .env file:

^* EPO patent data requires a separate Data Use Agreement with the European Patent Office. Contact sales@pauhu.eu for status.

7. VS Code extension

The Pauhu VS Code extension connects your IDE to the Sovereign Brain. It provides EU regulatory context, terminology lookup, and compliance checks directly in your editor — useful for policy drafting, legislative analysis, and procurement document preparation.

Install

# From the VS Code marketplace
code --install-extension pauhu.pauhu-eu

# Or from the .vsix file (air-gapped install)
code --install-extension /path/to/pauhu-eu-1.0.0.vsix

Configure

Open VS Code settings (Ctrl+,) and search for pauhu:

{
  "pauhu.serverUrl": "http://your-server",
  "pauhu.apiKey": "",
  "pauhu.language": "en",
  "pauhu.showTerminology": true,
  "pauhu.showClassification": true
}

Features

• IATE terminology lookup: Hover over a legal term to see its definition and translations in all 24 EU languages, drawn from 2.4 million verified entries
• Domain classification: The status bar shows which of the 21 EU policy domains your current document relates to
• Search panel: Ctrl+Shift+P → Pauhu: Search EU Sources to search 4.8M documents from inside your editor
• Chat panel: Ctrl+Shift+P → Pauhu: Ask a Question to get a grounded answer with citations
• Compliance check: Ctrl+Shift+P → Pauhu: Check Compliance to scan your current file for regulatory references and verify they are up to date
• Translate selection: Select text, right-click, Pauhu: Translate to... to translate using OPUS-MT models running on your server

8. Troubleshooting

Container won't start

# Check container logs
docker compose logs pauhu-compass --tail 50

# Check available disk space
df -h /opt/pauhu/data

# Check available memory
free -h

# Verify the container image is loaded
docker images | grep pauhu

Performance tuning

Verify data integrity

# Check all model manifests
docker exec pauhu-fid /verify-integrity
docker exec pauhu-specialist /verify-integrity
docker exec pauhu-nmt /verify-integrity
docker exec pauhu-tts /verify-integrity

# Check data integrity (document count, index status)
docker exec pauhu-compass /verify-integrity

# Full system health report
curl -s http://localhost/health/all | python3 -m json.tool

Reset to factory state

# Stop all containers
docker compose down

# Remove configuration (keeps models and data)
rm -rf /opt/pauhu/data/config /opt/pauhu/data/logs

# Restart
docker compose up -d

Get help

• Technical support: support@pauhu.eu
• On-site deployment: Available for EU government customers. Contact sales@pauhu.eu.
• Related documentation:

• Sovereign Brain — architecture overview and procurement specifications
• FiD Dual-Brain Architecture — technical deep-dive into the generation brain
• MCP Sovereign Mode — IDE integration protocol reference
• Government Procurement Demo — 10-step walkthrough
• The Guide vs. the Encyclopedia — why Pauhu exists