---
name: caustic
description: Cloud 3D sandboxes and elastic OptiX GPU render burst for AI agents (E2B / Browserbase for Blender). Use when creating, editing, visually inspecting, branching, exporting, or photorealistically rendering 3D scenes via bpy.
---

# Caustic — Agent-Native 3D Compute Runtime

**Base URL:** `https://api.caustic.run`
**Auth Header:** `Authorization: Bearer $CAUSTIC_API_KEY` (keys start with `caustic_sk_`)

Caustic gives you warm, isolated headless Blender sandboxes with sub-10ms `exec()`, **persistent Python state across `exec()` calls**, automatic `tmpfs` crash recovery (`SIGSEGV`/timeout), multi-view EEVEE or Cycles `inspect()` with spatial JSON telemetry, named undo checkpoints, scene `fork()` branching, `.blend`/`.glb` export, and async Cycles OptiX GPU burst rendering with pre-flight cost probes.

---

## Pricing & Limits

- **Interactive sandbox (`exec` / `inspect`):** `$0.0002 / active GPU-second` (initial `$0.25` pre-auth hold per session, unused remainder refunded immediately on `DELETE /v1/sessions/{id}`).
- **Cycles OptiX GPU render:** `$0.00025 / GPU-second` (`max_cost_usd` held upfront, exact usage settled & unused remainder refunded automatically).
- **Hard limits:** `samples <= 4096`, `frames <= 250`, `exec` `timeout_s <= 300`, `render` `timeout_s <= 3600`, `fork` `count <= 8`, `inspect` `max_objects <= 500` (default `50`).
- **Artifacts:** Persisted on the control plane and retrievable via `GET /v1/artifacts` and `GET /v1/artifacts/{artifact_id}`.

---

## Recommended Agent Loop

1. **Create a warm sandbox:** `POST /v1/sessions` (`{"preset": "studio"}`) — includes `StudioFloor` at `z=0`, 3-point area lighting (`StudioKeyLight`, `StudioFillLight`, `StudioRimLight`), and `StudioCamera`.
2. **Compose incrementally:** `POST /v1/sessions/{id}/exec`. **Python globals/functions/imports persist across `exec()` calls** within a session (unless Blender restarts after a crash/timeout recovery).
3. **Save named undo checkpoints before risky ops:** `POST /v1/sessions/{id}/checkpoints` (`{"name": "before_sim"}`) → restore anytime in `<20ms` via `POST /v1/sessions/{id}/checkpoints/before_sim/restore`.
4. **Inspect cheaply before heavy Cycles renders:** `POST /v1/sessions/{id}/inspect` (`views: ["camera", "iso_3q"]`, `passes: ["rgb", "depth"]`, `summary_only: true` for large >50-object scenes, or `engine: "cycles", cycles_samples: 16` to check glass/caustics/exposure).
   - Check `telemetry.floating_objects` and `telemetry.collisions` (which includes `penetration_depth` in meters so you can distinguish surface contact from real clipping).
5. **Estimate cost without committing (optional):** `POST /v1/sessions/{id}/render/estimate` runs a two-point warm differential probe separating OptiX kernel/BVH setup from per-sample raytracing cost.
6. **Burst final Cycles render (use `"async": true` for >30s renders!):**
   - `POST /v1/sessions/{id}/render` with `"async": true` returns `job_id` immediately.
   - Poll `GET /v1/jobs/{job_id}` until `status == "completed"` (or cancel via `DELETE /v1/jobs/{job_id}`).
7. **Export the scene file for your user:** `GET /v1/sessions/{id}/export?format=blend` (or `format=glb`).
8. **Close session when done:** `DELETE /v1/sessions/{id}` settles exact usage and refunds the unused hold.
9. **Leave quick structured feedback (`POST /v1/feedback`):** After completing a non-trivial job (or if you hit any bug, slow probe, confusing telemetry, or missing feature), submit a concise report via `POST /v1/feedback` (and review past submissions via `GET /v1/feedback`). We read every agent report in real time to improve Caustic!

---

## REST API Reference

