Deployment Guide

Run Pathfinder anywhere — single container, full stack, or bare metal.

Docker (single container, bash-only)

The quickest Docker setup. No database needed — agents explore docs with shell commands only.

$ docker run -d \
  -v ./pathfinder.yaml:/app/pathfinder.yaml:ro \
  -v ./docs:/app/docs:ro \
  -p 3001:3001 \
  ghcr.io/copilotkit/pathfinder:latest

This mounts your config and local docs into the container. Agents get read-only access to your documentation via bash tools.

Docker Compose (full stack)

For semantic search, you need Postgres with pgvector. The production docker-compose.yml sets up everything:

# docker-compose.yml
services:
  db:
    image: pgvector/pgvector:pg16
    environment:
      POSTGRES_DB: pathfinder
      POSTGRES_USER: pathfinder
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-changeme}
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U pathfinder"]
      interval: 5s
      timeout: 3s
      retries: 5

  app:
    image: ghcr.io/copilotkit/pathfinder:latest
    ports:
      - "${PORT:-3001}:${PORT:-3001}"
    environment:
      DATABASE_URL: postgres://pathfinder:${POSTGRES_PASSWORD:-changeme}@db:5432/pathfinder
      OPENAI_API_KEY: ${OPENAI_API_KEY}
      GITHUB_TOKEN: ${GITHUB_TOKEN:-}
      GITHUB_WEBHOOK_SECRET: ${GITHUB_WEBHOOK_SECRET:-}
      PATHFINDER_CONFIG: /app/pathfinder.yaml
      WORKSPACE_DIR: /data/workspaces
      PORT: ${PORT:-3001}
      NODE_ENV: production
    volumes:
      - ./pathfinder.yaml:/app/pathfinder.yaml:ro
      - workspaces:/data
    depends_on:
      db:
        condition: service_healthy

volumes:
  pgdata:
  workspaces:

Create a .env file with your secrets, then start:

$ docker compose up -d

Persistent volume required for workspaces

Without a persistent volume mounted at /data, agent workspaces are lost on every container restart. If you use workspaces, always mount a volume. The workspaces volume in the compose file above handles this.

Railway

Deploy to Railway with a Postgres plugin and persistent volume:

Create a new project on Railway and add a PostgreSQL database (use the pgvector template if available).
Add a new service from the Pathfinder GitHub repo or Docker image (ghcr.io/copilotkit/pathfinder:latest).
Set environment variables: DATABASE_URL (from Railway's Postgres), OPENAI_API_KEY, GITHUB_TOKEN (if needed).
Add a persistent volume mounted at /data for workspace storage.
Set WORKSPACE_DIR=/data/workspaces in the service environment.
Deploy. The first boot auto-indexes your configured sources.

Generic VPS

Run Pathfinder directly on any Linux server with Node.js 20+.

systemd service

# /etc/systemd/system/pathfinder.service
[Unit]
Description=Pathfinder MCP Server
After=network.target postgresql.service

[Service]
Type=simple
User=pathfinder
WorkingDirectory=/opt/pathfinder
ExecStart=/usr/bin/node dist/server.js
Environment=NODE_ENV=production
Environment=PORT=3001
Environment=DATABASE_URL=postgresql://pathfinder:secret@localhost:5432/pathfinder
Environment=OPENAI_API_KEY=sk-...
Environment=PATHFINDER_CONFIG=/opt/pathfinder/pathfinder.yaml
Environment=WORKSPACE_DIR=/var/lib/pathfinder/workspaces
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

nginx reverse proxy

# /etc/nginx/sites-available/pathfinder
server {
    listen 443 ssl http2;
    server_name docs.example.com;

    ssl_certificate /etc/letsencrypt/live/docs.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/docs.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:3001;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Environment Variables

Variable	Required	Default	Description
`DATABASE_URL`	For search tools	-	PostgreSQL connection string (with pgvector)
`OPENAI_API_KEY`	When embedding.provider is "openai" (default)	-	OpenAI API key for computing embeddings. Not needed for ollama or local providers.
`GITHUB_TOKEN`	For private repos	-	GitHub PAT for cloning private repositories
`GITHUB_WEBHOOK_SECRET`	For webhooks	-	Secret for validating GitHub webhook payloads
`SLACK_BOT_TOKEN`	When slack sources configured	-	Slack bot OAuth token (xoxb-...)
`SLACK_SIGNING_SECRET`	When using emoji-trigger	-	For Slack webhook signature verification
`DISCORD_BOT_TOKEN`	When discord sources configured	-	Discord bot token
`DISCORD_PUBLIC_KEY`	When discord sources configured	-	For Discord webhook Ed25519 verification
`NOTION_TOKEN`	When notion sources configured	-	Notion internal integration token
`PORT`	No	`3001`	HTTP port the server listens on
`PATHFINDER_CONFIG`	No	`pathfinder.yaml`	Path to the config file
`WORKSPACE_DIR`	No	`/tmp/pathfinder-workspaces`	Directory for agent workspace storage
`NODE_ENV`	No	`development`	Set to `production` for deployed instances
`LOG_LEVEL`	No	`info`	Logging verbosity (debug, info, warn, error)
`CLONE_DIR`	No	`/tmp/mcp-repos`	Directory for git repo clones
`ANALYTICS_TOKEN`	When analytics enabled	-	Bearer token for authenticating `/api/analytics/*` endpoints

Optional dependencies

Some features require extra packages that are not bundled by default. Install only the ones your config needs:

Package	When required	Install
`pdf-parse`	Any source has `type: document` with `*.pdf` file patterns	`npm install pdf-parse`
`mammoth`	Any source has `type: document` with `*.docx` file patterns	`npm install mammoth`
`@xenova/transformers`	`embedding.provider` is `local`	`npm install @xenova/transformers`

Run pathfinder validate to detect missing optional dependencies and get install instructions.

Health endpoint

Pathfinder exposes GET /health for monitoring. It returns JSON with uptime, indexing status, chunk counts per source, and index state (last indexed time, commit SHA, errors). Use it for load balancer health checks and deployment verification.

Webhook URLs

GitHub: Set your GitHub webhook's Payload URL to https://your-domain/webhooks/github.

Slack: Set your Slack app's Event Subscriptions Request URL to https://your-domain/webhooks/slack.

Discord: Set your Discord application's Interactions Endpoint URL to https://your-domain/webhooks/discord.

Volume Mounts

What you mount depends on your source configuration:

Local docs — If your source uses a path without a repo, you need to mount the docs directory into the container (e.g., -v ./docs:/app/docs:ro).
Git-backed sources — If your source specifies a repo, Pathfinder clones it automatically. No volume mount needed for the docs themselves.
Config file — Always mount your pathfinder.yaml (e.g., -v ./pathfinder.yaml:/app/pathfinder.yaml:ro).
Workspace persistence — If agents use writable workspaces (workspace: true in bash tools), mount a persistent volume at the WORKSPACE_DIR path. Without this, workspace files are lost on restart.
Database persistence — The Postgres data directory should always be on a persistent volume.