Installation

Via pip (recommended)

bash
pip install samma-suit

From source

bash
git clone https://github.com/OneZeroEight-ai/samma-suit.git
cd samma-suit
pip install -e .

Requires Python 3.10+. The SDK integrates with any FastAPI application via a single call:

python
from samma import SammaSuit

app = FastAPI()
SammaSuit(app)  # All 8 layers activated

Authentication

Samma Suit supports two authentication methods:

API Key

API keys use the samma_ prefix and are 56 hex characters. Include in the Authorization header:

http
Authorization: Bearer samma_a1b2c3d4e5f6...

You receive an API key when you create an account through the /api/billing/checkout endpoint.

Session Token (Magic Link)

For browser-based access, use the magic link flow:

  1. Send POST /api/auth/magic-link with your email
  2. Click the link in your email (contains a 15-minute token)
  3. The token is verified via POST /api/auth/verify
  4. You receive a 30-day session token

Quickstart

New here? Watch the 2-minute demo video to see all 8 layers in action before you start.

Get from zero to a protected AI agent in 4 commands.

1. Create an account

bash
curl -X POST https://sammasuit.com/api/billing/checkout \
  -H "Content-Type: application/json" \
  -d '{
    "email": "you@example.com",
    "tier": "pro",
    "success_url": "https://sammasuit.com/dashboard.html"
  }'

# Response: { "checkout_url": "...", "api_key": "samma_..." }

2. Create an agent

bash
curl -X POST https://sammasuit.com/api/agents \
  -H "Authorization: Bearer samma_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-first-agent",
    "monthly_budget_usd": 50.00,
    "llm_api_key": "sk-ant-..."
  }'

# Response: { "agent": { "id": "...", "name": "my-first-agent", "has_byok_key": true, ... } }

3. Send a request through the gateway

bash
curl -X POST https://sammasuit.com/api/agents/AGENT_ID/gateway \
  -H "Authorization: Bearer samma_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "Hello, agent!" }
    ]
  }'

# All 8 Samma layers enforced on every request

4. Check the audit log

bash
curl https://sammasuit.com/api/agents/AGENT_ID/audit?limit=10 \
  -H "Authorization: Bearer samma_YOUR_KEY"

# Every gateway call is logged with layers enforced, tokens, and cost

The 8 Layers

Every request through the Samma Suit gateway passes through all 8 layers. Each layer addresses a specific class of vulnerability exploited in the wild.

1

SUTRA

Gateway

The outermost defense. Validates request origins, enforces TLS 1.3, authenticates WebSocket connections, and applies rate limiting. Prevents the class of attacks demonstrated by CVE-2026-25253.

Prevents: Origin hijacking, replay attacks, DDoS, unauthorized gateway access

json — 429 rate limit
{ "detail": "Rate limit exceeded", "layer": "SUTRA" }
json — 403 origin
{ "detail": "Origin not allowed", "layer": "SUTRA" }
2

DHARMA

Permissions

Role-based access control for agents. Each agent is scoped to specific capabilities — an email agent cannot access the shell, a file agent cannot send messages. Prevents privilege escalation and lateral movement within agent roles.

Prevents: Privilege escalation, unauthorized model access, scope creep

json — 403 model not allowed
{ "detail": "Model 'claude-opus-4-6' not allowed for this agent role", "layer": "DHARMA" }
3

SANGHA

Skill Vetting

Curated skill marketplace with mandatory vetting. Every skill is scanned for malware, sandboxed, and reviewed before it can be installed. Directly addresses the ClawHavoc campaign that delivered 341 malicious skills.

Prevents: Malware injection, credential theft, supply chain attacks

json — 403 unvetted skill
{ "detail": "Skill not approved for installation", "layer": "SANGHA" }
4

KARMA

Cost Controls

Per-agent budget enforcement with token optimization. Prevents the $750/month runaway costs seen with uncontrolled heartbeat jobs. Each agent has a hard monthly budget cap that cannot be exceeded. Pro/Team customers can Bring Your Own Key (BYOK) for full spend control.

Prevents: Runaway API costs, budget overruns, token waste

json — 402 budget exceeded
{ "detail": "Monthly budget exceeded ($50.00/$50.00)", "layer": "KARMA" }
5

SILA

Audit Trail

Complete activity logging for every agent action. Records timestamps, tokens used, cost, IP addresses, and which layers were enforced. Provides the accountability that OpenClaw's zero-governance model completely lacks.

Prevents: Undetected rogue behavior, compliance gaps, forensic blind spots

json — 500 audit failure
{ "detail": "Audit log write failed — request blocked", "layer": "SILA" }
6

METTA

Identity

Cryptographic agent identity using Ed25519 key pairs. Every agent gets a unique keypair at creation. Responses are signed so you can verify they came from your agent and not an impersonator.

Prevents: Agent spoofing, impersonation, man-in-the-middle attacks

json — response fields
{
  "response": "...",
  "metta_signature": "a1b2c3d4...",
  "metta_public_key": "ed25519:..."
}
7

