# Grok config.yaml Configuration Options: Complete Reference for chenyme/grok2api

> Explore Grok config.yaml options for server, auth, database, and more. Get a complete reference for chenyme/grok2api configuration settings to optimize your setup.

- Repository: [Chenyme/grok2api](https://github.com/chenyme/grok2api)
- Tags: api-reference
- Published: 2026-08-09

---

**Grok's** [`config.yaml`](https://github.com/chenyme/grok2api/blob/main/config.yaml) **file defines 12 top-level configuration sections—including server bindings, authentication tokens, database drivers, and optional quality guard parameters—that are parsed by the configuration loader in** [`backend/internal/infra/config/config.go`](https://github.com/chenyme/grok2api/blob/main/backend/internal/infra/config/config.go).

The `chenyme/grok2api` repository uses a YAML-based configuration system centered on [`config.yaml`](https://github.com/chenyme/grok2api/blob/main/config.yaml), with a comprehensive example provided in [`config.example.yaml`](https://github.com/chenyme/grok2api/blob/main/config.example.yaml). This file controls everything from HTTP server timeouts to Redis clustering and audit ledger behavior, making it the single source of truth for deployment characteristics.

## Server Configuration Options

The `server` section in [`config.yaml`](https://github.com/chenyme/grok2api/blob/main/config.yaml) controls the HTTP listener and request handling limits.

- **`listen`**: Defines the bind address as `host:port`. Defaults to `127.0.0.1:8000`, though Docker deployments typically override this to `0.0.0.0:8000` ([lines 6-9](https://github.com/chenyme/grok2api/blob/main/config.example.yaml#L6-L9)).
- **`maxBodyBytes`**: Sets the maximum request body size in bytes, defaulting to 32 MiB ([line 10](https://github.com/chenyme/grok2api/blob/main/config.example.yaml#L10)).
- **`readTimeout`**: Maximum duration allowed for clients to upload the full request body, set to 15 minutes by default ([line 12](https://github.com/chenyme/grok2api/blob/main/config.example.yaml#L12)).
- **`requestTimeout`**: Upper bound for total non-streaming request lifetime, including processing time; defaults to 2 hours ([line 14](https://github.com/chenyme/grok2api/blob/main/config.example.yaml#L14)).
- **`swaggerEnabled`**: Boolean flag to expose the Swagger UI interface; defaults to `false` ([line 16](https://github.com/chenyme/grok2api/blob/main/config.example.yaml#L16)).

## Authentication and Security Settings

Security parameters are split across the `auth`, `secrets`, and `bootstrapAdmin` sections.

### Auth Parameters

- **`accessTokenTTL`**: Lifetime of issued access tokens; defaults to 15 minutes ([line 20](https://github.com/chenyme/grok2api/blob/main/config.example.yaml#L20)).
- **`refreshTokenTTL`**: Lifetime of refresh tokens; defaults to 720 hours (30 days) ([line 21](https://github.com/chenyme/grok2api/blob/main/config.example.yaml#L21)).
- **`secureCookies`**: Must be set to `true` when the service runs behind HTTPS ([line 23](https://github.com/chenyme/grok2api/blob/main/config.example.yaml#L23)).

### Secrets Management

- **`jwtSecret`**: HMAC secret for JWT signing; requires at least 32 characters ([line 27](https://github.com/chenyme/grok2api/blob/main/config.example.yaml#L27)).
- **`credentialEncryptionKey`**: Base64-encoded 32-byte key used to encrypt stored credentials at rest ([line 30](https://github.com/chenyme/grok2api/blob/main/config.example.yaml#L30)).

### Bootstrap Administrator

- **`username`** and **`password`**: Credentials for the initial admin account created only when no existing admin is detected in the database ([lines 34-36](https://github.com/chenyme/grok2api/blob/main/config.example.yaml#L34-L36)).

## Database and Storage Configuration

The `database` and `runtimeStore` sections define persistence layers for structured data and ephemeral state.

### Database Driver Options

- **`driver`**: Selects between `sqlite` for single-instance deployments or `postgres` for multi-instance setups ([line 44](https://github.com/chenyme/grok2api/blob/main/config.example.yaml#L44)).
- **`sqlite.path`**: Filesystem path for the SQLite database file, relative to the configuration file ([line 47](https://github.com/chenyme/grok2api/blob/main/config.example.yaml#L47)).
- **`postgres.dsn`**: PostgreSQL connection string; can be overridden via the `GROK2API_DATABASE_URL` environment variable ([line 51](https://github.com/chenyme/grok2api/blob/main/config.example.yaml#L51)).
- **`postgres.maxOpenConns`** and **`postgres.maxIdleConns`**: Connection pool limits for PostgreSQL ([lines 53-54](https://github.com/chenyme/grok2api/blob/main/config.example.yaml#L53-L54)).

### Runtime State Store

- **`driver`**: Choose `memory` for single-instance deployments or `redis` for clustered setups ([line 58](https://github.com/chenyme/grok2api/blob/main/config.example.yaml#L58)).
- **`redis.address`**: Redis server endpoint ([line 61](https://github.com/chenyme/grok2api/blob/main/config.example.yaml#L61)).
- **`redis.username`** and **`redis.password`**: Optional authentication credentials ([lines 62-63](https://github.com/chenyme/grok2api/blob/main/config.example.yaml#L62-L63)).
- **`redis.database`**: Redis DB index number ([line 64](https://github.com/chenyme/grok2api/blob/main/config.example.yaml#L64)).
- **`redis.keyPrefix`**: String prefix for all keys stored by Grok, useful when sharing a Redis instance ([line 66](https://github.com/chenyme/grok2api/blob/main/config.example.yaml#L66)).
- **`redis.tls`**: Enable TLS encryption for Redis connections ([line 68](https://github.com/chenyme/grok2api/blob/main/config.example.yaml#L68)).

## Deployment and Frontend Settings

### Deployment Scaling

- **`replicas`**: Number of service instances running; set to 1 for single-instance mode ([line 72](https://github.com/chenyme/grok2api/blob/main/config.example.yaml#L72)).
- **`instanceID`**: Stable unique identifier for each replica; required when `replicas > 1` ([line 74](https://github.com/chenyme/grok2api/blob/main/config.example.yaml#L74)).
- **`clusterID`**: Identifier shared across all replicas; required for multi-instance deployments ([line 76](https://github.com/chenyme/grok2api/blob/main/config.example.yaml#L76)).
- **`sharedMedia`**: Boolean indicating whether the media directory is shared across replicas ([line 78](https://github.com/chenyme/grok2api/blob/main/config.example.yaml#L78)).

### Frontend and Media

- **`frontend.staticPath`**: Path to built front-end assets served by the Go server ([line 40](https://github.com/chenyme/grok2api/blob/main/config.example.yaml#L40)).
- **`media.driver`**: Currently supports only `local` storage ([line 82](https://github.com/chenyme/grok2api/blob/main/config.example.yaml#L82)).
- **`media.local.path`**: Directory path for uploaded media files ([line 85](https://github.com/chenyme/grok2api/blob/main/config.example.yaml#L85)).

## Routing and Performance Tuning

The `routing` section optimizes connection handling and reasoning replay caching.

- **`reasoningReplayEnabled`**: Enables caching of encrypted reasoning content for multi-turn conversations ([line 89](https://github.com/chenyme/grok2api/blob/main/config.example.yaml#L89)).
- **`reasoningReplayTTL`**: Time-to-live for cached reasoning entries ([line 90](https://github.com/chenyme/grok2api/blob/main/config.example.yaml#L90)).
- **`reasoningReplayMaxEntries`**: Maximum cache size limit ([line 91](https://github.com/chenyme/grok2api/blob/main/config.example.yaml#L91)).
- **`accountIsolatedConnections`**: When `true`, each account maintains its own upstream connection pool ([line 93](https://github.com/chenyme/grok2api/blob/main/config.example.yaml#L93)).
- **`segmentedSelectorEnabled`**: Activates segmented selection for large account pools ([line 95](https://github.com/chenyme/grok2api/blob/main/config.example.yaml#L95)).
- **`segmentedSelectorMinCandidates`**: Minimum candidate threshold for segmentation ([line 96](https://github.com/chenyme/grok2api/blob/main/config.example.yaml#L96)).
- **`segmentedSelectorWindowSize`**: Window size parameter for the selector algorithm ([line 97](https://github.com/chenyme/grok2api/blob/main/config.example.yaml#L97)).

## Audit and Quality Guard Options

### Audit Ledger Configuration

- **`bufferSize`**: Internal audit buffer capacity in bytes ([line 101](https://github.com/chenyme/grok2api/blob/main/config.example.yaml#L101)).
- **`batchSize`**: Number of records per write batch ([line 102](https://github.com/chenyme/grok2api/blob/main/config.example.yaml#L102)).
- **`flushInterval`**: Duration between buffer flushes ([line 103](https://github.com/chenyme/grok2api/blob/main/config.example.yaml#L103)).
- **`commitDelay`**: Maximum wait time for commit operations ([line 105](https://github.com/chenyme/grok2api/blob/main/config.example.yaml#L105)).
- **`ledgerMode`**: Enforcement mode—`observe` for passive logging or `enforce` for active blocking ([line 107](https://github.com/chenyme/grok2api/blob/main/config.example.yaml#L107)).
- **`ledgerFailureThreshold`**: Consecutive failure count before pausing inference ([line 108](https://github.com/chenyme/grok2api/blob/main/config.example.yaml#L108)).
- **`ledgerUnhealthyGrace`**: Grace period before marking the ledger unhealthy ([line 109](https://github.com/chenyme/grok2api/blob/main/config.example.yaml#L109)).
- **`ledgerQueueHighWatermarkPercent`**: Queue capacity threshold percentage ([line 110](https://github.com/chenyme/grok2api/blob/main/config.example.yaml#L110)).

### Quality Guard Parameters (Optional)

The `qualityGuard` section provides side-car quality control for Grok Build deployments.

- **`enabled`**: Master switch for the quality guard ([line 115](https://github.com/chenyme/grok2api/blob/main/config.example.yaml#L15)).
- **`model`**: Model name used for quality checks (e.g., `grok-4.5`) ([line 117](https://github.com/chenyme/grok2api/blob/main/config.example.yaml#L17)).
- **`mode`**: Operating mode—`passive`, `active`, or `hybrid` ([line 118](https://github.com/chenyme/grok2api/blob/main/config.example.yaml#L18)).
- **`softTPS`** and **`hardTPS`**: Requests-per-second thresholds ([lines 121-122](https://github.com/chenyme/grok2api/blob/main/config.example.yaml#L21-L22)).
- **`consecutiveSoft`** and **`consecutiveErrors`**: Violation counters triggering protective actions ([lines 123-124](https://github.com/chenyme/grok2api/blob/main/config.example.yaml#L23-L24)).
- **`quarantineDuration`**: Duration nodes remain isolated after violations ([line 125](https://github.com/chenyme/grok2api/blob/main/config.example.yaml#L25)).
- **`minimumHealthyNodes`**: Required healthy node count to remain operational ([line 127](https://github.com/chenyme/grok2api/blob/main/config.example.yaml#L27)).
- **`failClosed`**: When `true`, rejects traffic on guard failures ([line 129](https://github.com/chenyme/grok2api/blob/main/config.example.yaml#L29)).
- **`rotationURL`**, **`rotationToken`**, **`rotationTimeout`**: Optional webhook configuration for IP rotation ([lines 131-134](https://github.com/chenyme/grok2api/blob/main/config.example.yaml#L31-L34)).

## Minimal Configuration Example

The following [`config.yaml`](https://github.com/chenyme/grok2api/blob/main/config.yaml) includes only the required sections for a single-instance SQLite deployment:

```yaml
server:
  listen: "0.0.0.0:8000"
  swaggerEnabled: true

auth:
  secureCookies: true

secrets:
  jwtSecret: "replace-with-at-least-32-characters"
  credentialEncryptionKey: "replace-with-base64-key"

bootstrapAdmin:
  username: "admin"
  password: "replace-with-a-strong-password"

database:
  driver: sqlite
  sqlite:
    path: "./data/backend.db"

runtimeStore:
  driver: memory

```

Optional sections such as `qualityGuard` or `audit` can be appended to this base configuration as operational requirements dictate.

## Summary

- **Grok's configuration schema** is defined in [`config.yaml`](https://github.com/chenyme/grok2api/blob/main/config.yaml) and validated by [`backend/internal/infra/config/config.go`](https://github.com/chenyme/grok2api/blob/main/backend/internal/infra/config/config.go).
- **Core sections** include `server`, `auth`, `secrets`, `bootstrapAdmin`, `database`, and `runtimeStore`, which are required for basic operation.
- **Database flexibility** supports both `sqlite` for single-instance and `postgres` for distributed deployments, with similar flexibility for `runtimeStore` (`memory` vs `redis`).
- **Advanced features** like multi-turn reasoning replay caching, audit ledgers, and quality guard thresholds are controlled via the `routing`, `audit`, and optional `qualityGuard` sections.
- **All default values and available options** are documented in the repository's [`config.example.yaml`](https://github.com/chenyme/grok2api/blob/main/config.example.yaml) file.

## Frequently Asked Questions

### What is the default HTTP listen address in Grok's config.yaml?

By default, the `server.listen` option is set to `127.0.0.1:8000`. Docker-based deployments typically override this to `0.0.0.0:8000` to accept external connections.

### How do I configure Grok for a multi-instance deployment with PostgreSQL?

Set `database.driver` to `postgres` and provide a valid DSN in `database.postgres.dsn`. Additionally, configure `runtimeStore.driver` as `redis` with appropriate connection parameters, and ensure each replica has a unique `deployment.instanceID` with a shared `deployment.clusterID`.

### What are the minimum required secrets for Grok to start?

You must provide `secrets.jwtSecret` (minimum 32 characters) and `secrets.credentialEncryptionKey` (Base64-encoded 32-byte key). Without these, the authentication and encryption systems in [`backend/internal/infra/config/config.go`](https://github.com/chenyme/grok2api/blob/main/backend/internal/infra/config/config.go) will fail validation.

### How does the reasoning replay feature work in the routing configuration?

When `routing.reasoningReplayEnabled` is `true`, Grok caches encrypted reasoning content to support multi-turn conversations. You can control the cache lifetime with `reasoningReplayTTL` and limit memory usage with `reasoningReplayMaxEntries`.