Run it on your own machine
This walkthrough uses
test:fixture-execute, a generic, credential-free
capability built for local testing. It’s evaluated against a policy named
vendor-payment. That policy name is unrelated to any connector; it’s simply
the example policy this transaction runs against. SignalIntentBinder rejects
a transaction whose declared vendorId signal doesn’t exactly match its
intent.target (see Policies and the
decision), so the execute step below
sets both to the same value. Code samples below are shown for Python and
TypeScript. Pick whichever matches your client.parmana-local/api-key.txt.
The demo key used below is accepted only by the server started from source, so use the key from
that file in its place when you run the Docker server. For the full setup, including the approver
key, see Self hosted.
1
Install and build
.env.example is in the repository; .env is gitignored and holds your local settings.2
Generate the local signing keys
The server signs authorizations and records with the This writes
default key, and the Execution Gateway
signs its own attestations with a separate gateway key. keys/ is gitignored, so a fresh
clone has neither. Create both:keys/default.private.pem, keys/default.public.pem, keys/gateway.private.pem
and keys/gateway.public.pem. They stay local. See Deploy patterns
for how to manage keys outside local dev.3
Make a local approver key
~/.parmana/local-test-approver__local-test-approver-key-1.private.pem (keep it)
and .public.pem (the server trusts it in the next step).4
Start the Runtime locally
This step sets four variables.
NODE_ENV=test and PARMANA_STORAGE=memory let the server run
without a database. They are for this local run only, and a real deployment must not use them.The .env copied from .env.example defaults to PostgreSQL storage (PARMANA_STORAGE=supabase,
which is an alias for postgres). To run fully locally with no external dependency, override storage
to memory and set NODE_ENV=test. Both are required: PARMANA_STORAGE=memory alone only affects
where Business Transactions and Trust Records are stored, two other components, the Execution
Gateway’s replay-nonce store and the caller-authentication audit trail, independently require a
PostgreSQL database (DATABASE_URL) outside NODE_ENV=test.
With NODE_ENV=test, a generic, test-only connector (test-fixture) registers
automatically, no credential environment variable required, and the server trusts
local-test-approver with the key in PARMANA_TEST_APPROVER_PUBLIC_KEY_FILE:PARMANA_TEST_APPROVER_PUBLIC_KEY_FILE is honored only when NODE_ENV is test. With any
other NODE_ENV the server refuses to start while it is set.Confirm it’s up:The Execution Gateway is wired into this server unconditionally. Every
POST /execute is independently re-verified and routed through a real Connector. An
action with no registered connector fails closed with "No connector registered for action", it does not silently skip enforcement. See The
gateway.5
Authenticate (optional): every other route requires a bearer key
You can skip this step. The SDK calls in the next steps send the key for you.The This is real, fail-closed authentication, not a placeholder, see
Authentication for how keys are minted and rotated outside
this demo key.
/health is the one route exempt from caller authentication (along with /ready,
/openapi.yaml, /openapi.json, /api-manifest.json, /documentation, and
/reference). Everything else, including /version, fails closed with a 401 before a
Business Transaction is even constructed:PARMANA_API_KEYS entry in the previous step is a demo caller key for local development
only: callerId: "demo", raw key my-secret-api-key, allowed to use test:fixture-execute
and to act as demo (only its SHA-256 hash is stored, see
Authentication). Its raw key is public, so never use it on a
server anyone else can reach; make real keys with npm run generate:api-key. Send it as a
bearer token and the same route succeeds:6
Install the SDK
7
Sign an approval, then execute a Business Transaction
First the approver signs an approval for this action, this target, up to this amount. Then
the agent sends the transaction with the approval attached. The The
createBusinessTransaction
helper derives every id pair the server checks for consistency, so there’s nothing to
hand-assemble and get wrong:signals are the facts the policy checks before it approves. This quickstart sets them for you.
You don’t need to change them to get the first approved action.Without humanApproved and a valid approvalArtifact, the server refuses this transaction
with 403 POLICY_DENIED, whatever else the signals say.Full runnable versions: python/examples/quickstart/run.py and
typescript/examples/06-create-business-transaction.ts, the same transactions run against a
test server with authentication off, so they act as other principals; each takes the signed approval as an argument, or from the file
PARMANA_APPROVAL_FILE names when run as a script. python/tests/test_quickstart_example.py and
typescript/test/integration/examples.integration.test.ts run them against a real,
freshly-spawned server on every test run, so both examples are verified to work, not just
syntax-checked. The two samples above were run as shown, with the demo key, against a server started as in step 4.8
Real output
Captured from an actual run against a local server, 2026-09-14:The full
ExecutionTrustRecord includes the signature block, executions[0].decision
(outcome: "APPROVED", evaluated by the vendor-payment policy), executions[0].evidence
(what the connector actually did, including a connectorEvidenceHash), and an initial
verifications / receipts history. See Trust Record for the
complete shape, or python/examples/quickstart/README.md for the full captured JSON. For
the equivalent captured TypeScript output (camelCase field names, same record shape), see
TypeScript SDK Quickstart’s own “Real output” step.Next
Integrate an agent
Connect an agent to a Parmana server you run, with the approval flow.
How Parmana thinks
The concepts behind what just happened: policy, authorization, the gateway,
trust records.
Verify & replay
Read back or re-run verification against the record you just created.