# Getting started

## Prerequisites

- A set of Cerbos policies. An example set of policies are available at [https://github.com/cerbos/example-cerbos-policy-repository](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](https://github.com/cerbos/example-cerbos-policy-repository/archive/refs/heads/main.zip)) or fork the GitHub [example repository](https://github.com/cerbos/example-cerbos-policy-repository) and connect it to Cerbos Hub.

### Upload policies via browser

1. Sign in to Cerbos Hub at [https://hub.cerbos.cloud](https://hub.cerbos.cloud/) and follow the on-boarding wizard to create an Organization and its first Workspace.
2. Inside the Workspace, select **Policy stores** then **New store**.
3. Give the store a clear name, for example `orders-service`, choose **Browser upload** as the source, and click **Create**.
4. 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.
5. Cerbos Hub immediately ingests the ZIP file, compiles the policies, and shows the first successful build.

### GitHub repository

1. Sign in to Cerbos Hub at [https://hub.cerbos.cloud](https://hub.cerbos.cloud/) and follow the on-boarding wizard to create an Organization and its first Workspace.
2. Inside the Workspace, select **Policy stores** then **New store**.
3. Give the store a clear name, for example `orders-service`, choose **GitHub repository** as the source and connect to your GitHub account.
4. 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.

1. Open **Deployments** then click **New deployment**.
2. Select the store you just created.
3. 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:

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

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

```shell
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](https://docs.cerbos.dev/cerbos/latest/configuration/) for advanced configuration options.

## Enable audit log collection (optional)

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

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

Refer to [Audit log collection](https://docs.cerbos.dev/cerbos-hub/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](https://docs.cerbos.dev/cerbos-hub/decision-points) | Production deployment patterns, Kubernetes setup, reliability features, and monitoring. |
| [Embedded PDPs](https://docs.cerbos.dev/cerbos-hub/deployments-epdp-rules) | Run authorization in browsers, edge functions, and mobile apps using WebAssembly. |
| [Audit log collection](https://docs.cerbos.dev/cerbos-hub/audit-log-collection) | Stream decision logs to Cerbos Hub for analysis and compliance. |
| [Policy stores](https://docs.cerbos.dev/cerbos-hub/policy-stores) | Connect Git repositories, upload via CLI, or use the SDKs to manage policies.