Developer documentation

CAIN Control

Last reviewed 31 August 2026

CAIN Control Documentation

Status: PRODUCTION

CAIN Control is production-ready. It provides the authorization layer that answers WHAT an actor is allowed to do, UNDER WHAT CONDITIONS, and WHO CAN STOP IT.

What is CAIN Control?

CAIN Control is the permission and control layer for CAIN Trust Fabric:

• CAIN Identity answers: WHO is acting?
• CAIN Control answers: WHAT is that actor allowed to do, and WHO CAN STOP IT?

IDENTITY → CONTROL → POLICY → RISK → DECISION → ENFORCEMENT → ACTION → EVIDENCE

Core Capabilities

Agent Controls

• Pause / resume / kill agents
• Set action frequency limits
• Set concurrent action limits
• View agent control status

Tool Controls

• Enable / disable tools
• Set risk levels
• Require approval for high-risk tools
• Restrict tools to specific agents
• Restrict tools to specific identities
• Associate tools with policies

Policy Management

• Create / update / version policies
• Activate / deactivate policies
• Rollback to previous versions
• Full policy audit history

Kill Switch

• Tenant-wide emergency stop
• Immediately blocks all consequential actions
• Cannot be bypassed

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                     CAIN Control                                  │
├─────────────────────────────────────────────────────────────────┤
│  Control Engine                                                  │
│  ├── Agent state management (active/paused/killed)              │
│  ├── Tool enable/disable                                        │
│  ├── Policy evaluation                                          │
│  ├── Kill switch                                                │
│  └── Rate limiting                                              │
│                                                                  │
│  Control API                                                    │
│  ├── /fabric/control/agents/*    - Agent controls              │
│  ├── /fabric/control/tools/*     - Tool controls                │
│  ├── /fabric/control/policies/* - Policy management            │
│  ├── /fabric/control/kill-switch - Emergency stop              │
│  └── /fabric/control/evaluate    - Control decisions           │
│                                                                  │
│  Integration                                                    │
│  └── CAIN Identity → CAIN Control → CAIN Enforcement           │
└─────────────────────────────────────────────────────────────────┘

API Reference

Kill Switch

# Check kill switch status
curl https://cainstudio.online/fabric/control/kill-switch \
  -H "X-API-Key: your-key"

# Activate kill switch
curl -X POST https://cainstudio.online/fabric/control/kill-switch/activate \
  -H "X-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{"reason": "security incident"}'

# Deactivate kill switch
curl -X POST https://cainstudio.online/fabric/control/kill-switch/deactivate \
  -H "X-API-Key: your-key"

Agent Controls

# Pause an agent
curl -X POST https://cainstudio.online/fabric/control/agents/agent:xxx/pause \
  -H "X-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{"reason": "maintenance"}'

# Resume an agent
curl -X POST https://cainstudio.online/fabric/control/agents/agent:xxx/resume \
  -H "X-API-Key: your-key"

# Kill an agent (permanent)
curl -X POST https://cainstudio.online/fabric/control/agents/agent:xxx/kill \
  -H "X-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{"reason": "compromised"}'

# List agent controls
curl https://cainstudio.online/fabric/control/agents \
  -H "X-API-Key: your-key"

Tool Controls

# Create tool control
curl -X POST https://cainstudio.online/fabric/control/tools/my-tool \
  -H "X-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "risk_level": "high",
    "requires_approval": true,
    "allowed_agents": ["agent:xxx"],
    "allowed_identities": ["urn:cain:identity:agent:yyy"]
  }'

# Disable tool
curl -X POST https://cainstudio.online/fabric/control/tools/my-tool/disable \
  -H "X-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{"reason": "vulnerability found"}'

# Enable tool
curl -X POST https://cainstudio.online/fabric/control/tools/my-tool/enable \
  -H "X-API-Key: your-key"

Policies

# Create policy
curl -X POST https://cainstudio.online/fabric/control/policies \
  -H "X-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "high-risk-tool-policy",
    "description": "Restricts high-risk tool usage",
    "rules": [
      {"action": "tool:write", "risk_level": "high", "requires_approval": true}
    ]
  }'

# Activate policy
curl -X POST https://cainstudio.online/fabric/control/policies/pol:xxx/activate \
  -H "X-API-Key: your-key"

# Rollback policy
curl -X POST https://cainstudio.online/fabric/control/policies/pol:xxx/rollback?version=2 \
  -H "X-API-Key: your-key"

Control Evaluation

# Evaluate (records decision)
curl -X POST https://cainstudio.online/fabric/control/evaluate \
  -H "X-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "identity_id": "urn:cain:identity:agent:xxx",
    "agent_id": "agent:yyy",
    "action": "tool:read",
    "tool": "my-tool"
  }'

# Simulate (no recording, no execution)
curl -X POST https://cainstudio.online/fabric/control/simulate \
  -H "X-API-Key: your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "identity_id": "urn:cain:identity:agent:xxx",
    "agent_id": "agent:yyy",
    "action": "tool:read",
    "tool": "my-tool"
  }'

Fail-Closed Behavior

CAIN Control is fail-closed. The following ALWAYS result in DENY:

• Tenant kill switch active
• Agent is paused
• Agent is killed
• Tool is disabled
• Identity not in allowed list
• Agent not in allowed list
• Control service unavailable

Only ALLOW permits execution.

Integration with CAIN Enforcement

CAIN Control integrates with make_cain_decision in CAIN Private:

Request Action
    ↓
CAIN Identity (verify WHO)
    ↓
CAIN Control (verify WHAT allowed)
    ↓
CAIN Enforcement (ALLOW/DENY)
    ↓
Execute or Block
    ↓
Evidence

Security Properties

See Also

• CAIN Identity - Verifiable identity
• CAIN Private - Private AI agent environment
• CAIN Architecture - Trust Fabric overview