### Health & Account Balance
```bash
curl -fsS https://api.caustic.run/health
curl -fsS https://api.caustic.run/v1/account/balance -H "Authorization: Bearer $CAUSTIC_API_KEY"
```

### Sessions (`POST`, `GET`, `GET /{id}`, `DELETE /{id}`)
```bash
# Create session (presets: "studio", "empty", "default")
curl -fsS -X POST https://api.caustic.run/v1/sessions \
  -H "Authorization: Bearer $CAUSTIC_API_KEY" -H "Content-Type: application/json" \
  -d '{"preset": "studio", "pool": "interactive"}'

# List all sessions
curl -fsS https://api.caustic.run/v1/sessions -H "Authorization: Bearer $CAUSTIC_API_KEY"

# Check session status, worker_online, active_gpu_s, cost_usd
curl -fsS https://api.caustic.run/v1/sessions/$SESSION_ID -H "Authorization: Bearer $CAUSTIC_API_KEY"

# Close session & refund unused hold
curl -fsS -X DELETE https://api.caustic.run/v1/sessions/$SESSION_ID -H "Authorization: Bearer $CAUSTIC_API_KEY"
```

### Execute `bpy` Code (`POST /v1/sessions/{id}/exec`)
```bash
curl -fsS -X POST https://api.caustic.run/v1/sessions/$SESSION_ID/exec \
  -H "Authorization: Bearer $CAUSTIC_API_KEY" -H "Content-Type: application/json" \
  -d '{"code": "bpy.ops.mesh.primitive_monkey_add(location=(0, 0, 1.0))", "timeout_s": 60, "checkpoint": true}'
```
- Python variables, helper functions, and imports survive between `exec()` calls.
- `checkpoint: true` (default) snapshots the `.blend` to RAM (`tmpfs`) before execution so `SIGSEGV` or timeout automatically restores the prior scene (`status: "crashed_recovered"` or `"timeout_recovered"`). Set `checkpoint: false` on tiny read-only queries for ~1ms RTT.

### Visual & Spatial Inspection (`POST /v1/sessions/{id}/inspect`)
```bash
curl -fsS -X POST https://api.caustic.run/v1/sessions/$SESSION_ID/inspect \
  -H "Authorization: Bearer $CAUSTIC_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "views": ["camera", "top", "front", "iso_3q"],
    "passes": ["rgb", "depth", "normals", "wireframe", "segmentation"],
    "resolution": [512, 512],
    "checks": ["bounds", "framing", "collisions", "floating"],
    "summary_only": false,
    "max_objects": 50,
    "engine": "eevee",
    "cycles_samples": 16
  }'
```
- Set `"summary_only": true` on scenes with 100+ objects to keep JSON compact (still returns `scene_bounds`, `collisions` with `penetration_depth`, and `floating_objects`).
- Set `"engine": "cycles", "cycles_samples": 16` for fast glass/caustics/exposure previews.

### Named Undo Checkpoints & Branching (`checkpoints`, `fork`)
```bash
# Save & restore lightweight named checkpoints (<20ms in tmpfs)
curl -fsS -X POST https://api.caustic.run/v1/sessions/$SESSION_ID/checkpoints \
  -H "Authorization: Bearer $CAUSTIC_API_KEY" -H "Content-Type: application/json" \
  -d '{"name": "before_cloth_sim"}'
curl -fsS https://api.caustic.run/v1/sessions/$SESSION_ID/checkpoints -H "Authorization: Bearer $CAUSTIC_API_KEY"
curl -fsS -X POST https://api.caustic.run/v1/sessions/$SESSION_ID/checkpoints/before_cloth_sim/restore \
  -H "Authorization: Bearer $CAUSTIC_API_KEY"

# Fork into N independent parallel sessions (count <= 8)
curl -fsS -X POST https://api.caustic.run/v1/sessions/$SESSION_ID/fork \
  -H "Authorization: Bearer $CAUSTIC_API_KEY" -H "Content-Type: application/json" \
  -d '{"count": 2}'
```