BODHI

Isolation

Process-level sandboxing for agent execution. Each agent runs in isolation with no lateral movement between agents. Egress allowlists prevent unauthorized network access. Enforces execution timeouts.

Prevents: Lateral movement, container escape, unauthorized network access

json — 504 timeout
{ "detail": "Agent execution timed out (30s)", "layer": "BODHI" }
8

NIRVANA

Recovery

The last line of defense. State snapshots, 1-click rollback, and kill switches. If an agent goes rogue, NIRVANA lets you immediately terminate it and restore to a known-good state. Includes dead man's switch for unresponsive agents.

Prevents: Uncontrolled rogue agents, state corruption, irreversible damage

json — 400 agent terminated
{ "detail": "Agent has been terminated via kill switch", "layer": "NIRVANA" }

API Reference

Base URL: https://sammasuit.com/api (production) or http://localhost:8001/api (local dev). All endpoints require authentication unless noted.

Authentication

POST /api/auth/magic-link
Send a magic link to the customer's email. Auto-creates a free-tier account if the customer doesn't exist.
Request / Response
json — request
{ "email": "you@example.com" }
json — response
{ "success": true, "message": "Magic link sent" }
POST /api/auth/verify
Validate a magic link token and create a 30-day session.
Request / Response
json — request
{ "token": "abc123..." }
json — response
{
  "success": true,
  "token": "session_token_here",
  "customer": {
    "id": "...",
    "email": "you@example.com",
    "tier": "pro"
  }
}
GET /api/auth/me
Return the current authenticated customer's profile, tier, and agent counts.
POST /api/auth/logout
Delete the current session.

Agents

POST /api/agents
Create a new agent. Checks tier limits and generates an Ed25519 keypair.
Request / Response
json — request
{
  "name": "my-agent",
  "description": "An email assistant",
  "monthly_budget_usd": 50.00,
  "llm_api_key": "sk-ant-...",
  "samma_config": {}
}
json — response
{
  "agent": {
    "id": "uuid",
    "name": "my-agent",
    "status": "active",
    "metta_public_key": "ed25519:...",
    "monthly_budget_usd": 50.00,
    "has_byok_key": true,
    "created_at": "2026-02-01T..."
  }
}
GET /api/agents
List all agents for the authenticated customer.
Response
json
{
  "agents": [ { "id": "...", "name": "...", "status": "active", ... } ],
  "total": 3,
  "max": 5
}
GET /api/agents/{agent_id}
Get full agent detail including Samma configuration.
PUT /api/agents/{agent_id}
Update agent name, description, budget, or Samma config.
DELETE /api/agents/{agent_id}
Soft-delete (terminate) an agent.
POST /api/agents/{agent_id}/pause
Pause an active agent. Cannot pause terminated agents.
POST /api/agents/{agent_id}/resume
Resume a paused agent.
POST /api/agents/{agent_id}/kill
NIRVANA kill switch — immediately and permanently terminate an agent.
Response
json
{ "success": true, "message": "Agent terminated", "layer": "NIRVANA" }
POST /api/agents/{agent_id}/gateway
Core product endpoint. Proxies messages to Claude API with full 8-layer Samma pipeline enforcement. Logs IP, user-agent, tokens, and cost.
Request / Response
json — request
{
  "messages": [
    { "role": "user", "content": "Summarize today's news" }
  ],
  "model": "claude-sonnet-4-5-20250929",
  "max_tokens": 1024,
  "system": "You are a helpful assistant."
}
json — response
{
  "content": "Here is today's summary...",
  "model": "claude-sonnet-4-5-20250929",
  "tokens_used": 342,
  "cost_usd": 0.0051,
  "layers_enforced": ["SUTRA","DHARMA","SANGHA","KARMA","SILA","METTA","BODHI","NIRVANA"],
  "metta_signature": "a1b2c3..."
}
GET /api/agents/{agent_id}/audit
Paginated audit log for a specific agent. Params: limit (max 100, default 50), offset.
Response
json
{
  "audit": [
    {
      "id": "...",
      "action": "gateway",
      "agent_name": "my-agent",
      "tokens_used": 342,
      "cost_usd": 0.0051,
      "layers_enforced": ["SUTRA","DHARMA","SANGHA","KARMA","SILA","METTA","BODHI","NIRVANA"],
      "created_at": "2026-02-01T12:00:00Z"
    }
  ],
  "total": 47
}

Dashboard

GET /api/dashboard/overview
Top-level dashboard data: tier, agent counts, monthly usage, and the last 10 audit entries.
Response
json
{
  "tier": "pro",
  "agents": { "active": 3, "total": 4, "max": 5 },
  "usage": {
    "total_cost_usd": 12.45,
    "monthly_budget_usd": 500,
    "total_calls": 1847
  },
  "recent_audit": [ ... ]
}
GET /api/dashboard/billing
Payment history and subscription details. Params: limit (max 100, default 20), offset.
GET /api/dashboard/costs
Per-agent cost breakdown for the current month with budget tracking.

