Skip to content

Quickstart: self-hosted control plane ​

Some teams keep the control plane inside their own network. We provide the control plane for this and agree the setup with you. To try it, one machine is enough: one control plane, one agent. For a control plane that other people and agents use, follow Self-hosted control plane (PostgreSQL, TLS, backups) instead of step 1.

The commands run from the top folder of the control-plane files. SDK commands are written as preworld-guard …, the command the SDK installs. From a source checkout, uv run --frozen python -m preworld_guard … does the same.

1. Start the control plane ​

On one machine, with SQLite, set a bootstrap token and the host name the control plane answers to:

sh
export PREWORLD_GUARD_BOOTSTRAP_TOKEN='replace-with-a-random-value'
export PREWORLD_GUARD_ALLOWED_HOSTS='guard.example.com'
export PREWORLD_GUARD_ENDPOINT='https://guard.example.com'
export PREWORLD_GUARD_DB='/var/lib/preworld-guard/control.sqlite3'
uv run --frozen python -m guard_demo serve --host 0.0.0.0 --port 8765

The bootstrap token only creates organizations and projects. Never give it to an agent or an executor. A real deployment sits behind TLS, keeps its secrets in a secret manager and runs under its own service account.

2. Create the organization and project ​

sh
preworld-guard --endpoint https://guard.example.com \
  onboard \
  --bootstrap-token "$PREWORLD_GUARD_BOOTSTRAP_TOKEN" \
  --organization 'Example' \
  --project 'support-agent'

Keep the project.id and the owner access_token it returns. The owner token issues the other tokens. It never goes into an agent's process.

3. Issue project tokens ​

With the owner token, call POST /v1/tokens once per role: executor, admin, reviewer and viewer. Each raw value is returned once.

sh
curl -X POST "$PREWORLD_GUARD_ENDPOINT/v1/tokens" \
  -H "Authorization: Bearer $GUARD_OWNER_TOKEN" -H 'Content-Type: application/json' \
  -d '{"role":"executor"}'
RoleWho holds itWhat it can do
executorThe agent (SDK or MCP proxy)Fetch the policy, send heartbeats and events, ask for approvals
adminWhoever manages policiesPreview, propose and publish policies
reviewerAn independent reviewerApprove or reject candidate policies
viewerAudit and log exportRead events and the audit log, run siem-export
sh
export PREWORLD_GUARD_PROJECT_ID='prj_...'
export PREWORLD_GUARD_TOKEN='pwg_...'
export GUARD_ADMIN_TOKEN='pwg_...'
export GUARD_REVIEWER_TOKEN='pwg_...'

A project token is a service identity: it doesn't prove which person used it. Action approvals are decided only by people signed in to the console with a named account, so for those, and for the console in general, configure enterprise SSO. See Self-hosted control plane.

4. Install the SDK ​

The SDK is preworld-guard-sdk, distributed privately. Install it only from the index or wheel we give you, never from public PyPI, where nobody owns that name. Pin the version and its hash. See Python SDK.

5. Register an executor and fetch the policy ​

sh
preworld-guard \
  --endpoint https://guard.example.com \
  --project-id "$PREWORLD_GUARD_PROJECT_ID" \
  --token "$PREWORLD_GUARD_TOKEN" register --name support-agent

preworld-guard \
  --endpoint https://guard.example.com \
  --project-id "$PREWORLD_GUARD_PROJECT_ID" \
  --token "$PREWORLD_GUARD_TOKEN" policy

This proves the connection once. A long-running agent calls guard.start() instead, which registers, sends a heartbeat every 15 seconds and confirms which policy it loaded. The policy is cached in .preworld-guard/policy.json and checked against its SHA-256.

6. Wrap a tool ​

python
from preworld_guard import GuardClient, GuardDenied

guard = GuardClient(
    endpoint="https://guard.example.com",
    token="pwg_...",
    project_id="prj_...",
    agent_id="support-agent",
)
guard.start(name="support-agent")

@guard.tool("search_customer")
def search_customer(customer_id: str):
    return database.search(customer_id)

try:
    search_customer("customer-42")
except GuardDenied as error:
    print(error.decision.reason_code, error.decision.message)

For framework agents and MCP servers, see Framework adapters and MCP proxy.

7. Observe, then enforce ​

The project starts in Observe mode. Let the agent report a few real actions, then preview and publish with the admin token:

sh
curl -X POST "$PREWORLD_GUARD_ENDPOINT/v1/policy/preview" \
  -H "Authorization: Bearer $GUARD_ADMIN_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"mode":"enforce","rules":[{"rule_id":"deny-shell","effect":"deny","resource":"shell.exec","message":"Running shell commands is not allowed."}]}'

curl -X POST "$PREWORLD_GUARD_ENDPOINT/v1/policy/publish" \
  -H "Authorization: Bearer $GUARD_ADMIN_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"mode":"enforce","rules":[{"rule_id":"deny-shell","effect":"deny","resource":"shell.exec","message":"Running shell commands is not allowed."}]}'

Publishing directly like this is meant for emergencies. It is recorded in the control audit log but has no second reviewer. The normal route, with candidates, preview, an independent review and a versioned publish, is in Publishing a policy.

Then try one ordinary call and one call the rule matches, and check the events for the policy version, the decision and the execution status.

Next steps ​