Developer documentation

CAIN Private

Last reviewed 31 August 2026

All docs

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)#

What CAIN Studio Operates	What You Control
Agent runtime	Agent configuration
CAIN enforcement	Tool permissions
Evidence storage	Your data/memory
Credential vault	API access

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

CAIN Private Self-Hosted (MCPGate) - COMING SOON#

What You Operate	What CAIN Studio Receives
Everything	Nothing (air-gapped option)
Agent runtime	Decision requests (optional)
Evidence	Usage for billing only
Credentials	Nothing

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#

State	Meaning
`created`	Agent created, not running
`initializing`	Agent initializing
`running`	Agent active
`paused`	Agent paused
`stopped`	Agent stopped
`error`	Error state

Memory#

Memory Types#

Type	Visibility	Use Case
`agent`	Agent + audit	Agent's working memory
`user`	User only	Sensitive user data
`workspace`	Configurable	Shared workspace

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#

Level	Requires Approval	Example
`low`	No	Read data
`medium`	No	Write data
`high`	Yes	Delete records
`critical`	Yes	Financial transactions

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#

Outcome	Meaning	Action Taken
`allow`	Policy permits	Executed
`deny`	Policy forbids	Blocked
`require_approval`	High-risk	Blocked until approved
`unknown`	Cannot determine	Blocked (fail-closed)
`error`	System error	Blocked (fail-closed)

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#

Property	Status
Tenant isolation	Tested
Authentication	Implemented
Authorization	Implemented
Fail-closed (UNKNOWN/ERROR → DENY)	Implemented
Credential protection	Implemented
Secret redaction	Implemented
IDOR resistance	Implemented

Fail-Closed Behavior#

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

Feature Status#

Feature	Status
Agent creation	LIVE + FUNCTIONAL
Memory management	LIVE + FUNCTIONAL
Tool registration	LIVE + FUNCTIONAL
CAIN enforcement	LIVE + FUNCTIONAL
Credential storage	LIVE + FUNCTIONAL
Decision auditing	LIVE + FUNCTIONAL
Approval workflow	LIVE + FUNCTIONAL
Automation	STUB
MCP integration	NOT DEPLOYED
Evidence signing	HEALTH-CHECK ONLY
Self-hosted deployment	DOCUMENTATION ONLY

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