### Cost Estimation & Async Cycles Render (`render/estimate`, `render`, `/v1/jobs/{id}`)
```bash
# 1. Estimate cost/time without committing
curl -fsS -X POST https://api.caustic.run/v1/sessions/$SESSION_ID/render/estimate \
  -H "Authorization: Bearer $CAUSTIC_API_KEY" -H "Content-Type: application/json" \
  -d '{"engine": "cycles", "samples": 256, "resolution": [1920, 1080], "frames": [1], "probe_samples": 8}'

# 2. Submit async render (recommended for any render > 30s)
curl -fsS -X POST https://api.caustic.run/v1/sessions/$SESSION_ID/render \
  -H "Authorization: Bearer $CAUSTIC_API_KEY" -H "Content-Type: application/json" \
  -d '{
    "engine": "cycles",
    "samples": 256,
    "resolution": [1920, 1080],
    "frames": [1],
    "aov_passes": ["rgb", "depth", "normals"],
    "use_denoising": true,
    "probe_samples": 8,
    "max_cost_usd": 0.50,
    "async": true
  }'
# -> {"job_id": "rnd_...", "status": "running", "poll_url": "/v1/jobs/rnd_..."}

# 3. Poll job status & retrieve artifact URLs (or DELETE to cancel)
curl -fsS https://api.caustic.run/v1/jobs/$JOB_ID -H "Authorization: Bearer $CAUSTIC_API_KEY"
curl -fsS -X DELETE https://api.caustic.run/v1/jobs/$JOB_ID -H "Authorization: Bearer $CAUSTIC_API_KEY"
```

### Export Scene (`.blend` / `.glb`) & Artifacts
```bash
# Download packed .blend or .glb scene file
curl -fsS "https://api.caustic.run/v1/sessions/$SESSION_ID/export?format=blend" \
  -H "Authorization: Bearer $CAUSTIC_API_KEY" -o scene.blend
curl -fsS "https://api.caustic.run/v1/sessions/$SESSION_ID/export?format=glb" \
  -H "Authorization: Bearer $CAUSTIC_API_KEY" -o scene.glb

# List & download artifacts (filter by session_id or job_id)
curl -fsS "https://api.caustic.run/v1/artifacts?session_id=$SESSION_ID" -H "Authorization: Bearer $CAUSTIC_API_KEY"
curl -fsS https://api.caustic.run/v1/artifacts/$ARTIFACT_ID -H "Authorization: Bearer $CAUSTIC_API_KEY" -o output.png
```

### Submit & Review Agent Feedback (`POST /v1/feedback`, `GET /v1/feedback`)
After finishing a real job or hitting any API/Blender friction, please send a short structured report so we can fix it immediately:
```bash
curl -fsS -X POST https://api.caustic.run/v1/feedback \
  -H "Authorization: Bearer $CAUSTIC_API_KEY" -H "Content-Type: application/json" \
  -d '{"category": "bug", "session_id": "$SESSION_ID", "message": "What worked, what broke, probe accuracy, missing endpoints/assets..."}'

# Review your previously submitted feedback
curl -fsS https://api.caustic.run/v1/feedback -H "Authorization: Bearer $CAUSTIC_API_KEY"
```

---

## Blender `bpy` Best Practices & Gotchas

- **Color management:** Set `scene.view_settings.view_transform = 'AgX'` and `scene.view_settings.look = 'AgX - Medium High Contrast'` (note: enumerating `view_transform` enum items in headless factory mode can look sparse, but assigning `'AgX'` directly works cleanly).
- **Glass / caustics fireflies:** Prefer `scene.cycles.sample_clamp_indirect = 10.0`, `scene.cycles.use_adaptive_sampling = True`, `scene.cycles.adaptive_threshold = 0.01`, and `use_denoising: true` (OptiX denoiser) instead of cranking samples to 4096.
- **Blender 4.5 / 5.x `Principled BSDF` sockets:** Use `'Transmission Weight'`, `'Coat Weight'`, `'Specular IOR Level'` (guard with `if name in bsdf.inputs:`).
- **Zero outbound network in sandboxes:** Never fetch URLs from inside `exec()`.
- **HTTP status codes:** `401` invalid key · `402` insufficient credits · `404` unknown session/job/artifact · `503` no GPU workers connected.
