Sandbox Environment

Kakunin provides staging.kakunin.ai — a complete isolated replica of the production API where you can test agent integration without affecting production data.

What is Sandbox?

• Separate domain: staging.kakunin.ai (same code as production)
• Isolated database: Same schema, but rows tagged environment='sandbox'
• Automatic cleanup: Data older than 7 days auto-deleted nightly
• On-demand reset: Clear your sandbox data in seconds
• Free tier: No metering, no costs
• Test keys: kkn_sandbox_* keys work only in sandbox

Getting Started

1. Generate Sandbox Key

# Via dashboard
# /dashboard/api-keys → "Generate Sandbox Key" button
# Copy the key immediately (not shown again)

# Save to .env.local
KAKUNIN_API_KEY=kkn_sandbox_abc123def456...

2. Point agents at staging

// Use staging base URL instead of production
const kakunin = new KakuninClient(
  process.env.KAKUNIN_API_KEY,
  'https://staging.kakunin.ai/api/v1'  // staging instead of kakunin.ai
);

3. Run test agents

npm run agent:http-tool       # Autonomous lifecycle test
npm run agent:event-harness   # 100+ events, throughput test
npm run agent:discord         # Interactive CLI

Data Isolation

Sandbox data is completely isolated:

• Each tenant's sandbox data is separate (RLS enforced)
• Sandbox never appears in production dashboards
• Sandbox keys have limited scope: agents:create, certificates:issue, events:create only
• No access to: webhooks, compliance reports, compliance certifications

Reset Data On-Demand

Clear all your sandbox data in seconds:

curl -X POST https://staging.kakunin.ai/api/internal/sandbox/reset \
  -H "Authorization: Bearer kkn_sandbox_..." \
  -H "Content-Type: application/json"

Response:

{
  "data": {
    "deleted": 234,
    "message": "Sandbox data cleared",
    "timestamp": "2026-05-23T..."
  }
}

Automatic Cleanup

Sandbox data older than 7 days is automatically deleted nightly (2am UTC).

created_at < NOW() - INTERVAL '7 days' → DELETED

No manual action required — just develop and test.

When to Use

✅ Integration testing — Test agent registration → certificate → events → risk score ✅ Load testing — Stress-test with 100+ events, measure throughput ✅ Feature development — Experiment without affecting production ✅ Training/demos — Let users test without real data concerns

❌ Do NOT use for production workloads or real regulated transactions

Troubleshooting

Key not working?

• Verify prefix: kkn_sandbox_ (not kak_live_)
• Ensure it's a newly generated sandbox key (not production key)
• Check staging URL in base config

Data not appearing?

• Confirm KAKUNIN_API_KEY is set to sandbox key
• Check Content-Type: application/json header
• Verify request is authenticated (Bearer token)

"Sandbox reset only available in staging"?

• Reset API only works on staging.kakunin.ai
• Production sandbox data stays for 7 days, then auto-deletes
• To clear manually in production, contact support

After Integration Testing

Once your agent works in sandbox:

1. Generate production key — /dashboard/api-keys → "Generate API Key"
2. Update base URL — change from staging.kakunin.ai to kakunin.ai
3. Test in production — run full agent lifecycle
4. Monitor risk scores — use /dashboard/agents to watch behavioral monitoring
5. Set up webhooks — configure /api/v1/webhooks for risk alerts

FAQ

Does sandbox have the same SLA as production?

No — sandbox is best-effort. No uptime guarantee, may have delays during maintenance.

Are sandbox and production data completely isolated?

Yes — row-level security (RLS) ensures only your tenant sees your sandbox rows.

Can I migrate sandbox data to production?

Not directly. Re-register your agent in production and re-run tests there.

How long does cleanup take?

Nightly job runs at 2am UTC. Cleanup typically completes within 5 minutes.

What if I need data to persist longer than 7 days?

Use production keys instead — production data retained per your subscription plan.

Next: Integration Guide · API Reference