Developer documentation

CAIN Private

Last reviewed 31 August 2026

CAIN Private Documentation

Status: PRIVATE PREVIEW

CAIN Private is in private preview. Not all features are production-ready.

What is CAIN Private?

CAIN Private is a private AI agent environment where:

• You control the agent - its instructions, memory, and tools
• CAIN governs every action - consequential actions require authorization
• Evidence is recorded - every decision leaves a traceable record

CAIN Private is not a chatbot. It is governed autonomous AI that can take real actions in your systems.

Core proposition: Your AI. Your data. Your infrastructure. Your rules.

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                     CAIN Private                                 │
├─────────────────────────────────────────────────────────────────┤
│  Agent Runtime                                                   │
│  ├── System instructions                                        │
│  ├── Model configuration                                       │
│  ├── Tool registry (MCP, API, custom)                          │
│  └── Memory (agent, user, workspace)                            │
│                                                                  │
│  CAIN Enforcement Layer                                         │
│  ├── Identity verification                                      │
│  ├── Policy evaluation                                         │
│  ├── Authorization                                             │
│  ├── Risk assessment                                          │
│  └── Decision (ALLOW/DENY/REQUIRE_APPROVAL)                     │
│                                                                  │
│  Evidence Chain                                                 │
│  └── Signed records of all decisions                           │
└─────────────────────────────────────────────────────────────────┘

Deployment Models

CAIN Private Hosted (CAIN Studio)

Privacy claim: Your agent's memory and data are isolated per tenant.

CAIN Private Self-Hosted (MCPGate) - COMING SOON

Agent Management

Create Agent

curl -X POST https://cainstudio.online/private/agents \
  -H "X-Tenant-ID: your-tenant" \
  -H "X-API-Key: your-key" \
  -d '{
    "name": "data-processor",
    "description": "Processes data with CAIN protection"
  }'

Response:

{
  "agent_id": "agent:abc123...",
  "name": "data-processor",
  "state": "created"
}

Configure Agent

# Set allowed tools
curl -X PATCH https://cainstudio.online/private/agents/{agent_id} \
  -H "X-Tenant-ID: your-tenant" \
  -H "X-API-Key: your-key" \
  -d '{"allowed_tools": ["read_record", "write_record"]}'

Agent States

Memory

Memory Types

Set Memory

curl -X POST https://cainstudio.online/private/agents/{agent_id}/memory \
  -H "X-Tenant-ID: your-tenant" \
  -H "X-API-Key: your-key" \
  -d '{
    "memory_type": "agent",
    "key": "current_task",
    "value": "Processing customer orders"
  }'

List Memory

curl https://cainstudio.online/private/agents/{agent_id}/memory \
  -H "X-Tenant-ID: your-tenant" \
  -H "X-API-Key: your-key"

Clear Memory

# Clear all agent memory
curl -X DELETE https://cainstudio.online/private/agents/{agent_id}/memory \
  -H "X-Tenant-ID: your-tenant" \
  -H "X-API-Key: your-key"

# Clear specific type
curl "https://cainstudio.online/private/agents/{agent_id}/memory?memory_type=agent" \
  -X DELETE \
  -H "X-Tenant-ID: your-tenant" \
  -H "X-API-Key: your-key"

Tools

Register Tool

curl -X POST https://cainstudio.online/private/agents/{agent_id}/tools \
  -H "X-Tenant-ID: your-tenant" \
  -H "X-API-Key: your-key" \
  -d '{
    "tool_name": "read_customer_record",
    "tool_type": "api",
    "risk_level": "low"
  }'

Risk Levels

Enable/Disable Tool

curl -X PATCH https://cainstudio.online/private/tools/{tool_id}/enabled \
  -H "X-Tenant-ID: your-tenant" \
  -H "X-API-Key: your-key" \
  -d '{"enabled": false}'

Credentials

Store Credential