Billing

POST /api/billing/checkout
Create a Stripe Checkout session for a subscription. Auto-creates customer and returns API key if new.
Request / Response
json — request
{
  "email": "you@example.com",
  "tier": "pro",
  "success_url": "https://sammasuit.com/dashboard.html",
  "cancel_url": "https://sammasuit.com/"
}
json — response
{
  "checkout_url": "https://checkout.stripe.com/...",
  "session_id": "cs_...",
  "customer_id": "uuid",
  "api_key": "samma_a1b2c3..."
}
GET /api/billing/portal
Create a Stripe Billing Portal session for managing subscriptions.
Response
json
{ "portal_url": "https://billing.stripe.com/..." }
GET /api/billing/status
Current subscription info, tier limits, and Stripe customer details.
POST /api/billing/link-wallet
Link a Polygon wallet via EIP-191 signature verification for SUTRA token payments.
Request
json
{ "wallet_address": "0x...", "signature": "0x..." }

Marketplace

GET /api/marketplace/skills
Browse approved skills. Params: q (search), free_only, status, limit, offset.
GET /api/marketplace/skills/{skill_id}
Get skill detail with full vetting status and manifest.
POST /api/marketplace/skills
Submit a new skill for SANGHA review. Validates manifest automatically.
Request
json
{
  "name": "Email Summarizer",
  "description": "Summarizes email threads",
  "package_url": "https://github.com/...",
  "manifest": { "permissions": ["email.read"] },
  "version": "1.0.0",
  "price_usd": 0
}
POST /api/marketplace/agents/{agent_id}/skills/{skill_id}/install
Install an approved skill on an agent. Checks ownership and prevents duplicates.

Configuration

Samma Suit is configured via environment variables. All variables use the SAMMA_ prefix.

Variable Required Description
ANTHROPIC_API_KEY Yes API key for Claude. Used by the gateway to proxy requests.
SAMMA_STRIPE_SECRET_KEY Yes Stripe secret key for billing and subscription management.
SAMMA_STRIPE_WEBHOOK_SECRET Yes Stripe webhook signing secret for verifying webhook events.
SAMMA_STRIPE_PRO_PRICE_ID Yes Stripe Price ID for the Pro tier ($29/mo).
SAMMA_STRIPE_TEAM_PRICE_ID Yes Stripe Price ID for the Team tier ($99/mo).
SAMMA_FROM_EMAIL Yes Sender email for magic links (e.g., noreply@sammasuit.com).
SAMMA_FRONTEND_URL Yes Frontend URL for magic link redirects (e.g., https://sammasuit.com).
RESEND_API_KEY Yes Resend API key for sending magic link emails.
DATABASE_URL No PostgreSQL connection string. Defaults to SQLite for local dev.
SAMMA_RATE_LIMIT No SUTRA layer rate limit per minute. Default: 60.
SAMMA_ALLOWED_ORIGINS No Comma-separated allowed origins for SUTRA validation.

FAQ

Is Samma Suit a fork of OpenClaw?
No. Samma Suit is built from scratch on a completely different architecture. OpenClaw's security problems are architectural — they can't be patched, they have to be redesigned. That's what Samma Suit does.
Can I self-host Samma Suit?
Yes. The Samma Suit SDK is open source and free forever. You can run all 8 layers on your own infrastructure. The paid tiers (Pro, Team, Enterprise) add managed hosting, a vetted skill marketplace, and premium support.
What models does the gateway support?
The gateway currently proxies to Anthropic's Claude API. The default model is claude-sonnet-4-5-20250929. The DHARMA layer controls which models each agent role is allowed to use. Multi-provider support is on the roadmap.
What is the SUTRA token?
SUTRA is an ERC-20 token on Polygon (contract: 0x0b3f81d3e1fa01e911a8b4e49048eea0ddf2a896). It powers OneZeroEight's music promotion economy and will extend into Samma Suit for subscription payments (20% discount), identity staking (METTA layer), skill developer rewards, and governance voting.
How are the 8 layers enforced?
Every request through the /api/agents/{id}/gateway endpoint passes through all 8 layers sequentially. Layers 1-2 (SUTRA + DHARMA) are fully production-hardened. Layers 3-8 are enforced with baseline implementations, with production-hardened versions shipping Q1-Q2 2026. No layer can be skipped or disabled.
What happens if my agent exceeds its budget?
The KARMA layer enforces a hard budget cap. When an agent's monthly spend reaches its budget limit, all subsequent gateway requests return a 402 error. You can increase the budget via the dashboard or API at any time. Pro/Team customers can also use BYOK (Bring Your Own Key) to supply their own Anthropic API key and control LLM spend directly.
How do kill switches work?
The NIRVANA layer provides immediate agent termination via POST /api/agents/{id}/kill or the Kill button in the dashboard. Terminated agents cannot be resumed — this is intentional. The kill switch is designed for emergency situations where an agent must be stopped immediately and permanently.