Sandbox compliance pinning
This page explains what changes on a sandbox created under a HIPAA-enrolled app or team key, or with compliance: { hipaa: true }. For enrollment, see Enable HIPAA protection.
How a sandbox becomes HIPAA-pinned
A sandbox is pinned in either of two ways:
- Your key is HIPAA-enrolled. Tangle reads the enrollment from the verified app or team behind the API key, never from the request. Every sandbox that key creates is pinned. If Tangle cannot confirm the key’s current enrollment, the create is refused rather than placed without protection.
- You ask for it on create. Pass
compliance: { hipaa: true }orcompliance: ["hipaa"]. The key must be entitled to HIPAA placement.
import { Sandbox } from "@tangle-network/sandbox";
const client = new Sandbox({
apiKey: process.env.TANGLE_API_KEY!,
baseUrl: "https://sandbox.tangle.tools",
});
const box = await client.create({ compliance: { hipaa: true } });
try {
console.log(box.id, box.status);
} finally {
await box.delete();
}The Python SDK has no compliance option either. Send "compliance": {"hipaa": true} in the body of POST /v1/sandboxes, for example with client.fetch("POST", "/v1/sandboxes", json={...}).
Where a pinned sandbox runs
A pinned sandbox runs only on capacity that can take HIPAA workloads, and it is never placed anywhere else.
- A create that asks for HIPAA with a key that is not entitled to it gets
COMPLIANCE_NOT_ENTITLED(403). - When no HIPAA capacity can take the sandbox, the create gets
COMPLIANCE_CAPACITY_UNAVAILABLEorCOMPLIANCE_CELL_UNAVAILABLE(503) with aRetry-Afterheader. - A call that cannot keep the protection gets
COMPLIANCE_CREATE_UNSUPPORTED(403); see Calls that refuse a pinned workload.
Branch on error.code; Error codes says what to do about each.
What pinning changes
For the life of the sandbox:
| Behavior | Effect |
|---|---|
| Fixed at create | The HIPAA setting is fixed when the sandbox is created and applies for its whole life. |
| Session transcripts | Coding-agent session transcripts are not copied out of the sandbox when it stops or is deleted. |
| Telemetry | Telemetry carries metadata only, never content. |
| Error reports | An error report from inside the sandbox carries an event ID, a timestamp and a fixed label, never request or file content. Traces and profiles are not sampled. |
The sandbox record echoes its compliance state so your code can confirm it. The echo is set by Tangle; you cannot change it after create.
Calls that refuse a pinned workload
These calls cannot keep the protection, so a HIPAA-enrolled key gets COMPLIANCE_CREATE_UNSUPPORTED instead of an unprotected sandbox:
- Batch runs (
POST /v1/sandboxes/batch/run) - Branching a sandbox (
POST /v1/sandboxes/{id}/branch) - Rollouts (
POST /v1/sandboxes/{id}/rollouts) - GPU leases, including a GPU lease requested as part of a create
- E2B-compatible create (
POST /e2b/sandboxes) - Creating a session with
POST /v1/sessionsthat names no existing sandbox
Create the sandbox with POST /v1/sandboxes first. Reads and commands on existing sandboxes keep working.
Not retroactive
Pinning applies to new sandboxes. Enrollment does not change existing sandboxes, retained files or past logs; moving them needs a separate approved procedure. Until the launch requirements close, do not put PHI on the shared fleet, whether or not a sandbox is pinned.
Next steps
- Enable HIPAA protection: enroll an app or team.
- Isolation and compliance: the sandbox security model.
- Error codes: every Sandbox error code.