Run the Sidecar

The sidecar runs next to your agent. The agent makes its tool calls to the sidecar over loopback (HTTP proxy /{tool}/{path} or MCP) — it holds no provider credentials. The sidecar authorizes with the gate, injects the vaulted credential, and originates the real call.

There is no iptables redirect, no CA cert, no TLS interception. The one agent-side change is pointing a tool’s base-URL (or the MCP client) at the sidecar — for MCP-native agents that’s zero-code.

Try it locally — zero prod, one command

The repo ships a self-contained demo: a mock control plane + a mock provider + the sidecar + an unmodified agent. It proves the whole credential-broker flow without touching any real service or audit trail.

cd sidecar/demo
docker compose up --build
docker compose logs -f agent

You’ll see the agent make three calls through the sidecar:

=== ALLOWED call (amount under limit) ===
{"received_authorization":"Bearer vault-secret-xyz","path":"/charge"}   # ← sidecar injected the vaulted key
=== DENIED call (amount=999 over the $50 mandate) ===
{"decision":"deny","code":"MANDATE_LIMIT_EXCEEDED",...}                 # ← provider never called
=== UNCATALOGED tool (egress allowlist) ===
{"decision":"deny","code":"TOOL_NOT_ALLOWED",...}                       # ← only catalogued tools are reachable

The provider echoes the Authorization it received — proving the sidecar injected a credential the agent never held.

Run it for real

Drop the sidecar next to your agent (same pod / compose project). It pulls its tool catalog

enforcement mode live from the control plane using its CONTROL_API_KEY, so dashboard changes take effect within ~15s — no redeploy.

The sidecar image is published to GHCR by CI from regent-control/sidecar: ghcr.io/abay94/control-sidecar:latest. (Or build it yourself: docker build -t control-sidecar regent-control/sidecar.) For unauthenticated docker pull, the GHCR package must be public — otherwise docker login ghcr.io first.

services:
  agent:
    image: yourorg/your-agent:latest
    environment:
      # The ONLY agent change: point each tool at the local sidecar.
      PAYMENTS_BASE_URL: "http://sidecar:8080/payments"
      # (or, for an MCP-native agent, set the MCP server to http://sidecar:8080/mcp)
    depends_on: [sidecar]
 
  sidecar:
    image: ghcr.io/abay94/control-sidecar:latest
    ports: ["8080:8080"]
    environment:
      CONTROL_API_URL:     "https://api.regentprotocol.org"
      CONTROL_API_KEY:     "${CONTROL_API_KEY}"      # rgnt_ctrl_… (issued in the dashboard)
      CONTROL_LICENSE_KEY: "${CONTROL_LICENSE_KEY}"  # rcl_…
      CONTROL_AGENT_ID:    "agent_refund_bot"
      CONTROL_FAIL_MODE:   "closed"                  # deny if the control plane is unreachable
      # The vaulted provider credential(s) — read by the sidecar, never the agent:
      PAYMENTS_TOKEN:      "${PAYMENTS_TOKEN}"

⚠️

Vaulted credentials must live only in the sidecar’s environment (KMS-backed), never in the agent container or Regent’s cloud.

Environment reference

Variable	Purpose
`CONTROL_API_URL`	the Decision API base URL
`CONTROL_API_KEY`	the org Control key (`rgnt_ctrl_…`) — also pulls the live catalog + mode
`CONTROL_LICENSE_KEY`	enables enforcement (fail-closed if invalid)
`CONTROL_AGENT_ID`	the agent this sidecar governs
`CONTROL_FAIL_MODE`	`closed` (deny on control-plane error) or `open` (allow + warn)
`CONTROL_TOOLS`	a JSON catalog — the fallback/base if config-pull is off
`CONTROL_SIGN_REQUESTS`	HMAC-sign decision requests (`X-Agent-Signature`)
`<secret_env>`	each tool’s vaulted credential, named by the catalog’s `secret_env`

Verify it’s live

Health

curl http://localhost:8080/healthz → {"status":"ok",...}.

First call

Make a tool call through the sidecar; it appears in Control → Decisions in the dashboard.

Observe → enforce

Start in observe mode (logs would-be denials, allows everything), then flip to enforce.

Next: the full Refund Agent walkthrough wires a real policy, mandate, and delegation end-to-end.

Onboarding Guide Walkthrough: Refund Agent