RouterHIPAASandbox compliance pinning

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 } or compliance: ["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_UNAVAILABLE or COMPLIANCE_CELL_UNAVAILABLE (503) with a Retry-After header.
  • 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:

BehaviorEffect
Fixed at createThe HIPAA setting is fixed when the sandbox is created and applies for its whole life.
Session transcriptsCoding-agent session transcripts are not copied out of the sandbox when it stops or is deleted.
TelemetryTelemetry carries metadata only, never content.
Error reportsAn 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/sessions that 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