Self-Hosting the AI Engine

Run the AI engine alongside your Stirling PDF server. You need Docker Compose, a language model provider, an embedding provider, and a shared secret for the connection.

This setup uses the default hosted providers, Claude and VoyageAI. For GPT, another service or local models, see Model Providers. To use AI without hosting an engine, see Stirling Cloud AI.

Step 1: Configure the containers#

Add the engine service and AI settings to your Compose file. Keep any existing server volumes and configuration.

services:
  stirling-pdf:
    image: docker.stirlingpdf.com/stirlingtools/stirling-pdf:latest
    ports: ['8080:8080']
    environment:
      AIENGINE_ENABLED: 'true'
      AIENGINE_URL: 'http://stirling-pdf-engine:5001'
      STIRLING_ENGINE_SHARED_SECRET: 'replace-with-a-long-random-string'
  stirling-pdf-engine:
    image: ghcr.io/stirling-tools/stirling-engine:latest
    environment:
      STIRLING_ENGINE_SHARED_SECRET: 'replace-with-a-long-random-string'
      STIRLING_ENGINE_REQUIRE_AUTH: 'true'
      ANTHROPIC_API_KEY: 'your-anthropic-api-key'
      VOYAGE_API_KEY: 'your-voyageai-api-key'
    volumes: ['./stirling-engine-data:/app/engine/data']
    stop_grace_period: 30s

Replace the provider keys and set the same long, random shared secret on both services. Keep engine port 5001 private; no published port is needed. Pin matching release versions for production and upgrade both services together.

The engine volume stores document data and saved AI settings. Use a local directory or Docker volume.

If Stirling PDF does not run in the same Compose file, set aiEngine.enabled and aiEngine.url the way you configure the rest of the server; see the AI Settings Reference. The shared secret is always an environment variable.

Step 2: Start and verify#

1. Run docker compose up -d.
2. Check the engine with docker compose exec stirling-pdf-engine curl -fsS http://localhost:5001/health.
3. Sign in as an administrator and open Settings → Server → AI Engine. Run your own engine should be selected, and Status shows whether the engine is reachable.
4. Attach a PDF to the assistant and ask a question about it to verify document search.

Restart Stirling PDF after changing the engine URL or enabling AI. After rotating the shared secret, restart both services and re-save the AI settings.

Troubleshooting#

See AI Settings Reference for all settings and AI Security for network and provider access.