Types and errors

Every type here is a dataclass or enum you import from tangle_sandbox. Errors are SandboxError with a platform code; Error codes lists every code.

from tangle_sandbox import SandboxError
 
try:
    box.exec("true")
except SandboxError as error:
    print(error.code, error.status, error.retryable, error.next_step)

Status

SandboxStatus is a string enum: PENDING, PROVISIONING, RUNNING, STOPPED, FAILED, EXPIRED, DELETED. Values are the lowercase strings the API returns (box.status.value == "running"). Pass members, not strings, to wait_for and ListSandboxOptions.

Create options

BackendType lists what the SDK accepts. The coding agents the service runs today come from GET /v1/backends; the service refuses one it cannot run with HARNESS_UNAVAILABLE.

Sandbox details

Commands and agents

Git, snapshots and network

Batches

Fleets

CreateSandboxFleetOptions, CreateSandboxFleetWithCoordinatorOptions, SandboxFleetMachineSpec, SandboxFleetPolicy, SandboxFleetWorkspace, ListSandboxFleetOptions, FleetExecDispatchOptions, FleetPromptDispatchOptions, FleetRetryPolicy, FleetDispatchResultBufferOptions, FleetDispatchResultBuffer, SandboxFleetDispatchResponse, SandboxFleetTraceBundle, SandboxFleetTraceExport, SandboxFleetIntelligenceEnvelope, CreateSandboxFleetTokenOptions and ReapExpiredSandboxFleetsOptions. Fleets and optional modules describes the fields you set.

Traces and reports

These are TypedDicts with the API’s camelCase keys.

Exported types that nothing returns

ProvisionEvent, ProvisionResult, ProvisionStep, ProvisionStatus and BuildProgressEvent are exported, but no method returns or yields them; Python has no provisioning progress stream. ImageSpec, ImageBuildResult and ImageBuildOptions belong to the image builder, whose build() the service refuses. SandboxClientConfig holds the client’s settings.

SandboxError

SandboxError(message, code=None, status=None, **details)

Handle errors by code:

from tangle_sandbox import SandboxError
 
try:
    box = client.create()
except SandboxError as error:
    if error.code == "CAPACITY_EXHAUSTED" and error.retryable:
        print("retry in", error.retry_after_ms, "ms")
    else:
        raise

Aliases

Each alias is a SandboxError subclass for a group of codes, so isinstance checks work.

A bad key raises a SandboxError with an auth code; check code rather than expecting AuthError alone. tangle_sandbox.TimeoutError is not the built-in TimeoutError, and except TimeoutError with the built-in does not catch it.

Errors raised before a request

• Sandbox("", url) raises AuthError("API key is required").
• Sandbox(key, "") raises ValidationError("Base URL is required").
• A runtime call on an instance whose cached status is not RUNNING raises StateError.

Errors that are not SandboxError

Next

• Error codes
• Sandbox and AsyncSandbox
• Python examples