Install AI Gateway

Install the latest stable AI Gateway binary or run the published container. No account is required.

Documentation is versioned by major release (v1). The latest download and image tags follow the newest stable v1 release. Record the version reported by runku-ai version and pin that exact release in production.

Binary installation

Linux x86-64

curl --fail --location --output runku-ai.tar.gz \
  https://downloads.runku.dev/latest/runku-ai_linux_amd64.tar.gz
curl --fail --location --output checksums.txt \
  https://downloads.runku.dev/latest/checksums.txt
grep " runku-ai_linux_amd64.tar.gz$" checksums.txt | sha256sum --check
tar -xzf runku-ai.tar.gz
sudo install -m 0755 runku-ai /usr/local/bin/runku-ai
runku-ai version

macOS Apple silicon

curl --fail --location --output runku-ai.tar.gz \
  https://downloads.runku.dev/latest/runku-ai_darwin_arm64.tar.gz
curl --fail --location --output checksums.txt \
  https://downloads.runku.dev/latest/checksums.txt
grep " runku-ai_darwin_arm64.tar.gz$" checksums.txt | shasum -a 256 --check
tar -xzf runku-ai.tar.gz
sudo install -m 0755 runku-ai /usr/local/bin/runku-ai
runku-ai version

Windows x86-64

Run PowerShell as Administrator:

$BaseUrl = "https://downloads.runku.dev/latest"
Invoke-WebRequest "$BaseUrl/runku-ai_windows_amd64.zip" -OutFile runku-ai.zip
Invoke-WebRequest "$BaseUrl/checksums.txt" -OutFile checksums.txt
$Expected = ((Select-String " runku-ai_windows_amd64.zip$" checksums.txt).Line -split " ")[0]
$Actual = (Get-FileHash runku-ai.zip -Algorithm SHA256).Hash.ToLower()
if ($Actual -ne $Expected.ToLower()) { throw "Checksum verification failed" }
New-Item -ItemType Directory -Force "C:\Program Files\Runku" | Out-Null
Expand-Archive runku-ai.zip -DestinationPath "C:\Program Files\Runku" -Force
& "C:\Program Files\Runku\runku-ai.exe" version

Add C:\Program Files\Runku to the system PATH, then open a new terminal.

Direct downloads

SHA-256 checksums are published with every channel update. Production automation should use the immutable release URLs.

Configure and start the binary

For a production binary installation, configure a managed PostgreSQL database and expose its DSN as RUNKU_AI_STORE_DSN. Preserve the vault key separately.

Linux and macOS:

export RUNKU_AI_STORE_DSN='postgres://runku_ai:<password>@<host>:5432/runku_ai?sslmode=require'
export RUNKU_AI_MASTER_KEY='<64-hex-character-secret>'
runku-ai serve --config /etc/runku/config.ai.yaml

Windows PowerShell:

$env:RUNKU_AI_STORE_DSN = "postgres://runku_ai:<password>@<host>:5432/runku_ai?sslmode=require"
$env:RUNKU_AI_MASTER_KEY = "<64-hex-character-secret>"
runku-ai.exe serve --config "C:\ProgramData\Runku\config.ai.yaml"

Use store.driver: postgres and dsn: ${RUNKU_AI_STORE_DSN} in the YAML.

Docker Compose installation — recommended production mode

AI Gateway supports PostgreSQL for its product state. The following template uses PostgreSQL and is the recommended production starting point.

services:
  # Dedicated PostgreSQL database for AI Gateway's private operational store.
  postgres:
    # Pin an exact image version in controlled production environments.
    image: postgres:17-alpine
    # Restart after host or process failures unless explicitly stopped.
    restart: unless-stopped
    environment:
      # Database, login and secret used only by AI Gateway.
      POSTGRES_DB: runku_ai
      POSTGRES_USER: runku_ai
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?set POSTGRES_PASSWORD}
    volumes:
      # Persist providers, encrypted credentials, consumers and usage state.
      - postgres-data:/var/lib/postgresql/data
    healthcheck:
      # Wait until the private store accepts connections.
      test: ["CMD-SHELL", "pg_isready -U runku_ai -d runku_ai"]
      interval: 10s
      timeout: 5s
      retries: 10

  # Free self-hosted AI Gateway distribution.
  runku-ai:
    # `latest` tracks stable; pin an exact version for controlled upgrades.
    image: registry.runku.dev/runku-ai:latest
    restart: unless-stopped
    depends_on:
      postgres:
        # Start only after the private store is healthy.
        condition: service_healthy
    ports:
      # Host port : container port for API and portal traffic.
      - "8088:8088"
    environment:
      # Stable 32-byte key used to encrypt upstream provider secrets.
      RUNKU_AI_MASTER_KEY: ${RUNKU_AI_MASTER_KEY:?set RUNKU_AI_MASTER_KEY}
      # Private-store DSN; unrelated to LLM provider endpoints.
      RUNKU_AI_STORE_DSN: postgres://runku_ai:${POSTGRES_PASSWORD}@postgres:5432/runku_ai?sslmode=disable
    volumes:
      # Read-only bootstrap configuration.
      - ./config.ai.yaml:/etc/runku/config.ai.yaml:ro
    # Start the published gateway binary with the mounted configuration.
    command: ["serve", "--config", "/etc/runku/config.ai.yaml"]

volumes:
  # Named data survives container replacement and upgrades.
  postgres-data:

Use this store configuration in config.ai.yaml:

# Production store for AI Gateway's private operational state.
store:
  # PostgreSQL is recommended for production and multiple instances.
  driver: postgres
  # Dedicated DSN supplied as a secret through the environment.
  dsn: ${RUNKU_AI_STORE_DSN}

Generate the vault key once, store it in a secrets manager and place only the runtime value in .env:

openssl rand -hex 32
docker compose pull
docker compose up -d
docker compose exec runku-ai runku-ai version
docker compose exec runku-ai \
  runku-ai admin key create --config /etc/runku/config.ai.yaml --label bootstrap

For production, replace latest with the exact version printed above.

SQLite mode

SQLite is supported for evaluation and a small single-node installation. Set store.driver: sqlite, use a persistent path and back up the SQLite file. For production deployments, PostgreSQL is recommended.

Upgrade and rollback

1. Back up PostgreSQL and preserve RUNKU_AI_MASTER_KEY separately.
2. Download the newest stable binary or pull latest.
3. Record and pin the exact version before completing the maintenance window.
4. Verify health, provider access, quotas and a denied consumer request.
5. Restore the previous version and PostgreSQL backup if verification fails.

Continue with AI Gateway configuration.