Skip to content

Getting Started

This guide takes you from nothing to a working allow and a working deny in a few minutes. You will write a Build Intent Manifest (BIM), sign it, and judge two outbound requests against it.

1. Build the CLI

cargo build --release --workspace
export PATH="$PWD/target/release:$PATH"   # so `pimatika-cli` is on the path

2. Provide a signing key

Pimatika signs and verifies the BIM with a keyed-BLAKE3 MAC. There is no auto-generated key — you must supply one. The quickest way for a first run:

export LITATOLI_SIGNING_KEY=$(python3 -c "print('ab'*32)")   # 64 hex chars = 32 bytes

In production, set LITATOLI_SIGNING_KEY (or a key file) to a real secret. See Reference for the full resolution order.

3. Write a draft BIM

A BIM is a signed YAML document declaring exactly which outbound targets a workload may reach. Save this as bim.draft.yaml — one contract, and a default_policy of DENY:

bim_version: '0.1'
runtime_identity:
  runtime_type: python
  runtime_version: '3.12'
  runtime_digest: blake3:0000000000000000000000000000000000000000000000000000000000000000
  sandbox: nazelo
workload_identity:
  service_name: my-agent
  code_digest: blake3:0000000000000000000000000000000000000000000000000000000000000000
  config_digest: blake3:0000000000000000000000000000000000000000000000000000000000000000
  dependency_digest: blake3:0000000000000000000000000000000000000000000000000000000000000000
  model_digest: blake3:0000000000000000000000000000000000000000000000000000000000000000
component_scope:
  owner: demo
  environment: test
  criticality: high
  trust_tier: 1
attestation_proof:
  evidence_ref: getting-started
  merkle_root: blake3:0000000000000000000000000000000000000000000000000000000000000000
  muundo_digest: blake3:0000000000000000000000000000000000000000000000000000000000000000
  signed_at: 2026-08-01T00:00:00Z
policy_identity:
  signer_id: getting-started-signer
  trust_anchor: demo-root
intent_profile:
  usage_contracts:
    - name: reference-data
      target: https://api.github.com
      purpose: fetch reference data
      data_class: public
      allowed_methods: [GET]
      max_payload_kb: 8
runtime_capabilities:
  network_egress:
    default_policy: DENY

The one contract permits GET requests to https://api.github.com, up to 8 KB, for the stated purpose and data class. Nothing else is allowed.

The digest and identity fields above use placeholder zeros so the guide runs. A real BIM fills them in — and if you leave purpose, data_class, or max_payload_kb as the literal HUMAN_REQUIRED, or an identity field as PLACEHOLDER, the BIM is rejected at load. A human must complete a draft before it is signed.

4. Sign it

sign-bim computes the digest and the MAC and writes a signed BIM:

pimatika-cli sign-bim --bim bim.draft.yaml --out bim.yaml
pimatika-cli verify-bim --bim bim.yaml     # prints "ok"

5. Run an ALLOW

Feed a request that matches the contract on stdin as JSON:

echo '{"workload_id":"my-agent","target":"https://api.github.com","method":"GET","payload_kb":2,"purpose":"fetch reference data","data_class":"public"}' \
  | pimatika-cli check --bim bim.yaml

The printed EgressDecision has event_type: "EGRESS_ALLOWED". The host process would now proceed with the call.

6. Run a DENY

Now ask about a target the BIM does not name:

echo '{"workload_id":"my-agent","target":"https://pypi.org","method":"GET","payload_kb":2,"purpose":"fetch reference data","data_class":"public"}' \
  | pimatika-cli check --bim bim.yaml

This time event_type is "EGRESS_DENIED" and decision_reason is TARGET_NOT_IN_USAGE_CONTRACTS. The host process would abort the call.

Try other denials by changing one field of the allowed request:

  • "method":"POST" → METHOD_NOT_ALLOWED (only GET is declared)
  • "payload_kb":99 → PAYLOAD_EXCEEDS_LIMIT (the ceiling is 8)
  • "purpose":"exfiltrate" → PURPOSE_MISMATCH
  • "data_class":"secret" → DATA_CLASS_MISMATCH

Each decision is also written to a chain-linked evidence log at .jagora/evidence/pimatika-egress.jsonl (override with --log-file).

Next steps

  • Reference — every CLI sub-command, the pimatika-core library API, and signing-key resolution.
  • Architecture — the BIM schema in full, the enforcer call-flow, all DecisionReason values, and drift/JAQ overlays.
  • Python binding — judge egress in-process from Python instead of shelling out to the CLI.