From licence to your first gated tool call in five steps.
Install the AgentGuard trial with Docker Compose, run the demo agent, review the calls it holds, then connect your own agent and your own MCP servers.
What you need.
The trial files and your licence come to you by email once you request a trial.
- Docker with Compose v2
- uv, to register agents and mint their capabilities on the host
- The trial bundle (a .zip) we email you, unzipped into a directory of its own
- Your licence directory, holding license.json and license.sig. Keep it outside the bundle
No files yet? Request the trial. The bundle has its own README.md with the same steps. Where it differs from this page, the README is right for your bundle.
Start the sandbox and run the demo agent.
The demo agent calls tools on two demo MCP servers, so you can watch the gateway work before you connect anything of your own.
1. Register the demo agent
From the root of the bundle, the directory that holds AgentGuard/ and FinanceTrak/. This creates a capability root, gives the agent a key, and mints its capability: a token that names the agent, the run, the tools it may call and an expiry (one hour by default). Everything is written to AgentGuard/identity/state/. Keep that directory private.
uv run --project AgentGuard/identity python AgentGuard/identity/issue.py setup \
--run run-1 --agent demo
# agent:demo may use 9 tool(s) in run run-1 for 3600s2. Tell the sandbox where your licence is, and which run this is
Use the absolute path to your licence directory. RUN_ID must match the --run from step 1. Docker Compose reads .env on every command run from AgentGuard/sandbox, so you set these once.
cat > AgentGuard/sandbox/.env <<'EOF'
AGENTGUARD_LICENSE_DIR=/absolute/path/to/your/license
RUN_ID=run-1
EOF3. Start the sandbox
Every command from here on runs in AgentGuard/sandbox. The first build takes a few minutes while Docker fetches the base images. The gateway refuses to start without a valid, unexpired licence.
cd AgentGuard/sandbox
docker compose up -d --build --wait4. Check that the gateway is licensed
If there is no licensed to line, the gateway did not start. See Troubleshooting.
docker compose logs gateway | grep agentguard-gateway
# agentguard-gateway: licensed to <your company> (trial), license L-...
# agentguard-gateway: financetrak-standin, 9 tools exposed: vault__get_secret, ...5. Run the demo agent
It lists the tools the gateway exposes, calls one, and prints the result. Choose the tool with DEMO_TOOL and its arguments with DEMO_ARGS (JSON). --build makes sure the agent image comes from this bundle, not from an earlier one.
docker compose run --rm --build --use-aliases agent
# 9 tool(s) exposed: vault__get_secret, vault__list_secrets, ...
# calling workspace__list_inbox {}
# result: [{"id":"m1","from":"billing@corp.example","subject":"Invoice 4021"}, ...]What the gateway does with a call.
The trial’s stand-in gate decides by the tool’s tier, which is fixed by the tool’s name.
- A read runs.
READ_ONLYtools run without a reviewer. - Anything else is held for a person.
MUTATING,EGRESSandDESTRUCTIVEcalls wait for a reviewer, up to two minutes, and are then refused. - A call outside the agent’s capability is refused before it reaches the gate, and the refusal is recorded. By default the capability grants every exposed tool. Narrow it with
--rights. The agent still sees every exposed tool in its list, but can call only the ones its capability names. A new capability takes effect on the next call, with no restart.shell# from the bundle root uv run --project AgentGuard/identity python AgentGuard/identity/issue.py setup \ --run run-1 --agent demo --rights workspace__list_inbox,workspace__read_inbox # back in AgentGuard/sandbox docker compose run --rm --use-aliases -e DEMO_TOOL=vault__list_secrets agent # refused: AgentGuard gateway refused vault__list_secrets: # capability ... grants no right to vault__list_secrets # from the bundle root again: give the demo agent every tool back before you go on uv run --project AgentGuard/identity python AgentGuard/identity/issue.py setup \ --run run-1 --agent demo - A refusal halts the run. Once any consequential call is refused, or an agent calls a tool name that isn’t exposed, every later consequential call through the gateway is refused, for every agent. Reads still run. Recreate the gateway to start a fresh run.
- A tool whose definition has changed is quarantined. The gateway checks each tool against its pin before every consequential call.
- Copying untrusted content into a consequential call is refused. Once an agent has read results from an untrusted server, a consequential call that copies 24 or more characters of them, or names a recipient that appears in no trusted result, is refused before the gate. No reviewer can release it.
Review held calls.
The review socket lives inside the gateway container, so only someone who can run docker compose exec there can review. No agent can.
Start a call that will be held, in one terminal:
docker compose run --rm --use-aliases -e DEMO_TOOL=workspace__archive_message \
-e 'DEMO_ARGS={"message_id":"m1"}' agentIn a second terminal, from AgentGuard/sandbox, list the held calls and decide:
PY=/app/AgentGuard/gateway/.venv/bin/python
docker compose exec gateway $PY -m agentguard_gateway.review list --show-args
# backend financetrak-standin: 1 held
# run-1.24a2ab5f:1 workspace__archive_message MUTATING waiting 6.2s
# args: {"message_id": "m1"}
docker compose exec gateway $PY -m agentguard_gateway.review \
approve run-1.24a2ab5f:1 --reviewer you@example.com
# or: ... review deny run-1.24a2ab5f:1 --reviewer you@example.comThe first terminal then prints result: Archived m1. The reviewer’s name goes into the audit log with the decision. A deny halts the run, so recreate the gateway before you try more consequential calls.
Run your own agent.
An agent is any process on sandbox-net that sends its requests to http://gateway:8000/mcp with AgentGuardAuth. The gateway publishes no port, so nothing outside the sandbox can reach it.
1. Register your agent, then recreate the gateway
# from the bundle root; use the same --run as RUN_ID
uv run --project AgentGuard/identity python AgentGuard/identity/issue.py setup \
--run run-1 --agent my-agent
# then, in AgentGuard/sandbox: the gateway reads agent keys at start
docker compose up -d --force-recreate --wait gateway2. Use AgentGuardAuth in your agent’s MCP client
Copy AgentGuard/identity/agentguard_identity.py into your agent. It needs fastmcp and pyjwt[crypto]. Each request carries the agent’s capability and a short-lived assertion signed with the agent’s key. Both files are read again on every request, so a re-minted capability works without restarting the agent.
import asyncio
from fastmcp import Client
from fastmcp.client.transports import StreamableHttpTransport
from agentguard_identity import AgentGuardAuth
async def main():
# Reads AGENTGUARD_CAPABILITY_FILE, AGENTGUARD_AGENT_KEY_FILE and
# AGENTGUARD_AGENT_NAME from the environment.
auth = AgentGuardAuth.from_env()
client = Client(StreamableHttpTransport("http://gateway:8000/mcp", auth=auth))
async with client:
print(await client.call_tool("workspace__list_inbox", {}))
asyncio.run(main())3. Run it as the agent service
The agent service in compose.yaml already sets the environment and mounts the key and capability of the agent named by AGENT_NAME. Point its build at your agent’s Dockerfile, or replace build with image: your-agent:tag. Keep --build while you change the agent, or Compose may reuse the demo agent’s image. AgentGuard/sandbox/agent/Dockerfile is a working example to start from.
AGENT_NAME=my-agent docker compose run --rm --use-aliases --build agent
# or, for an agent that keeps running:
AGENT_NAME=my-agent docker compose --profile agent up -d --build agent4. If your agent calls a model API, allow the host
The sandbox has no other route out. The agent service already sends HTTPS through the egress proxy. Name the service, so that only your agent may use the route, then run docker compose restart egress-proxy. A clients= rule needs --use-aliases on docker compose run, which is why the commands above include it. Every connection, allowed or refused, is logged.
# AgentGuard/sandbox/egress_proxy/allowlist.txt
api.anthropic.com:443 clients=agentAdd your own MCP server.
Do this once the demo works.
- Run your server on mcp-net, so only the gateway can reach it, by adding a service to
compose.yaml. - Propose pins for its tools. The pin tool runs inside the gateway container, the only place that can reach
mcp-net. It prints each tool with its definition hash and tier, and changes nothing. You can review the output before approving it. - Approve the tools with
--approve. It prints only the entries to approve, and leaves out any tool whose description fails the poisoning scan. Those tools are reported on stderr and need a hand edit. Append the output to thetools:list inAgentGuard/sandbox/sandbox.yamlon your machine, minus its firsttools:line. Settrust: trustedonly for a server whose results you would let an agent act on without checking. Omitted means untrusted. Tiers are fixed by the tool’s name, and the gateway refuses any other tier. A tool namedfetch_…isMUTATING, so each call waits for a reviewer. Name read-only toolsget_…to have them run without one. - Recreate the gateway and re-mint capabilities, since a capability names its tools when it is minted.
my-tools:
image: your-mcp-server:tag
networks: [mcp-net]docker compose up -d --wait my-tools
docker compose exec gateway /app/AgentGuard/gateway/.venv/bin/python \
-m agentguard_gateway.pin my-tools=http://my-tools:8000/mcp# from AgentGuard/sandbox: print only the entries to approve, then append them
docker compose exec -T gateway /app/AgentGuard/gateway/.venv/bin/python \
-m agentguard_gateway.pin --approve my-tools=http://my-tools:8000/mcp \
| tail -n +2 >> sandbox.yamldocker compose up -d --force-recreate --wait gateway
docker compose logs gateway | grep "tools exposed"
# from the bundle root: a capability names its tools when it is minted
uv run --project AgentGuard/identity python AgentGuard/identity/issue.py setup \
--run run-1 --agent demoWatch the decisions.
Every decision goes into a hash-chained audit log in the gateway-audit volume. It holds an argument digest, never argument values. The audit log is the record; traces are a view of it.
docker compose exec gateway tail -n 5 /var/lib/agentguard/gateway-audit.jsonlTraces in the bundled Grafana
One span per tool call, with the gate’s decision inside it. A span carries the tool name, its tier, the outcome and reason, the argument digest and length, and the run ID. Add the overlay to .env, so every docker compose command uses it. Grafana is bound to 127.0.0.1 and is read-only for anonymous users.
echo "COMPOSE_FILE=compose.yaml:compose.observability.yaml" >> .env
docker compose up -d --build --wait
docker compose --profile debug up -d debug-ports
# Open http://127.0.0.1:3000 → Explore → Tempo, then search:
# {resource.service.name="agentguard-gateway"}Your own OTLP collector
Set OTEL_EXPORTER_OTLP_ENDPOINT to your collector’s base URL in an override file next to compose.yaml, and set COMPOSE_FILE=compose.yaml:collector.yaml in .env. The gateway sends spans to one endpoint, so this replaces the bundled Grafana: if .env already has a COMPOSE_FILE line, edit it rather than adding a second one, since the last one wins. Then run docker compose up -d --wait. A collector on a network the gateway joins gets spans, and nothing else does. Keep it off sandbox-net, where every agent could reach it. We have tested only the bundled Grafana; the exporter is standard OTLP/HTTP.
# collector.yaml, next to compose.yaml
services:
gateway:
environment:
OTEL_EXPORTER_OTLP_ENDPOINT: http://your-collector:4318
networks: [sandbox-net, mcp-net, your-net]
networks:
your-net:
external: true # the network your collector is already onStop and start again
To start again later, re-run quick start step 1 if the capability has expired, then docker compose up -d --wait.
docker compose down # stop; the audit log is kept
docker compose down -v # stop and delete the audit logIf something does not work.
- You seeset AGENTGUARD_LICENSE_DIR to the directory with license.json and license.sigWhat it means
AgentGuard/sandbox/.envis missing, or you ran the command from another directory.What to doCreate.env(quick start, step 2) and run Compose fromAgentGuard/sandbox. - You seeThe gateway exits at start with a licence errorWhat it meansThe licence is expired, not yet valid, or the files are altered.What to doContact us. Do not edit the licence files.
- You seeThe gateway exits with a clock errorWhat it meansThe system clock went back past the last recorded run (five minutes of slack is allowed).What to doFix the system clock, then start the gateway again.
- You seebind source path does not exist: .../identity/state/agents/<name>/...What it meansThe agent named by
AGENT_NAMEis not registered.What to doRunissue.py setupfor that agent. - You seeCalls are refused with an expired or invalid capabilityWhat it meansThe capability lasts one hour by default, or was minted for another run.What to doRe-run
issue.py setupwith--runequal toRUN_ID. Use--ttl(seconds) for a longer one. - You seeMCPError: Server returned an error responseWhat it meansWith
401 Unauthorizedindocker compose logs gateway: the gateway refused the agent’s credentials. The audit log’scaller_refusedrecord says why, most oftenno registered agent '<name>', because the agent was registered after the gateway started.What to dodocker compose up -d --force-recreate --wait gateway. Otherwise re-runissue.py setupwith--runequal toRUN_ID. - You seesession halted after a prior denialWhat it meansAn earlier consequential call was refused, so the gateway now refuses every consequential call.What to do
docker compose up -d --force-recreate --wait gateway - You seeA tool is missing from “tools exposed”What it meansIts definition no longer matches its pin, so it is quarantined, or it is not in
sandbox.yaml.What to doCheck the gateway log, then re-pin the tool if the change was intended. - You seeThe agent’s model API calls fail with 403 ForbiddenWhat it meansThe host is not in the egress allowlist, or the
clients=rule did not match.What to doAdd the host, restartegress-proxy, and use--use-aliases. Checkdocker compose logs egress-proxy.
What to expect.
- Capabilities expire. A capability lasts one hour by default. Re-mint it with
issue.py setup, or pass--ttlfor a longer one. - The licence is checked at start. After its expiry date the gateway will not start. It also refuses to run if the system clock moves backwards past a recorded time, with five minutes of slack.
- It can be bypassed by anyone with the source. Rebuilding the image replaces the baked-in licence key. Use the trial to evaluate AgentGuard, not as a control against the person running it.
- Not a production deployment. Containment is best-effort. An internal Docker network stops routing, not a container escape.
For a longer trial or a full licence, email hkboateng@fihansystems.com with your organisation’s name and the licence ID (L-...) from the gateway log.
Need a licence or a longer trial?
Tell us what you are evaluating and we will issue a licence for your organisation. Interocept, the production gate, is licensed separately.