Getting started

Prerequisites

A set of Cerbos policies. An example set of policies are avaliable at https://github.com/cerbos/example-cerbos-policy-repository.
Cerbos version 0.45.1 or higher.
Outbound internet access from your Cerbos instances so that they can connect to Cerbos Hub to fetch bundle updates and, if enabled, upload audit logs.

Create a policy store

Cerbos Hub uses policy stores to manage your policies. A policy store is a collection of policies and tests that can be built into a deployment and distributed to Cerbos PDPs.

For the quick start, you can create a policy store using the browser and upload a ZIP file containing policies (example) or fork the GitHub example repository and connect it to Cerbos Hub.

Upload policies via browser

Sign in to Cerbos Hub at https://hub.cerbos.cloud and follow the on-boarding wizard to create an Organization and its first Workspace.
Inside the Workspace, select Policy stores then New store.
Give the store a clear name, for example orders-service, choose Browser upload as the source, and click Create.
In the store detail page, click Upload files and select a ZIP file containing your policies. The ZIP file should contain the policies in the root directory, not in a subdirectory.
Cerbos Hub immediately ingests the ZIP file, compiles the policies, and shows the first successful build.

GitHub repository

Sign in to Cerbos Hub at https://hub.cerbos.cloud and follow the on-boarding wizard to create an Organization and its first Workspace.
Inside the Workspace, select Policy stores then New store.
Give the store a clear name, for example orders-service, choose GitHub repository as the source and connect to your GitHub account.
Pick the branch you want Hub to track, usually main, and save. Cerbos Hub immediately ingests the repository, compiles the policies, and shows the first successful build.

You can create additional stores for other branches, teams or projects.

Create a Deployment

Deployments package policies from one or more policy stores into versioned bundles that are automatically distributed to connected Cerbos PDPs.

Open Deployments then click New deployment.
Select the store you just created.
Click Create. Hub starts the initial build. When it finishes, note the deployment ID shown on the detail page. You will need this ID to configure the PDP.

Generate client credentials

Navigate to Settings → Client credentials and click Generate a client credential, giving it a name and select Read & Write so that policies can be pulled down and Audit Logs pushed back. Copy both the Client ID and Client secret. The secret is shown only once.

Configure and run a Cerbos PDP

You can pass the Hub connection settings as environment variables or in a YAML configuration file. The example below uses environment variables for a quick start:

docker run --rm --name cerbos \
  -p 3592:3592 -p 3593:3593 \
  -e CERBOS_HUB_DEPLOYMENT_ID="..." \
  -e CERBOS_HUB_CLIENT_ID="..." \
  -e CERBOS_HUB_CLIENT_SECRET="..." \
  ghcr.io/cerbos/cerbos:latest server

`CERBOS_HUB_DEPLOYMENT_ID`	Deployment ID from the deployment detail page in Cerbos Hub.
`CERBOS_HUB_CLIENT_ID`	Client ID from Deployment → Client credentials.
`CERBOS_HUB_CLIENT_SECRET`	Client secret from Deployment → Client credentials.
`CERBOS_HUB_PDP_ID`	Optional. A friendly name for this PDP instance, shown on the Cerbos Hub monitoring page. If omitted, a random identifier is generated.

YAML alternative

server:
  httpListenAddr: ":3592"
  grpcListenAddr: ":3593"

hub:
  credentials:
    pdpID: "orders-pdp-01" # Optional
    clientID: "..."
    clientSecret: "..."

storage:
  driver: hub
  hub:
    remote:
      deploymentID: "..." # Deployment ID from Hub

Assuming you saved the file as .cerbos.yaml in the current directory, start Cerbos with:

docker run --rm --name cerbos \
  -v $(pwd):/conf \
  -p 3592:3592 -p 3593:3593 \
  ghcr.io/cerbos/cerbos:latest server --config=/conf/.cerbos.yaml

See Configuration for advanced configuration options.

Enable audit log collection (optional)

Add the Hub audit backend to stream decision logs to Cerbos Hub:

audit:
  backend: hub
  hub:
    storagePath: "/var/cerbos/audit-buffer" # Local buffer used when the network is unavailable

Refer to Audit log collection for details on filtering sensitive fields and other advanced options.

With a policy store connected, a deployment created, and at least one PDP running, you are ready to iterate on your policies. Push a change to the repository, watch Cerbos Hub build a new deployment version, and see the PDP update itself automatically within seconds.

Next steps

Service PDPs	Production deployment patterns, Kubernetes setup, reliability features, and monitoring.
Embedded PDPs	Run authorization in browsers, edge functions, and mobile apps using WebAssembly.
Audit log collection	Stream decision logs to Cerbos Hub for analysis and compliance.
Policy stores	Connect Git repositories, upload via CLI, or use the SDKs to manage policies.