Skip to main content
The server configuration section defines how Cerbos listens for connections, handles authentication, and manages requests.

​
Basic Configuration

​
server.httpListenAddr
string
default:":3592"
required
HTTP server listen address. Can be a TCP address (:3592, 0.0.0.0:3592) or Unix domain socket (unix:/tmp/cerbos.http.sock).
​
server.grpcListenAddr
string
default:":3593"
required
gRPC server listen address. Can be a TCP address (:3593, 0.0.0.0:3593) or Unix domain socket (unix:/tmp/cerbos.grpc.sock).
​
server.udsFileMode
string
default:"0o766"
File permissions for Unix domain sockets. Must be specified in octal format.
server:
  httpListenAddr: ":3592"
  grpcListenAddr: ":3593"
  udsFileMode: "0o766"

​
TLS Configuration

Configure TLS/SSL encryption for secure connections.
​
server.tls.cert
string
Path to the TLS certificate file.
​
server.tls.key
string
Path to the TLS private key file.
​
server.tls.caCert
string
Path to the CA certificate for verifying client certificates (mutual TLS).
server:
  tls:
    cert: /path/to/server.crt
    key: /path/to/server.key
    caCert: /path/to/ca.crt  # Optional: for client certificate verification
Both cert and key must be provided to enable TLS. If either is missing, TLS will be disabled.

​
Admin API

The Admin API provides endpoints for managing policies, schemas, and server operations.
​
server.adminAPI.enabled
boolean
default:"false"
Enable or disable the Admin API.
​
server.adminAPI.adminCredentials.username
string
default:"cerbos"
Username for Admin API authentication.
​
server.adminAPI.adminCredentials.passwordHash
string
Base64-encoded bcrypt hash of the admin password.
server:
  adminAPI:
    enabled: true
    adminCredentials:
      username: admin
      passwordHash: JDJ5JDEwJEdEOVFzZDE2VVhoVkR0N2VkUFBVM09nalc0QnNZaC9xc2E4bS9mcUJJcEZXenp5OUpjMi91Cgo=
The default password is cerbosAdmin. Always change this in production by generating a bcrypt hash and encoding it in base64:
# Generate bcrypt hash and encode
htpasswd -bnBC 10 "" "your-password" | tr -d ":" | base64

​
CORS Configuration

Configure Cross-Origin Resource Sharing for HTTP API access from web browsers.
​
server.cors.disabled
boolean
default:"false"
Disable CORS entirely.
​
server.cors.allowedOrigins
string[]
default:"['*']"
List of allowed origins. Use ['*'] to allow all origins.
​
server.cors.allowedHeaders
string[]
default:"['content-type']"
List of allowed request headers.
​
server.cors.maxAge
duration
default:"0s"
How long browsers can cache the preflight response.
server:
  cors:
    allowedOrigins:
      - "https://app.example.com"
      - "https://admin.example.com"
    allowedHeaders:
      - "content-type"
      - "authorization"
    maxAge: 300s

​
Request Limits

Control the maximum size of authorization requests to prevent abuse.
​
server.requestLimits.maxActionsPerResource
integer
default:"50"
Maximum number of actions that can be checked for a single resource in one request. Must be between 1 and 500.
​
server.requestLimits.maxResourcesPerRequest
integer
default:"50"
Maximum number of resources that can be checked in a single batch request. Must be between 1 and 500.
server:
  requestLimits:
    maxActionsPerResource: 100
    maxResourcesPerRequest: 100
These limits help prevent resource exhaustion from overly large requests. Adjust based on your performance requirements and security needs.

​
Feature Flags

​
server.metricsEnabled
boolean
default:"true"
Enable Prometheus metrics endpoint at /metrics.
​
server.logRequestPayloads
boolean
default:"false"
Log full request payloads for debugging. Use with caution in production.
​
server.apiExplorerEnabled
boolean
default:"true"
Enable the API Explorer UI for testing API calls.
server:
  metricsEnabled: true
  logRequestPayloads: false
  apiExplorerEnabled: true

​
Advanced HTTP Settings

Fine-tune HTTP server timeouts and connection handling.
​
server.advanced.http.readTimeout
duration
default:"30s"
Maximum duration for reading the entire request, including the body.
​
server.advanced.http.readHeaderTimeout
duration
default:"15s"
Maximum duration for reading request headers.
​
server.advanced.http.writeTimeout
duration
default:"30s"
Maximum duration for writing the response.
​
server.advanced.http.idleTimeout
duration
default:"120s"
Maximum duration to wait for the next request when keep-alives are enabled.
server:
  advanced:
    http:
      readTimeout: 30s
      readHeaderTimeout: 15s
      writeTimeout: 30s
      idleTimeout: 120s

​
Advanced gRPC Settings

Fine-tune gRPC server connection handling and limits.
​
server.advanced.grpc.maxRecvMsgSizeBytes
integer
default:"4194304"
Maximum size of a single gRPC request message in bytes. Default is 4MiB. Affects performance and resource utilization.
​
server.advanced.grpc.maxConcurrentStreams
integer
default:"1024"
Maximum number of concurrent streams per connection. Set to 0 to allow unlimited streams.
​
server.advanced.grpc.maxConnectionAge
duration
default:"600s"
Maximum age of a connection before it’s closed and recreated.
​
server.advanced.grpc.connectionTimeout
duration
default:"60s"
Timeout for establishing new gRPC connections.
server:
  advanced:
    grpc:
      maxRecvMsgSizeBytes: 4194304  # 4 MiB
      maxConcurrentStreams: 1024
      maxConnectionAge: 600s
      connectionTimeout: 60s

​
Complete Example

server:
  httpListenAddr: ":3592"
  grpcListenAddr: ":3593"
  
  tls:
    cert: /etc/cerbos/tls/server.crt
    key: /etc/cerbos/tls/server.key
    caCert: /etc/cerbos/tls/ca.crt
  
  adminAPI:
    enabled: true
    adminCredentials:
      username: admin
      passwordHash: ${ADMIN_PASSWORD_HASH}
  
  cors:
    allowedOrigins:
      - "https://app.example.com"
    allowedHeaders:
      - "content-type"
      - "authorization"
  
  requestLimits:
    maxActionsPerResource: 100
    maxResourcesPerRequest: 50
  
  metricsEnabled: true
  apiExplorerEnabled: true
  
  advanced:
    http:
      readTimeout: 30s
      writeTimeout: 30s
    grpc:
      maxRecvMsgSizeBytes: 4194304
      maxConcurrentStreams: 1024

​
Environment Variable Expansion

Configuration values can reference environment variables using ${VAR_NAME} syntax: 
server:
  adminAPI:
    adminCredentials:
      username: ${ADMIN_USERNAME}
      passwordHash: ${ADMIN_PASSWORD_HASH}
Use $$ to escape literal dollar signs in configuration values.