Self-hosted control plane
A self-hosted deployment runs the control plane in your network. We provide it and agree the setup with you. It runs as a single node: the Guard API and PostgreSQL in separate containers, the database on an internal network only, the API bound to the host's loopback address, and a TLS reverse proxy on the host in front of it. It has no load balancing, no database failover and no public firewall rules. Add those yourself if you need them.
The commands run from the top folder of the control-plane files. preworld-guard is the SDK's command (see Command line).
Secrets and host names
Outside any repository, create a folder only the deployment administrator can read, with two random secrets in files named db-password and bootstrap-token. On Linux, Guard runs as 10001:10001, so give the files group 10001 and mode 0640, and the folder mode 0700:
sudo chgrp 10001 /etc/preworld-guard/secrets/{db-password,bootstrap-token}
chmod 0640 /etc/preworld-guard/secrets/{db-password,bootstrap-token}Never put the values in the Compose file, in Git or in an agent's container.
Start it
export GUARD_SECRETS_DIR=/etc/preworld-guard/secrets
export GUARD_ALLOWED_HOSTS=guard.example.com,127.0.0.1,localhost
export GUARD_PUBLIC_ORIGIN=https://guard.example.com
export GUARD_PORT=8765
docker compose -f deploy/control-plane.compose.yaml config --quiet
docker compose -f deploy/control-plane.compose.yaml up -d --build --wait
curl -fsS http://127.0.0.1:8765/v1/healthGUARD_SECRETS_DIRmust be an absolute path.- Keep
127.0.0.1,localhostinGUARD_ALLOWED_HOSTSfor the health checks. GUARD_PUBLIC_ORIGINis the HTTPS origin people really use (with a port if any, no path). It sets the session cookie's Secure flag and is checked on every write. The control plane doesn't trust a client'sX-Forwarded-Proto./v1/healthchecks the database and returns 503 when it can't reach it. Once TLS is set up, check it again over HTTPS from another machine.- Pin a reviewed image digest for real use.
GUARD_IMAGEselects the image.
Create the project, then turn onboarding off
Onboarding is off by default (GUARD_ONBOARD_ENABLED=0). Turn it on just long enough to create the organization and project:
GUARD_ONBOARD_ENABLED=1 docker compose -f deploy/control-plane.compose.yaml up -d --no-build --force-recreate guard
PREWORLD_GUARD_BOOTSTRAP_TOKEN="$(cat "$GUARD_SECRETS_DIR/bootstrap-token")" \
uv run --frozen python -m preworld_guard --endpoint https://guard.example.com \
onboard --organization 'Customer' --project 'support-agent'
GUARD_ONBOARD_ENABLED=0 docker compose -f deploy/control-plane.compose.yaml up -d --no-build --force-recreate guardThe owner token is shown once. Put it straight into your secret manager. With onboarding off, /v1/onboard returns 403 even if the bootstrap token leaks. Each call creates a new organization and project, so check the project ID you saved before running it again.
Project tokens
The owner token issues the others and never goes into an agent. Issue one per role with POST /v1/tokens:
| Role | For |
|---|---|
executor | Policy sync, heartbeats and events, in the agent |
viewer | Reading audit data and siem-export |
reviewer | Reviewing candidate policies |
admin | Managing policies |
POST /v1/tokens shows the raw value once to the owner; GET /v1/tokens lists only IDs, prefixes and status. POST /v1/token/rotate revokes the caller's own token; POST /v1/tokens/{id}/revoke lets the owner revoke any token.
A project token is a service identity. It can't prove which person used it. The direct publish endpoints (POST /v1/policy/publish, POST /v1/policy/dsl/publish) stay available to owners and admins for emergencies, recorded in the control audit log but without a second reviewer.
Enterprise SSO for the console
People sign in to a self-hosted console with your OIDC provider. It needs RS256-signed tokens, authorization code with PKCE (S256), a fixed issuer and JWKS address, and a group claim. Create the project first, then write the configuration:
{
"project_id": "REPLACE_WITH_PROJECT_ID",
"issuer": "https://id.example.com/realms/company",
"audience": "preworld-guard-console",
"jwks_url": "https://id.example.com/realms/company/protocol/openid-connect/certs",
"authorization_endpoint": "https://id.example.com/realms/company/protocol/openid-connect/auth",
"token_endpoint": "https://id.example.com/realms/company/protocol/openid-connect/token",
"client_secret_file": "/run/secrets/oidc_client_secret",
"group_roles": {
"guard-owners": "owner",
"guard-admins": "admin",
"guard-reviewers": "reviewer",
"guard-viewers": "viewer"
}
}Register the exact callback https://guard.example.com/v1/oidc/callback with your provider, put oidc-client-secret in the secrets folder, and start with the OIDC overlay:
export GUARD_OIDC_CONFIG_FILE=/etc/preworld-guard/oidc-login.json
export GUARD_PUBLIC_ORIGIN=https://guard.example.com
# The secrets folder holds oidc-client-secret, group 10001 and mode 0640 like the other secrets.
docker compose -f deploy/control-plane.compose.yaml -f deploy/oidc.compose.yaml config --quiet
docker compose -f deploy/control-plane.compose.yaml -f deploy/oidc.compose.yaml up -d --wait- Endpoints are configured explicitly. There is no automatic discovery.
- Only people in a mapped group can sign in. Someone in several groups gets the first of owner, admin, reviewer, viewer.
- Accounts are bound to the provider's issuer and subject, never matched by email.
- A session lasts at most 15 minutes, and never longer than the ID token.
- Group changes apply at the next sign-in. There is no SCIM and no global sign-out. Removing someone in your provider takes effect when their current token and session end.
- One identity provider per project.
Backups, restore and upgrades
Back up PostgreSQL regularly from a controlled host, and practise a restore somewhere isolated:
docker compose -f deploy/control-plane.compose.yaml exec -T postgres pg_dump -U guard -Fc guard > guard.dump
docker compose -f deploy/control-plane.compose.yaml stop guard
docker compose -f deploy/control-plane.compose.yaml exec -T postgres pg_restore -U guard --clean --if-exists -d guard < guard.dump
docker compose -f deploy/control-plane.compose.yaml start guard
curl -fsS http://127.0.0.1:${GUARD_PORT:-8765}/v1/health- Backups hold policies, audit records and token digests. Encrypt them and limit who can read them.
- The SDK's event queue lives on the agent's host, not in this database.
- Database migrations only go forward. An existing PostgreSQL database is upgraded only when
PREWORLD_GUARD_MIGRATION_BACKUP_FILEpoints to a readablepg_dump -Fcbackup taken before the upgrade. Otherwise the control plane refuses to start. A control plane older than its database also refuses to start. - Before an upgrade, note the image digest, the backup and the current policy version. Afterwards check health, token permissions, policy sync, the audit export and one allowed and one denied action.
This is a single-node Compose deployment. It has no zero-downtime upgrades and no failover.
The SDK for a self-hosted deployment
Agents install preworld-guard-sdk from a private index or wheel we provide, never from public PyPI. Pin the exact version and its SHA-256, or install the wheel by address with #sha256=.