Scenarios
Common patterns for how kubbi fits into real workflows. Each scenario involves two actors separated by a real gap — a different organisation, network, toolchain, or time cycle.
Core patterns
Scenario 1: Burn-After-Read Handoff
Actor A (an AI agent) finishes a task and needs to pass credentials to Actor B (another agent). The data should only be read once, then destroyed.
| Step | Who | API Call | What Happens |
|---|---|---|---|
| 1 | Actor A (producer) | POST /api/v1/kubbis | Creates kubbi with max_retrievals: 1. Gets back a claim_url. |
| 2 | Actor A | Sends claim_url to Actor B | Only the URL travels — no sensitive data in transit. |
| 3 | Actor B (consumer) | GET /r/:claim_token | Inspects metadata (content type, expiry) without consuming. |
| 4 | Actor B (consumer) | POST /r/:claim_token/claim | Gets the decrypted payload. Payload is immediately wiped. burned: true. |
Scenario 2: Multi-Read Shared State
A pipeline produces an intermediate result that 3 downstream steps all need. The data should live for 1 hour, then disappear.
| Step | Who | API Call | What Happens |
|---|---|---|---|
| 1 | Orchestrator (producer) | POST /api/v1/kubbis | Creates kubbi with max_retrievals: 3, ttl_seconds: 3600. |
| 2 | Orchestrator | Fans out claim_url | Each of Step A, B, C gets the same URL. |
| 3 | Step A (consumer) | POST /r/:claim_token/claim | Gets payload. retrieval_count → 1. |
| 4 | Step B (consumer) | POST /r/:claim_token/claim | Gets payload. retrieval_count → 2. |
| 5 | Step C (consumer) | POST /r/:claim_token/claim | Gets payload. retrieval_count hits 3 = max_retrievals. Payload burned. |
Scenario 3: Producer Cancels Early
An actor creates a kubbi for another system, but the downstream task gets cancelled before the data is picked up.
| Step | Who | API Call | What Happens |
|---|---|---|---|
| 1 | Actor (producer) | POST /api/v1/kubbis | Creates kubbi with ttl_seconds: 600. Stores kubbi_id. |
| 2 | Actor | Sends claim_url | External system has not claimed yet. |
| 3 | Actor (producer) | DELETE /api/v1/kubbis/:kubbi_id | kubbi set to deleted, payload wiped immediately. |
| 4 | External system | POST /r/:claim_token/claim | Gets 410 Gone. No data leaked. |
Scenario 4: Multi-File Package Handoff
A deployment pipeline needs to pass config, instructions, and a binary artifact to an air-gapped build agent. All three must arrive together as one atomic handoff.
| Step | Who | API Call | What Happens |
|---|---|---|---|
| 1 | Pipeline (producer) | POST /api/v1/kubbis | Creates a package kubbi with files[] containing config.json, instructions.md, and artifact.tar.gz (base64-encoded). Gets back a claim_url. |
| 2 | Pipeline | Sends claim_url to build agent | Only the URL travels. The three files stay encrypted in kubbi. |
| 3 | Build agent (consumer) | GET /r/:claim_token | Inspects the file manifest — sees names, types, sizes, and roles without consuming. |
| 4 | Build agent (consumer) | POST /r/:claim_token/claim | Gets all three files in a single response. Text files as UTF-8, binary as base64. Payload burned. |
Real-world use cases
Research agent → third-party summarisation service
Autonomous research agent (Company A)
AI summarisation service (Company B, separate org)
Raw research findings (~80 KB JSON)
30 min, max_retrievals: 1
Company A's research agent drops findings into a kubbi and POSTs only the claim URL to Company B's inbound webhook. Company B's summariser claims the kubbi when it runs. Neither company's system ever holds the other's data directly.
On-premise ETL → cloud analytics agent
On-premise ETL pipeline (corporate firewall)
Cloud-hosted analytics AI agent (AWS)
Transformed financial dataset (CSV, ~500 KB)
2 hours, max_retrievals: 1
The ETL job, which has outbound HTTPS access, creates a kubbi and writes the claim URL into a shared job-tracking database. The cloud agent polls for the URL, claims the kubbi, and processes the dataset.
CI/CD pipeline → air-gapped build agent
GitHub Actions workflow
Air-gapped build agent (isolated network)
Code-signing certificate and private key (PEM)
5 min, max_retrievals: 1
The pipeline creates a kubbi, injects only the claim URL into the build job's environment variables. The build agent claims the certificate when needed. The 5-minute TTL ensures cleanup even if the build never starts.
Cron job → async reporting agent
Cron job running at 00:00
AI reporting agent running at 06:00
Weekly aggregated usage statistics (JSON)
4 hours, max_retrievals: 1
The cron job drops stats into a kubbi and records the claim URL in a jobs table. The reporting agent claims it hours later. No shared in-memory state or schema coordination needed.
Security analyst → automated triage agent
Human security analyst (internal tooling)
Automated triage agent (separate security platform)
Decrypted incident report with IOCs
20 min, max_retrievals: 1
The analyst's tool creates a kubbi and sends only the claim URL to the triage platform's inbound API. The triage agent claims the report, processes the IOCs, and the report is burned.
Mobile app → backend verification service
Mobile app (iOS/Android)
Backend identity verification microservice
Signed biometric attestation token
90 sec, max_retrievals: 1
The app creates a kubbi with the attestation token and sends only the claim URL in its request to the backend. The 90-second TTL makes replay attacks impractical.
Partner org → onboarding agent
Partner organisation's ops team
Customer onboarding AI agent
API keys, tenant config, private certificate
1 hour, max_retrievals: 1
The partner creates a kubbi and sends the claim URL via a standard channel. The onboarding agent claims the payload during provisioning. Secrets are burned immediately after claim.
AI agent → human reviewer
AI agent mid-workflow
Human domain expert (reviews asynchronously)
Draft output requiring approval (~5 KB JSON)
Short TTL, max_retrievals: 1
The agent drops its draft into a kubbi, records the claim URL in a task system, and terminates. The reviewer claims the payload later. The pipeline resumes from the reviewer's decision.