MAQPNADocs

Quickstart

Start a local MAQPNA, make a governed tool call through its gateway, and see the decision, in three commands and no cluster.

This takes about five minutes on macOS, Linux or Windows. You need the CLI (Install); you do not need Kubernetes, a GPU or an API key.

1. Start a local MAQPNA#

maqpna dev up

This starts, on your machine:

  • the identity broker on port 8081, which mints session tokens;
  • the gateway on port 8080, with a starter policy and an audit ledger in ./.maqpna;
  • echo, a test MCP server with the tools echo, get_time and delete_resource.

Add --stub-llm for a scripted OpenAI-compatible model as well, as in the recording. On first use, maqpna dev up downloads the matching maqpna-gateway and maqpna-identity and checks them against the release's checksums.

maqpna dev up.cast

2. Make a governed tool call#

maqpna dev run runs a command as an agent session: it mints a session token from the local broker and gives the command the same environment a sandbox gets in a cluster. maqpna call makes one tool call through the gateway with that token.

maqpna dev run -- maqpna call --server echo --tool echo --arg text=hello

The starter policy allows echo (rule read-only-tools), so the call reaches the MCP server and its result comes back.

maqpna dev run.cast

Now try a call the policy does not allow. Rule never-touch-system-namespaces denies any tool that targets a kube-* namespace, and the gateway says which rule did it:

maqpna dev run -- maqpna call --server echo --tool delete_resource --arg namespace=kube-system --arg id=coredns
maqpna call.cast

3. See what the session did#

maqpna dev timeline --last

maqpna dev timeline lists each call of the last session, with the decision and the policy and rule that made it. The same records are in the audit ledger, ./.maqpna/audit.jsonl, which maqpna audit verify checks for tampering.

maqpna dev timeline.cast

Next#

  • Hold a call for a person: delete_resource in any other namespace needs approval (rule destructive-needs-human). Make the call, then approve it from a second terminal with maqpna approvals after eval "$(maqpna dev env)".
  • Run your own agent under MAQPNA: maqpna dev run -- python agent.py.
  • Test a policy change before you ship it, with maqpna policy test and maqpna replay.
  • Stop the local MAQPNA with maqpna dev down. The ledger stays in ./.maqpna.