curl -X POST https://cainstudio.online/private/agents/{agent_id}/credentials \
  -H "X-Tenant-ID: your-tenant" \
  -H "X-API-Key: your-key" \
  -d '{
    "name": "database-api-key",
    "credential_type": "api_key",
    "encrypted_value": "your-encrypted-value"
  }'

Important: Credentials are encrypted. The raw value is NEVER returned after storage.

List Credentials

curl https://cainstudio.online/private/agents/{agent_id}/credentials \
  -H "X-Tenant-ID: your-tenant" \
  -H "X-API-Key: your-key"

Response (values redacted):

[{
  "credential_id": "cred:abc123",
  "name": "database-api-key",
  "credential_type": "api_key",
  "encrypted_value": "***REDACTED***"
}]

CAIN Enforcement

Execute Action with Enforcement

curl -X POST https://cainstudio.online/private/agents/{agent_id}/execute \
  -H "X-Tenant-ID: your-tenant" \
  -H "X-API-Key: your-key" \
  -d '{
    "action": "read_customer_record",
    "resource": "customer-12345"
  }'

Decision Outcomes

ALLOW Example

{
  "decision_id": "cain:abc123",
  "result": "allow",
  "reason": "Action permitted by policy",
  "executed": true,
  "evidence_id": "ev:def456",
  "timestamp": "2026-09-02T12:00:00Z"
}

DENY Example

{
  "decision_id": "cain:abc124",
  "result": "deny",
  "reason": "Tool 'delete_all' is blocked for this agent",
  "executed": false,
  "evidence_id": null,
  "timestamp": "2026-09-02T12:01:00Z"
}

REQUIRE_APPROVAL Example

{
  "decision_id": "cain:abc125",
  "result": "require_approval",
  "reason": "Tool 'transfer_funds' requires approval due to risk level 'critical'",
  "executed": false,
  "evidence_id": null,
  "timestamp": "2026-09-02T12:02:00Z"
}

Approvals

List Pending Approvals

curl https://cainstudio.online/private/approvals?status=pending \
  -H "X-Tenant-ID: your-tenant" \
  -H "X-API-Key: your-key"

Resolve Approval

curl -X POST https://cainstudio.online/private/approvals/{approval_id}/resolve \
  -H "X-Tenant-ID: your-tenant" \
  -H "X-API-Key: your-key" \
  -d '{
    "approved": true,
    "resolver": "admin@example.com",
    "notes": "Approved after verification"
  }'

Evidence & Auditing

List Decision History

curl https://cainstudio.online/private/agents/{agent_id}/decisions \
  -H "X-Tenant-ID: your-tenant" \
  -H "X-API-Key: your-key"

Decision Record

[{
  "decision_id": "cain:abc123",
  "action": "read_customer_record",
  "resource": "customer-12345",
  "result": "allow",
  "reason": "Action permitted by policy",
  "risk_score": 0.3,
  "timestamp": "2026-09-02T12:00:00Z"
}]

Security Model

Verified Properties

Fail-Closed Behavior

Only ALLOW permits execution. All other outcomes block the action.

Feature Status

Limitations

1. No automated execution - Schedules can be created but not automatically run

2. No MCP integration - MCP tools not yet connected to CAIN enforcement

3. No evidence signatures - Decisions recorded but not cryptographically signed

4. Self-hosted not available - Documentation only

Privacy

CAIN Studio Hosted

We receive:

• Decision requests (action, resource)
• Decision outcomes (allow/deny)
• Usage for billing

We do NOT receive:

• Your memory data
• Your credentials (encrypted, unreadable)
• Your internal configurations

Self-Hosted (COMING SOON)

When self-hosted, you control everything. CAIN Studio receives nothing by default.

Troubleshooting

Action returns DENY

1. Check if tool is in blocked_tools

2. Check if tool is in allowed_tools (if list is non-empty)

3. Check agent state is running

Action returns ERROR

1. Check agent exists

2. Check tenant ID is correct

3. Check API key is valid

401 Unauthorized

1. Verify X-API-Key header is present

2. Verify API key is valid for the tenant