Getting Started

Run the Ovara gateway locally and issue your first trust decision.

Run the gateway

git clone https://github.com/SidianLabs/OVARA.git
cd OVARA/runtime/gateway
go build -o ovara-gateway ./cmd/server
./ovara-gateway                              # uses etc/config.json
OVARA_CONFIG=./etc/config.json ./ovara-gateway

The gateway starts on :8080 with the bundled policy in etc/.

Your first decision

curl -X POST http://localhost:8080/v1/runtime/check \
  -H "Content-Type: application/json" \
  -d '{
    "action_type": "shell",
    "resource": "shell:git push origin main",
    "agent_identity": { "issuer": "ovara", "subject_id": "agt_001" },
    "environment": "dev"
  }'

The response is a decision: allow, deny, or escalate (human approval required).

Use the TypeScript SDK

Note: the SDK packages publish alongside the V1.0.0 release and are not on npm yet. Until then, use the gateway HTTP API above, or build the SDK from sdk/typescript in the repository.

# npm install @ovara/sdk   (publishing with V1.0.0)

import { OvaraClient } from '@ovara/sdk';

const client = new OvaraClient({
  baseUrl: 'http://localhost:8080',
  apiKey: process.env.OVARA_TOKEN,
});

const decision = await client.check({
  actionType: 'shell',
  resource: 'shell:git push origin main',
  environment: 'dev',
});

if (decision.decision === 'allow') { /* proceed */ }
if (decision.decision === 'escalate') { /* request approval */ }

// Convenience helpers on the client
await client.allow('shell', 'shell:git push origin main', 'dev');
await client.batchCheck([{ actionType: 'shell', resource: '...', environment: 'dev' }]);

Use the Python SDK

Note: ovara-sdk is not on PyPI yet - it publishes with the V1.0.0 release. Until then, build from sdk/python in the repository.

# pip install ovara-sdk   (publishing with V1.0.0)

from ovara_sdk import OvaraClient, ActionRequest

client = OvaraClient(base_url="http://localhost:8080", api_key="...")
decision = await client.check(
    ActionRequest(
        action_type="shell",
        resource="shell:git push origin main",
        environment="dev",
    )
)

# Convenience helpers on the client
await client.allow("shell", "shell:git push origin main", "dev")
await client.batch_check([ActionRequest(action_type="shell", resource="...")])

Verify offline

Both SDKs ship portable verification - check identities, leases, and receipts without talking to the gateway:

from ovara_sdk import (
    verify_agent_identity,
    verify_capability_lease,
    verify_receipt,
    is_lease_expired,
    scope_covers,
)

verify_receipt(receipt, gateway_public_key)   # ed25519, no gateway needed
verify_agent_identity(identity, public_key)
is_lease_expired(lease)
scope_covers(lease, "shell:git push")         # least-privilege check

Run the demos

cd examples
./start_gateway.sh        # in another terminal
./demo_safe_shell.sh
./demo_approval_flow.sh
./demo_restricted_agent.sh

demo_approval_flow.sh walks the full human-in-the-loop narrative: escalate, create approval, list pending, approve, resume, verify.

Decision latency

Benchmarked on Apple M4 hardware:

Operation	Latency
Policy-only decision	5,374 ns
Decision with identity	6,126 ns
Decision with anomaly	6,210 ns
Full identity + lease decision	7,669 ns
HMAC-SHA256 sign	598 ns
HMAC-SHA256 verify	614 ns

Sub-10μs decision path - fast enough for inline interception in agent workflows.