Broker Quickstart

Beta — 0.1.0b5

The Zabta Broker is a local daemon that keeps API keys out of your AI agents' hands. Instead of an environment variable your agent can read at will, secrets live in an encrypted local vault; your agent requests a credential at the moment of use, and the Broker evaluates policy before handing over a short-lived lease.

Pre-release. The wire protocol, CLI, and policy model may change without notice between releases. Evaluate it, but don't put production credentials behind it yet.

Install

bash

pip install zabta-broker==0.1.0b5

Install by exact version, never --pre. While the Broker is in beta, pip only resolves pre-releases when named exactly — and --pre would opt your entire dependency tree into pre-release versions, not just this package. Requires Python 3.10+ on macOS or Linux.

Set up the daemon

1. Store a secret in the encrypted vault

bash

zabta-broker vault add --provider stripe --scopes charges:create

2. Start the daemon

bash

zabta-broker start
# Binds to 127.0.0.1:9477 — loopback only, never a network service

3. Register with the Zabta cloud control plane

bash

zabta-broker register --api-key <your-zabta-api-key>
# Connects to the Zabta cloud control plane for policies, approvals,
# and agent-identity sync

This is what lets the Broker pull your policies and learn your registered agents — see Agent identity below.

Requires a paid plan. Connecting a Broker to the Zabta cloud (policy sync, approvals, identity sync) is a Starter-plan capability. On Free, register returns a message pointing you here rather than a bare error. You can still run a standalone local Broker without registering — it enforces deny-by-default with no cloud-managed policies.

Optional: run as a background service

Instead of running zabta-broker start in a foreground terminal, install it as a launchd (macOS) or systemd (Linux) service:

bash

zabta-broker install-daemon
# launchd on macOS, systemd on Linux — starts the Broker at login/boot

Agent identity

The Broker identifies agents by DID (did:zabta:<agent id>), derived directly from the cloud agent id you already have — there is no separate identity to create or manage. Set one environment variable:

bash

export ZABTA_AGENT_ID=<your agent id>
# The id shown in the Zabta dashboard for this agent. Nothing else
# needs configuring — see "Agent identity" below.

The cloud is the source of truth: when the Broker registers and syncs, it pulls your tenant's active agents and populates its local identity registry with their derived DIDs. Unregistered DIDs are hard-denied — identity is checked before policy runs.

First-minute gap. If you create an agent in the dashboard and immediately request a credential, the Broker may not have synced that agent's identity yet — the sync runs on an interval, not instantly on agent creation. A credential request in that window is denied with identity_unregistered, not a hang or a silent allow. Wait for the next sync interval (or restart the Broker, which syncs immediately on startup) and retry.

Requesting a credential

On the agent side, use the zabta SDK:

python

import zabta

with zabta.credential("stripe", ["charges:create"]) as key:
    ...  # `key` is a fresh checkout; use it now, don't store it

An async equivalent, acredential(), ships from day one for async agent code:

python

import zabta

async with zabta.acredential("stripe", ["charges:create"]) as key:
    ...

The full context-manager contract — the yields-or-raises invariant, the exception taxonomy, and safe adoption patterns — is in the Credential Leasing Guide.

Credential Leasing Guide Enforcement Boundary SDK Reference