AgentGuard · Install and use

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.

Before you start

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.

Quick start

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.

shell
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 3600s

2. 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.

shell
cat > AgentGuard/sandbox/.env <<'EOF'
AGENTGUARD_LICENSE_DIR=/absolute/path/to/your/license
RUN_ID=run-1
EOF

3. 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.

shell
cd AgentGuard/sandbox
docker compose up -d --build --wait

4. Check that the gateway is licensed

If there is no licensed to line, the gateway did not start. See Troubleshooting.

shell
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.

shell
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"}, ...]
How calls are decided

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_ONLY tools run without a reviewer.
  • Anything else is held for a person. MUTATING, EGRESS and DESTRUCTIVE calls 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

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:

shell
docker compose run --rm --use-aliases -e DEMO_TOOL=workspace__archive_message \
    -e 'DEMO_ARGS={"message_id":"m1"}' agent

In a second terminal, from AgentGuard/sandbox, list the held calls and decide:

shell
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.com

The 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.

Your agents

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

shell
# 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 gateway

2. 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.

python
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.

shell
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 agent

4. 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.

text
# AgentGuard/sandbox/egress_proxy/allowlist.txt
api.anthropic.com:443 clients=agent
Your tools

Add your own MCP server.

Do this once the demo works.

  1. Run your server on mcp-net, so only the gateway can reach it, by adding a service to compose.yaml.
  2. 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.
  3. 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 the tools: list in AgentGuard/sandbox/sandbox.yaml on your machine, minus its first tools: line. Set trust: trusted only 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 named fetch_… is MUTATING, so each call waits for a reviewer. Name read-only tools get_… to have them run without one.
  4. Recreate the gateway and re-mint capabilities, since a capability names its tools when it is minted.
yaml · compose.yaml
  my-tools:
    image: your-mcp-server:tag
    networks: [mcp-net]
shell · pin
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
shell · approve
# 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.yaml
shell · reload
docker 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 demo
Observability

Watch 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.

shell · audit log
docker compose exec gateway tail -n 5 /var/lib/agentguard/gateway-audit.jsonl

Traces 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.

shell
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.

yaml
# 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 on

Stop and start again

To start again later, re-run quick start step 1 if the capability has expired, then docker compose up -d --wait.

shell
docker compose down          # stop; the audit log is kept
docker compose down -v       # stop and delete the audit log
Troubleshooting

If something does not work.

  • You see
    set AGENTGUARD_LICENSE_DIR to the directory with license.json and license.sig
    What it means
    AgentGuard/sandbox/.env is missing, or you ran the command from another directory.
    What to do
    Create .env (quick start, step 2) and run Compose from AgentGuard/sandbox.
  • You see
    The gateway exits at start with a licence error
    What it means
    The licence is expired, not yet valid, or the files are altered.
    What to do
    Contact us. Do not edit the licence files.
  • You see
    The gateway exits with a clock error
    What it means
    The system clock went back past the last recorded run (five minutes of slack is allowed).
    What to do
    Fix the system clock, then start the gateway again.
  • You see
    bind source path does not exist: .../identity/state/agents/<name>/...
    What it means
    The agent named by AGENT_NAME is not registered.
    What to do
    Run issue.py setup for that agent.
  • You see
    Calls are refused with an expired or invalid capability
    What it means
    The capability lasts one hour by default, or was minted for another run.
    What to do
    Re-run issue.py setup with --run equal to RUN_ID. Use --ttl (seconds) for a longer one.
  • You see
    MCPError: Server returned an error response
    What it means
    With 401 Unauthorized in docker compose logs gateway: the gateway refused the agent’s credentials. The audit log’s caller_refused record says why, most often no registered agent '<name>', because the agent was registered after the gateway started.
    What to do
    docker compose up -d --force-recreate --wait gateway. Otherwise re-run issue.py setup with --run equal to RUN_ID.
  • You see
    session halted after a prior denial
    What it means
    An 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 see
    A tool is missing from “tools exposed”
    What it means
    Its definition no longer matches its pin, so it is quarantined, or it is not in sandbox.yaml.
    What to do
    Check the gateway log, then re-pin the tool if the change was intended.
  • You see
    The agent’s model API calls fail with 403 Forbidden
    What it means
    The host is not in the egress allowlist, or the clients= rule did not match.
    What to do
    Add the host, restart egress-proxy, and use --use-aliases. Check docker compose logs egress-proxy.
Limits and renewals

What to expect.

  • Capabilities expire. A capability lasts one hour by default. Re-mint it with issue.py setup, or pass --ttl for 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.