Quickstart

Get from install to your first authorization decision in under five minutes.

You need Node.js 18+ and npm or pnpm before starting.

Install the CLI

npm install -g shotoku-cli

This installs the shotoku command globally. The core library (@shotoku/core) is also available separately if you want to call authorize() directly from your agent code.

Initialize

shotoku init

This creates three things in your current directory:

• shotoku.config.json — runtime config (policy path, ledger path)
• policy.yaml — your authorization rules
• data/ — directory where decisions are stored locally

Define your policy

Open policy.yaml and define which resources your agents are allowed to access. Anything not on the allowlist goes to pending_approval. Anything that exceeds a limit is denied.

version: 1
allowlist:
  - resource: "api.openai.com"
    actions: ["api_call"]
    limits:
      per_request: 5.00
      daily: 50.00

  - resource: "api.anthropic.com"
    actions: ["api_call"]
    limits:
      per_request: 2.00
      daily: 20.00

The daily limit is computed from the rolling 24-hour window in the local ledger — not a calendar day.

Call authorize() in your agent

Before your agent takes an action, call authorize(). It evaluates the request against your policy and the local ledger, writes the decision, and returns the result.

import { authorize } from "@shotoku/core";

const response = await authorize(
  {
    actor:    "agent-001",
    action:   "api_call",
    resource: "api.openai.com",
    amount:   0.04,
  },
  {
    policyPath: "./policy.yaml",
    ledgerPath: "./data/decisions.jsonl",
  },
);

if (response.approved) {
  // safe to proceed
  await callOpenAI(prompt);
}

Shotoku fails closed. If the policy file is missing or the request is malformed, the response is denied — it never defaults to approved.

Try it from the CLI

You can also authorize directly from the terminal — useful for testing policies before wiring them into agent code.

shotoku authorize \
  --actor agent-001 \
  --action api_call \
  --resource api.openai.com \
  --amount 0.04

✓ Approved  dec_abc123
  • api.openai.com is allowlisted
  • Daily budget remaining: $49.96
  • Transaction below $5.00 limit
  Recorded at 14:05:22

Handle pending approvals

When an agent tries to reach a resource not on your allowlist, Shotoku records it as pending_approval and waits for a human decision.

shotoku status

Pending Approval  dec_ghi789  • vendor-xyz.com is not on the allowlist  • A human must approve this decision  → Run: shotoku approve dec_ghi789

shotoku approve dec_ghi789
# → ✓ Approved. Recorded as apr_xxx.

shotoku deny dec_ghi789
# → ✗ Denied. Recorded as den_xxx.

Quick links