Set up your development environment

Install the maqpna CLI, start a local MAQPNA with maqpna dev up, check it, use contexts and MAQPNA Desk, and tear it down.

A local MAQPNA is the laptop stack that maqpna dev up starts: the identity broker, the MAQPNA gateway and a test Model Context Protocol (MCP) server, with no Kubernetes. Your agent runs under maqpna dev run and gets the same environment variables and the same kind of session token as in a cluster sandbox, so every call it makes is governed for real.

flowchart LR
    CLI["maqpna dev up"] --> ID["maqpna-identity<br/>:8081"]
    CLI --> GW["maqpna-gateway<br/>:8080"]
    CLI --> EC["mcp-echo<br/>:8090"]
    CLI -.->|"--stub-llm"| ST["stub-llm<br/>:8000"]
    RUN["maqpna dev run -- CMD"] -->|"mint token"| ID
    RUN --> AG["your agent"]
    AG -->|"Bearer token"| GW
    GW --> EC
    GW -.-> ST
    GW --> L[(".maqpna/audit.jsonl")]

Prerequisites#

• macOS, Linux or Windows.
• Ports 8080, 8081 and 8090 free (and 8000 if you use --stub-llm). Every port has a flag if one is taken.
• For the SDKs: Python 3.10+, Node.js 20.3+ or Go 1.24+.

Step 1: Install the CLI#

curl -fsSL https://maqpna.com/install.sh | sh

curl -fsSL https://maqpna.com/install.sh | sh
# or pin the version, install only the CLI, choose the directory, require a signature
curl -fsSL https://maqpna.com/install.sh | sh -s -- --version v2.1.0 --bin maqpna --dir "$HOME/.local/bin" --cosign

irm https://maqpna.com/install.ps1 | iex

Check it:

maqpna version

More options, including air-gapped installs, are in Install. Turn on tab completion with maqpna completion.

Step 2: Start a local MAQPNA#

Create a working directory for your agent project and start the stack there. maqpna dev keeps its state in ./.maqpna: keys, gateway configuration, the policy bundle, the audit ledger and logs.

mkdir triage-agent && cd triage-agent
maqpna dev up --stub-llm

local MAQPNA is up (~/triage-agent/.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>

The first run downloads maqpna-gateway and maqpna-identity of the same version as the CLI, unless they are already next to maqpna or on your PATH. In a source checkout, --from-source builds them instead.

The flags you use most as a developer:

The full list is in maqpna dev up.

Step 3: Check that it works#

maqpna dev status

maqpna-gateway   pid 94207   running
maqpna-identity  pid 94206   running
mcp-echo         pid 94194   running
stub-llm         pid 94195   running
gateway http://127.0.0.1:8080 ready=true

Then make one governed call. maqpna dev run mints a session token and runs a command with it; maqpna call makes one tool call:

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

The call prints the tool result and maqpna dev run prints a summary such as dev-786a4a69: 1 allow, cost $0.0000. If you see that, the broker, the gateway, the policy and the ledger all work.

maqpna doctor --gateway http://127.0.0.1:8080 --component gateway also works against a local gateway. It reports FAIL and WARN for settings that are fine on a laptop but not in production (static admin token, unsigned checkpoints, file state backend) and exits with status 3. Use it to learn the production settings, not as a local health check.

Step 4: Load the admin token for local commands#

Commands that use the gateway's admin API (approvals, audit tail, revocations, MCP pins) need the local admin token. Load it into your shell:

eval "$(maqpna dev env)"

It exports MAQPNA_GATEWAY_URL, MAQPNA_GATEWAY, MAQPNA_ADMIN_TOKEN, MAQPNA_BROKER_URL and MAQPNA_BROKER_TOKEN. Check what the gateway sees:

maqpna whoami

FIELD      VALUE
gateway    http://127.0.0.1:8080
context    -
auth mode  token
user       token
kind       token
issuer     urn:maqpna:admin-token
roles      admin, approver, audit-forwarder, auditor, killswitch, viewer
groups     -

Step 5: Use contexts for more than one installation#

A context names a gateway URL, a kube context and a default namespace, so you can switch between your laptop and a shared cluster without retyping flags. Contexts live in ~/.config/maqpna/config.yaml (or $MAQPNA_CONFIG); the file holds no secrets.

maqpna context set local --gateway http://127.0.0.1:8080 --namespace dev --use
maqpna context set staging --gateway https://gateway.staging.example.eu --kube-context staging-eu --namespace team-a
maqpna context list

CURRENT  NAME   GATEWAY                KUBE-CONTEXT  NAMESPACE  LOGGED-IN
*        local  http://127.0.0.1:8080  -             dev        no

For a shared installation, log in once per context; the access token is stored next to the config file with mode 0600:

maqpna login --context staging
maqpna --context staging whoami

See maqpna context and maqpna login.

Step 6: Open MAQPNA Desk#

MAQPNA Desk is the approvals inbox and the dev window. Its Local (dev) window starts and stops the local MAQPNA and follows the live timeline of the last maqpna dev run session.

maqpna desk

It serves on 127.0.0.1 with a per-launch token and opens your browser. For the web console instead, run maqpna console --gateway http://127.0.0.1:8080 --open. See Human approvals and Console and Desk.

Step 7: Tear it down#

maqpna dev down

The state and the audit ledger stay in .maqpna/; the next maqpna dev up in the same directory reuses them. Delete .maqpna/ to start from scratch, and add it to your .gitignore: it contains the local signing key and admin token.

What can go wrong#

Next steps#

• Anatomy of an agent project
• Connect to the gateway
• Local dev loop flow, for what maqpna dev does inside
• maqpna dev run reference