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

Grok's 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.

The chenyme/grok2api repository uses a YAML-based configuration system centered on config.yaml, with a comprehensive example provided in 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 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).
• maxBodyBytes: Sets the maximum request body size in bytes, defaulting to 32 MiB (line 10).
• readTimeout: Maximum duration allowed for clients to upload the full request body, set to 15 minutes by default (line 12).
• requestTimeout: Upper bound for total non-streaming request lifetime, including processing time; defaults to 2 hours (line 14).
• swaggerEnabled: Boolean flag to expose the Swagger UI interface; defaults to false (line 16).

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).
• refreshTokenTTL: Lifetime of refresh tokens; defaults to 720 hours (30 days) (line 21).
• secureCookies: Must be set to true when the service runs behind HTTPS (line 23).

Secrets Management

• jwtSecret: HMAC secret for JWT signing; requires at least 32 characters (line 27).
• credentialEncryptionKey: Base64-encoded 32-byte key used to encrypt stored credentials at rest (line 30).

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

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).
• sqlite.path: Filesystem path for the SQLite database file, relative to the configuration file (line 47).
• postgres.dsn: PostgreSQL connection string; can be overridden via the GROK2API_DATABASE_URL environment variable (line 51).
• postgres.maxOpenConns and postgres.maxIdleConns: Connection pool limits for PostgreSQL (lines 53-54).

Runtime State Store

• driver: Choose memory for single-instance deployments or redis for clustered setups (line 58).
• redis.address: Redis server endpoint (line 61).
• redis.username and redis.password: Optional authentication credentials (lines 62-63).
• redis.database: Redis DB index number (line 64).
• redis.keyPrefix: String prefix for all keys stored by Grok, useful when sharing a Redis instance (line 66).
• redis.tls: Enable TLS encryption for Redis connections (line 68).

Deployment and Frontend Settings

Deployment Scaling

• replicas: Number of service instances running; set to 1 for single-instance mode (line 72).
• instanceID: Stable unique identifier for each replica; required when replicas > 1 (line 74).
• clusterID: Identifier shared across all replicas; required for multi-instance deployments (line 76).
• sharedMedia: Boolean indicating whether the media directory is shared across replicas (line 78).

Frontend and Media

• frontend.staticPath: Path to built front-end assets served by the Go server (line 40).
• media.driver: Currently supports only local storage (line 82).
• media.local.path: Directory path for uploaded media files (line 85).

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).
• reasoningReplayTTL: Time-to-live for cached reasoning entries (line 90).
• reasoningReplayMaxEntries: Maximum cache size limit (line 91).
• accountIsolatedConnections: When true, each account maintains its own upstream connection pool (line 93).
• segmentedSelectorEnabled: Activates segmented selection for large account pools (line 95).
• segmentedSelectorMinCandidates: Minimum candidate threshold for segmentation (line 96).
• segmentedSelectorWindowSize: Window size parameter for the selector algorithm (line 97).

Audit and Quality Guard Options

Audit Ledger Configuration

• bufferSize: Internal audit buffer capacity in bytes (line 101).
• batchSize: Number of records per write batch (line 102).
• flushInterval: Duration between buffer flushes (line 103).
• commitDelay: Maximum wait time for commit operations (line 105).
• ledgerMode: Enforcement mode—observe for passive logging or enforce for active blocking (line 107).
• ledgerFailureThreshold: Consecutive failure count before pausing inference (line 108).
• ledgerUnhealthyGrace: Grace period before marking the ledger unhealthy (line 109).
• ledgerQueueHighWatermarkPercent: Queue capacity threshold percentage (line 110).

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).
• model: Model name used for quality checks (e.g., grok-4.5) (line 117).
• mode: Operating mode—passive, active, or hybrid (line 118).
• softTPS and hardTPS: Requests-per-second thresholds (lines 121-122).
• consecutiveSoft and consecutiveErrors: Violation counters triggering protective actions (lines 123-124).
• quarantineDuration: Duration nodes remain isolated after violations (line 125).
• minimumHealthyNodes: Required healthy node count to remain operational (line 127).
• failClosed: When true, rejects traffic on guard failures (line 129).
• rotationURL, rotationToken, rotationTimeout: Optional webhook configuration for IP rotation (lines 131-134).

Minimal Configuration Example

The following config.yaml includes only the required sections for a single-instance SQLite deployment:

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 and validated by 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}