# 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

```bash
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

```bash
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:

```powershell
$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

| Platform | Architecture | Latest stable | Immutable v1.0.0 |
|---|---|---|---|
| Linux | x86-64 | [Download](https://downloads.runku.dev/latest/runku-ai_linux_amd64.tar.gz) | [Download](https://downloads.runku.dev/releases/v1.0.0/runku-ai_linux_amd64.tar.gz) |
| Linux | ARM64 | [Download](https://downloads.runku.dev/latest/runku-ai_linux_arm64.tar.gz) | [Download](https://downloads.runku.dev/releases/v1.0.0/runku-ai_linux_arm64.tar.gz) |
| macOS | Intel | [Download](https://downloads.runku.dev/latest/runku-ai_darwin_amd64.tar.gz) | [Download](https://downloads.runku.dev/releases/v1.0.0/runku-ai_darwin_amd64.tar.gz) |
| macOS | Apple silicon | [Download](https://downloads.runku.dev/latest/runku-ai_darwin_arm64.tar.gz) | [Download](https://downloads.runku.dev/releases/v1.0.0/runku-ai_darwin_arm64.tar.gz) |
| Windows | x86-64 | [Download](https://downloads.runku.dev/latest/runku-ai_windows_amd64.zip) | [Download](https://downloads.runku.dev/releases/v1.0.0/runku-ai_windows_amd64.zip) |

[SHA-256 checksums](https://downloads.runku.dev/latest/checksums.txt) 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:

```bash
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:

```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.

```yaml
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`:

```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`:

```bash
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](/docs/v1/ai-configuration).