Skip to content

Quickstart: hosted control plane ​

Scope: current hosted production uses organization workspaces. Personal workspaces and owner self-review require a later control-plane upgrade; self-hosted installations depend on their actual version and identity configuration.

With the hosted control plane, we run the control plane for you. Your agent and the Guard SDK run in your own environment, and each tool call is decided there, before it runs. This is the path most teams take. To run the control plane yourself, see Quickstart: self-hosted.

You need:

  • Access set up with us. We give you the console address and the private SDK index address. Examples use https://guard.example.com and https://sdk.guard.example.com in their place.
  • An account accepted by your deployment; use the sign-in method its console offers.
  • An agent in Python 3.11 or 3.12, or in TypeScript on Node.js 22.12 or later with the Vercel AI SDK.
  • A second person who can review policies. A policy's author can't approve it.

1. Sign in ​

Open the console and click "Sign in with Yi Labs". The first time the owner of an organization signs in, Guard creates the organization's space and a project named Guard, with that person as its owner. If we set the space up for you in advance, sign in with the email we registered and confirm the claim within 7 days.

Colleagues join the organization at the configured organization identity provider and then sign in to Guard with their own accounts. Everyone except the owner starts as a viewer. The owner gives roles on the "Members" page, per project, or in advance by email. See Console and roles.

A session lasts 15 minutes and is not extended. Unsaved policy edits stay in the browser tab.

2. Get an SDK download token ​

The SDK is not on public PyPI or npm. It comes only from your private SDK index, and you need an SDK download token to reach it.

  1. As the owner, open "Connect" and click "Issue SDK download token". Pick how long it lasts (1 to 365 days).
  2. Copy the token. It is shown once. It can download the SDK and nothing else: it can't call the control plane.
  3. On the machine that installs packages, add the line the console shows to ~/.netrc and make the file readable only by you (chmod 600 ~/.netrc):
machine sdk.guard.example.com login token password <SDK download token>

In CI, keep the token in a CI secret, write a temporary netrc file during the build and point the NETRC environment variable at it. Never put the token in a requirements file or in Git. Revoke tokens you no longer use.

Don't install from a public index

Current production installs Python preworld-guard-sdk==0.10.0 or npm @preworld/guard@0.2.0. Use only the private-source command from the console, which pins the exact file and its hash.

3. Create a connection ​

A connection is one agent's way in. Still on "Connect", the owner fills in a name, the agent ID and the framework, then clicks "Generate and download package". The frameworks offered are those in Framework adapters, the MCP proxy and the Vercel AI SDK.

The package (guard-connection.zip) holds:

FileWhat it is
guard.envPREWORLD_GUARD_ENDPOINT, PREWORLD_GUARD_PROJECT_ID, PREWORLD_GUARD_AGENT_ID and PREWORLD_GUARD_TOKEN, the executor credential for this agent. It is issued once. Keep it with your secrets.
guard-connection.jsonThe connection's settings, read by the connection check.
guard_integration.pyA starting point for your framework. TypeScript gets guard-integration.ts and .npmrc.example; the MCP proxy gets guard-mcp.template.json.
guard-policy.jsonThe policy as it was when you downloaded the package.
guard-inventory.jsonThe agent as an asset, for the asset inventory.
README.txtThe install command and the check command for this connection.

The executor credential lasts 90 days by default. If it may have leaked, use "Rotate and download package" or "Revoke connection". After a revoke the agent is refused the next time it contacts the control plane.

4. Install the SDK ​

Run the install command from the console or README.txt. It names the wheel's address and its sha256, so a file with other bytes fails to install. For example:

sh
python -m pip install 'preworld-guard-sdk[langchain] @ https://sdk.guard.example.com/packages/preworld_guard_sdk-0.10.0-py3-none-any.whl#sha256=…'

The part in brackets is the framework extra (langchain, langgraph, claude, openai-agents, pydantic-ai, google-adk, agent-framework, llama-index, agno, dspy, crewai, mcp). Some extras can't be installed together. See Framework adapters.

With uv, add the index's /simple/ address as an explicit index and use [tool.uv.sources] so that preworld-guard-sdk comes only from it.

For TypeScript, see TypeScript SDK. The same SDK download token works for npm.

5. Put Guard in front of the tools ​

Follow guard_integration.py. A plain Python tool looks like this:

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)

In real code read the four values from the environment that guard.env sets, not from source. guard.start() registers the executor, sends a heartbeat every 15 seconds and picks up new policy versions. For LangChain, OpenAI Agents and the other frameworks, see Framework adapters. Wrap every tool that has a side effect.

When the agent acts for a signed-in user, pass that user as the trusted subject: with guard_run(subject_id=user_id): .... Approval rules need it, and rules can compare arguments with it.

Several agents on one machine

SDK 0.8.0 and earlier shared one event queue between agents started from the same folder, and one agent could end up blocked. Give each agent its own PREWORLD_GUARD_CACHE, or use SDK 0.9.0 or later, where this is fixed.

6. Check the connection ​

Load the variables from guard.env and run:

sh
preworld-guard connection-check --config guard-connection.json

For TypeScript, in the folder where @preworld/guard is installed:

sh
npx --no preworld-guard connection-check --config guard-connection.json

The check runs no business tool. It reports four things, the same four the console shows under "Check connection":

  • Credential active
  • Executor online
  • Current policy loaded
  • First event received

The first event arrives once the agent has made one guarded call. If a check fails, see Troubleshooting.

7. Observe first ​

A new project starts in Observe mode. Every action still runs. Guard records what it would have decided. Run your agent on normal work for a while and look at the events: which tools it calls, with which argument names, for which users.

8. Draft, preview, review, publish ​

When you know what normal looks like:

  1. Draft. On "Policy workflow", use "Generate from observed behaviour" to get a least-privilege allow list from successful actions. Or edit the policy on "Policy" directly. There you can also write deny, approval and degrade rules. See Policies.
  2. Preview. "Preview" shows syntax errors with line numbers, the difference from the current policy, how recent actions would be decided under the new one, and warnings (for example Enforce mode with no allow rule). Then "Save as a candidate".
  3. Review. "Submit for review". Another person with the reviewer role approves or rejects it.
  4. Publish. The owner or an admin clicks "Prepare to publish", checks the mode, version and changes, and publishes. What gets published must be exactly what was reviewed.

Executors pick up the new version on their next heartbeat, so it takes effect within about 15 seconds. To undo, publish a rollback version. The whole flow is in Publishing a policy.

Next steps ​