Your first governed agent in 5 minutes

Start a local MAQPNA, make an allowed and a denied tool call, hold one for approval, and read the session timeline and audit ledger.

flowchart LR
    A["maqpna dev up<br/>broker, gateway, echo"] --> B["maqpna dev run --<br/>maqpna call ..."]
    B --> C{"gateway<br/>decision"}
    C -->|allowed| D["tool result"]
    C -->|denied| E["error -32001<br/>exit status 3"]
    C -->|held for approval| F["maqpna approvals<br/>approve / deny"]
    D --> G["maqpna dev timeline --last"]
    E --> G
    F --> G
    G --> H["maqpna audit verify"]

Goal#

Run a local MAQPNA on your laptop and watch the MAQPNA gateway decide three tool calls: one allowed, one denied by policy and one held for a human approval. Then read what the session did in its timeline and prove the audit ledger is intact. No Kubernetes, no GPU and no API key are needed.

Prerequisites#

• macOS, Linux or Windows, with ports 8080, 8081 and 8090 free (8000 too if you add --stub-llm).
• The maqpna CLI:

curl -fsSL https://maqpna.com/install.sh | sh     # macOS and Linux
irm https://maqpna.com/install.ps1 | iex           # or Windows PowerShell

More install options: maqpna.com/download.

The first maqpna dev up downloads maqpna-gateway and maqpna-identity of the same version from the release and checks them against its checksums.txt (and their cosign signatures when cosign is installed). In a source checkout, add --from-source to build them with go build instead. - A terminal in an empty working directory. maqpna dev keeps its state (keys, configuration, ledger, logs) in ./.maqpna.

Steps#

1. Start a local MAQPNA#

maqpna dev up --stub-llm

✓ local MAQPNA started (900ms)
local MAQPNA is up (~/maqpna-demo/.maqpna)
  gateway   http://127.0.0.1:8080
  broker    http://127.0.0.1:8081
  mcp       echo -> http://127.0.0.1:8090/mcp
  model     stub -> http://127.0.0.1:8080/llm/stub/v1 (OpenAI base URL)
next: maqpna dev run -- <your agent command>

This starts, on 127.0.0.1:

The gateway loads the built-in dev policy (.maqpna/policies.json). It has two policies, baseline-guardrails and default-agent-policy, whose rules you meet in the next steps.

2. Make an allowed call#

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

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

maqpna dev: session dev-786a4a69 (agent coder, namespace dev, on behalf of you@localhost)
{
  "content": [
    {
      "text": "hello",
      "type": "text"
    }
  ],
  "isError": false
}
maqpna dev: dev-786a4a69: 1 allow, cost $0.0000 (maqpna dev timeline --last)

The session is dev-786a4a69: agent coder in namespace dev, acting for you@localhost. Change these with --agent, --namespace, --user and --session.

3. Make a denied call#

Rule never-touch-system-namespaces denies any tool call with a namespace argument that matches kube-*:

maqpna dev run -- maqpna call --server echo --tool delete_resource --arg id=db-1 --arg namespace=kube-system
echo "exit status $?"

maqpna dev: session dev-aa0511c1 (agent coder, namespace dev, on behalf of you@localhost)
error -32001: denied by policy baseline-guardrails rule never-touch-system-namespaces: system namespaces are off-limits to agents
data: {"detail":"system namespaces are off-limits to agents","domain":"maqpna.com","policy":"baseline-guardrails","reason":"policy_denied","rule":"never-touch-system-namespaces"}
maqpna dev: dev-aa0511c1: 1 deny, cost $0.0000 (maqpna dev timeline --last)
exit status 3

The denial is a JSON-RPC error -32001 that names the policy, the rule and the reason. The tool never ran. maqpna call exits with status 3 whenever the gateway refuses a call. The SDKs raise PolicyDenied with the same fields (see Error and reason codes).

4. Hold a call for approval#

Rule destructive-needs-human in default-agent-policy requires approval for delete_*, drop_*, deploy_* and other high-impact tools. Outside a system namespace, the same delete now waits for a person:

maqpna dev run -- maqpna call --server echo --tool delete_resource --arg id=db-1 --arg namespace=dev

The command waits. In a second terminal in the same directory, load the local admin token and list the pending approvals:

eval "$(maqpna dev env)"
maqpna approvals list

ID                           STATUS    NAMESPACE      AGENT          TOOL                     REASON
apr_902e3a670541349ffc7844a3 pending   dev            coder          echo/delete_resource     destructive or high-impact operation

Approve it as someone else. Approvers cannot approve calls made on their own behalf, so give a different name:

maqpna approvals approve apr_902e3a670541349ffc7844a3 --approver reviewer@localhost --note "test resource"

The held call in the first terminal runs and prints its result:

{
  "content": [
    {
      "text": "deleted resource db-1 in namespace dev (simulated)",
      "type": "text"
    }
  ],
  "isError": false
}

Run maqpna approvals deny ID --approver reviewer@localhost --note "..." instead, and the agent gets -32001 with reason approval_denied. The local gateway expires a pending approval after five minutes; maqpna call waits a little longer (--timeout, default 5m30s), so it ends with the decision or the expiry. To approve from a window instead of the CLI, run maqpna desk (see Human approvals).

MAQPNA Desk (maqpna desk) with two held calls. Light theme.

5. Read the timeline#

maqpna dev timeline --last

TIME      KIND       SERVER/TOOL           DECISION  DETAIL
00:11:20  tool_call  echo/delete_resource  deny      system namespaces are off-limits to agents
dev-aa0511c1: 1 deny, cost $0.0000 (maqpna dev timeline --last)

--last is the most recent maqpna dev run session. Any other session works with --session ID, and -o json prints every field. The timeline is the ledger-ordered view of one session: tool calls, model calls, approvals and the result the agent reported.

The console shows the same timeline, with the decision, rule and token usage of every step. Open it with maqpna console: run maqpna console --gateway http://127.0.0.1:8080 --open, then in Settings enter the console's own address, http://127.0.0.1:8088 (it proxies the gateway's admin API), and the MAQPNA_ADMIN_TOKEN value from maqpna dev env:

The console's session page. Light theme.

6. Verify the audit ledger#

Every decision is appended to a hash-chained audit ledger. Recompute the chain:

maqpna audit verify .maqpna/audit.jsonl

OK: 2 records, hash chain intact

Change or delete one line of a copy of the file and run it again: audit verify prints TAMPERED: chain breaks at seq N and exits with status 3. See Audit.

7. Stop it#

maqpna dev down

The state and the ledger stay in .maqpna/. The next maqpna dev up reuses the directory.

Verify#

You are done when:

• maqpna dev status lists maqpna-gateway, maqpna-identity and mcp-echo as running and the gateway as ready=true (before step 7).
• The allowed call printed a result and the denied call exited with status 3.
• maqpna audit verify .maqpna/audit.jsonl printed OK.

Troubleshooting#

More symptoms and fixes are in Troubleshooting.

Next steps#

• Run your own agent in Python, TypeScript or Go under maqpna dev run.
• Use a framework template: LangGraph, OpenAI Agents SDK or Claude Agent SDK.
• Write policies and test them with maqpna policy test.
• Human approvals with MAQPNA Desk and the console.