1 Install OpenLeash

The fastest way to get started is the one-liner install script, which installs Node.js (if needed) and the OpenLeash CLI globally:

    One-liner install 
 $ curl -fsSL https://openleash.ai/install.sh | bash 

Or install directly via npm:

    npm install 
 $ npm install -g @openleash/cli 

You can also run without installing using npx:

    npx (no install) 
 $ npx openleash start 

2 Run the Setup Wizard

The interactive wizard walks you through creating your first owner (that's you), registering an agent, and writing a starter policy:

    Interactive setup 
 $ npx openleash wizard 
   
  Welcome to OpenLeash! 
   
  ? Owner display name: Alice 
  ? Passphrase: •••••••• 
    Created owner: alice (a1b2c3d4-...) 
   
  ? Agent name: shopping-agent 
    Generated Ed25519 keypair 
    Created agent: shopping-agent (e5f6g7h8-...) 
   
  ? Create a starter policy? Yes 
    Created policy: default-policy.yaml 
   
  Setup complete. Run `npx openleash start` to begin. 

The wizard creates files in a ./data/ directory: your owner profile, agent registration (with Ed25519 keys), and the starter policy. Everything is local files — no database, no cloud dependency.

Prefer non-interactive setup? Use npx openleash init instead.

3 Start the Server

Start the authorization sidecar. It runs a local HTTP server with a built-in web GUI for managing agents, policies, approvals, and audit logs:

    Start the server 
 $ npx openleash start 
   
  OpenLeash v0.14.0 
  Server listening on http://127.0.0.1:8787 
  GUI available at http://127.0.0.1:8787/gui 

Open http://127.0.0.1:8787/gui in your browser to access the owner portal. Log in with the passphrase you set during the wizard.

4 Write a Policy

Policies are YAML files that define what your agent is allowed to do. Here's a policy that allows purchases under $100 and requires approval for anything higher:

    policies/spending-limits.yaml 
  name: spending-limits 
  description: Spending controls for the shopping agent 
  rules: 
    - action_type: purchase 
      decision: ALLOW 
      conditions: 
        - expression: "action.payload.cost <= 100" 
   
    - action_type: purchase 
      decision: REQUIRE_APPROVAL 
      conditions: 
        - expression: "action.payload.cost > 100" 
      obligations: 
        - type: HUMAN_APPROVAL 
          config: 
            notify: true 
            timeout_minutes: 60 

Add the policy using the CLI:

    Add the policy 
 $ npx openleash policy upsert ./policies/spending-limits.yaml 

You can test the policy against sample scenarios before deploying:

    Test with the playground 
 $ npx openleash playground run spending-check 

5 Authorize an Action

Install the SDK in your agent's project and call authorize() before performing any risky action:

    Install the SDK 
 $ npm install @openleash/sdk-ts 

    authorize.ts 
  import { authorize } from "@openleash/sdk-ts"; 
   
  const result = await authorize({ 
    openleashUrl: "http://127.0.0.1:8787", 
    agentId: "", 
    privateKeyB64: process.env.OPENLEASH_AGENT_PRIVATE_KEY_B64!, 
    action: { 
      action_id: crypto.randomUUID(), 
      action_type: "purchase", 
      requested_at: new Date().toISOString(), 
      principal: { agent_id: "" }, 
      subject: { principal_id: "" }, 
      relying_party: { domain: "store.example.com", trust_profile: "LOW" }, 
      payload: { item: "headphones", cost: 45 } 
    } 
  }); 
   
  if (result.decision === "ALLOW") { 
    // Proceed with the purchase, pass proof_token to the counterparty 
    console.log("Authorized:", result.proof_token); 
  } else if (result.decision === "REQUIRE_APPROVAL") { 
    // Wait for owner approval 
    console.log("Waiting for approval..."); 
  } 

The proof_token is a PASETO v4.public token — a cryptographically signed proof that this specific action was authorized by the owner. SDKs are also available for Python and Go.

6 Verify the Proof

The counterparty (the service receiving the agent's request) can verify the proof token offline using the owner's public key:

    verify.ts (counterparty side) 
  import { verifyProofOffline } from "@openleash/sdk-ts"; 
   
  const verification = await verifyProofOffline({ 
    token: proofToken, 
    publicKeys: [{ 
      kid: "key-id", 
      public_key_b64: "..."  // from GET /v1/public-keys 
    }] 
  }); 
   
  if (verification.valid) { 
    console.log("Action type:", verification.claims.action_type); 
    console.log("Agent:", verification.claims.agent_id); 
    console.log("Decision:", verification.claims.decision); 
  } 

No callback to OpenLeash is required — verification is entirely offline using Ed25519 public key cryptography.

Next Steps

Documentation — Full policy language reference, API endpoints, and CLI commands
Policy Playground — Test policies against scenarios before deploying
What is AI Agent Authorization? — Deep dive into the concepts
AI Agent Guardrails — Types of controls for autonomous agents
PASETO Proof Tokens — How the cryptographic proof system works
Use Cases — Real-world scenarios and FAQ