Fleets and optional modules

This page covers the Python modules beyond a single sandbox: fleets, an agent tool that manages fleets, trace export, and the modules behind the [gateway] and [tangle] extras.

Fleets

A fleet is a named group of sandboxes that run one workload. You send one command or prompt to every machine and collect the results.

client.fleets

There is no Python call that lists every fleet; use client.fetch("GET", "/v1/fleets") or tangle fleet list.

create() checks the policy caps on your machine first, creates each machine’s sandbox (4 at a time by default) with a 1-hour lifetime unless you set one, then records the fleet.

SandboxFleetPolicy caps: max_machines, max_concurrent_creates, max_total_cpu, max_total_memory_mb, max_total_storage_mb, max_total_accelerators, max_lifetime_seconds, max_spend_usd (checked against estimate_cost), allowed_drivers, allowed_environments, allowed_template_ids and allow_accelerators. create_with_coordinator adds a coordinator machine; it is a full sandbox and is billed like one.

SandboxFleet

Each dispatch result is a dict with machineId, ok, and result (exitCode, stdout, stderr) or error. FleetExecDispatchOptions takes machines, max_concurrent, retry=FleetRetryPolicy(attempts=...), cwd, env, timeout_ms, dispatch_id and buffer_results. FleetPromptDispatchOptions adds session_id, backend and context. A dispatch waits the larger of timeout_ms and 600 s, plus 15 s, whatever the client timeout. Every command a dispatch runs sees TANGLE_FLEET_ID, TANGLE_FLEET_MACHINE_ID, TANGLE_FLEET_MACHINE_ROLE and TANGLE_SANDBOX_ID.

collect_artifacts takes [{"machine_id": ..., "path": ...}]. Paths must be under /home/agent, and each file is capped at 10 MiB unless the entry sets max_bytes. The sync fleet also accepts machineId as the key; AsyncSandboxFleet needs machine_id.

from tangle_sandbox import FleetExecDispatchOptions
 
results = fleet.dispatch_exec(
    'echo "$TANGLE_FLEET_MACHINE_ID" > /home/agent/id.txt && nproc',
    FleetExecDispatchOptions(max_concurrent=3, timeout_ms=30_000),
)
for result in results:
    print(result["machineId"], result["ok"])
 
files = fleet.collect_artifacts([{"machine_id": m, "path": "/home/agent/id.txt"} for m in fleet.ids])

The manageSandboxes agent tool

from tangle_sandbox import SandboxFleetPolicy, create_manage_sandboxes_tool
 
tool = create_manage_sandboxes_tool(client, policy=SandboxFleetPolicy(max_machines=4, max_spend_usd=5))
print(tool.name)

create_manage_sandboxes_tool(client, policy=None) returns a ManageSandboxesTool you can hand to an agent framework: tool.name is manageSandboxes, tool.parameters is its JSON schema, and tool.execute(input) runs one action. Actions: capabilities, create, createWithCoordinator, list, delete, manifest, usage, trace, intelligence, cost, createWorkspaceSnapshot, reconcileWorkspace, attachMachine, detachMachine and restoreWorkspaceSnapshot. Create actions use the policy you pass to the factory; the agent cannot supply its own. execute returns SDK objects, such as a SandboxFleet, not JSON. create_async_manage_sandboxes_tool builds the AsyncSandbox version.

Export traces to your collector

from tangle_sandbox import export_trace_bundle, to_otel_json
 
bundle = box.trace()
spans = to_otel_json(bundle, service_name="my-agent")
export_trace_bundle(bundle, "https://collector.example.com/v1/traces", format="otel-json", headers={"authorization": "Bearer ..."})

The export uses its own HTTP request, so your collector’s headers never reach the Sandbox API.

Session gateway ([gateway])

pip install "tangle-sandbox[gateway]"

tangle_sandbox.session_gateway streams a session’s live events over a WebSocket, with reconnects, ping tracking, de-duplication and replay from the last event id.

from tangle_sandbox.session_gateway import SessionGatewayClient, SessionGatewayClientConfig
 
gateway = SessionGatewayClient(SessionGatewayClientConfig(url=gateway_url, token=read_token, session_id=session_id))
await gateway.connect()

SessionGatewayClient is async; SyncSessionGatewayClient runs it on a background thread. Methods: connect, disconnect, subscribe, unsubscribe, ping, replay(since), send_terminal_input(terminal_id, data), update_token, and stats and state readers. The token is a session read token minted on your backend with tangle_sandbox.auth. Without the extra, constructing a client raises ImportError naming the install command.

Product tokens (tangle_sandbox.auth)

from tangle_sandbox.auth import ProductTokenIssuer
 
issuer = ProductTokenIssuer(product_id="my-product", signing_secret=os.environ["SANDBOX_SIGNING_SECRET"])
token = issuer.issue(user_id="user-1", session_id="sess-1", tier="pro")

Mints signed tokens on your backend for the session gateway and collaboration connections. Default lifetimes: free 15 minutes, pro 240 minutes, enterprise 480 minutes. Helpers: issue_read_token, issue_session_scoped_token, issue_project_scoped_token, issue_batch_scoped_token, issue_collaboration_token, decode_token, get_token_ttl and is_token_expiring_soon. Keep the signing secret on your server; never send it to a browser.

Collaboration client (tangle_sandbox.collaboration)

CollaborationClient(CollaborationClientConfig(base_url, timeout_ms=30000, headers=None)) calls /api/collaboration/bootstrap, /token and /snapshot on a collaboration backend you run at base_url; it does not call the Sandbox API. CollaborationFileBridge, build_collaboration_document_id, parse_collaboration_document_id and normalize_collaboration_path help build document ids for files.

Tangle Network operators ([tangle])

pip install "tangle-sandbox[tangle]"

tangle_sandbox.tangle.TangleSandboxClient creates and deletes sandboxes through on-chain jobs on Tangle Network operators and returns a normal SandboxInstance whose runtime calls go to the operator.

from tangle_sandbox import CreateSandboxOptions
from tangle_sandbox.tangle import TangleSandboxClient, TangleSandboxClientConfig
 
client = TangleSandboxClient(TangleSandboxClientConfig(service_id=1, private_key=os.environ["OPERATOR_KEY"], rpc_url=rpc_url))
box = client.create(CreateSandboxOptions(name="on-chain"))

• create() blocks until the job completes and takes a CreateSandboxOptions.
• stop() and resume() answer 501: operators have no stop or resume job.
• prompt() and stream_prompt() raise NotImplementedError; call them on box.direct().
• get() answers from a cache of sandboxes this client created.
• env values are public on-chain. Send secrets with tangle_secrets, which go to the operator off-chain and need operator_api_url.
• Import names explicitly; from tangle_sandbox.tangle import * raises AttributeError.

Image builder

Image.create(base_image="ubuntu:22.04") returns a chainable ImageBuilder (python, add_packages, add_apt_packages, add_commands, with_env, workdir, user, and more). to_spec(), compute_id() and generate_dockerfile() work on your machine. build() raises ValueError, because the Sandbox API refuses image builds. To start from your own image, name a container image reference in CreateSandboxOptions(environment=...), or publish a template; see Templates and images.

Next

• Types and errors
• Fleets
• Python examples