Skip to main content
Hexagon currently uses persistent Box: disk is retained while pause/resume manages idle compute. Hexagon Runtime and the selected Harness execute tasks; the provider’s built-in Agent runner is unused. Historical Ephemeral Box, native TTL, and early transport probes are not current onboarding steps.

Configure a connection

Prepare an API key authorized to access, create, and delete Boxes. The only config field is size: small, medium, or large, defaulting to small. Do not add another provider’s CPU, memory, or image fields. Check current account specifications, quota, and availability separately; this page makes no fixed pricing claim. These local management-client examples read a private API key without passing it into the Sandbox. See self-hosting for hosted initialization. Save the connection ID; rerunning creation produces additional connections.
Validation performs list_boxes, reports control_plane expiry enforcement, and requests no provider TTL. Listing does not establish allocation or Harness execution. Explicitly enable after validation. Revalidate/enable after key or size changes; existing Sessions retain pinned configuration.

Execute the first task

Use the connection ID as sandbox_connection_id in the first Session, selecting a compatible model/Harness. The connector creates a persistent runtime=node Box with keepAlive=false, while Hexagon still selects and installs the Harness. Independently verify Run completion, file bytes, artifact export, and close through Python and TypeScript. Declared capabilities are files, commands, preview, pause_resume, and filesystem_resume. OCI and network_allowlist are absent. Choose a supporting provider when egress restrictions are required; do not silently downgrade to allow-all. Commands have a remote deadline. Accepted background startup still requires Runtime health or application-port checks. Submission is not task completion, and unknown completion is not permission to repeat external side effects.

Private HTTP and transport limits

Private preview relays an authenticated exec session’s stdin/stdout to the Sandbox port without a public port URL. The API key stays in the control plane, with separate Runtime and preview authorization. The application must actually listen on that port. Current Upstash relay limits are: 8 MiB is not a total response-body size limit. Continuously consumed streams may pass in chunks, but that does not promise arbitrary transfer sizes. Higher API, artifact, or proxy layers can impose independent limits. Verify integrity, total size, slow consumption, and interruption separately. A limit failure is not a successful truncated result.

Pause and the next turn

Idle handling calls pause; the next submit automatically resumes and prepares Runtime. Managed files and conversation data use filesystem preservation. Process memory, open connections, and arbitrary services are not preserved guarantees. Do not read normalized running state as proof of active CPU: the connector maps provider idle to running to represent an existing resource. Write a known file and record a conversation test value in the first turn. After the intended idle condition, submit another turn to the same Session and inspect real file reads and conversation continuation. Verify independently in Python and TypeScript; recheck preview services where needed. See idle and wake.

Expiry and close

The control plane owns durable deadlines and final deletion. Pause retains the Box and does not release every resource. Stopping the local control plane does not guarantee provider expiry deletion. Confirm Box absence after close; pause, idle, or accepted deletion requests are insufficient. Creation derives a name from the durable operation ID with a hexagon label. Find that original name after a lost response. A resource still visible after deletion produces upstash_deletion_unconfirmed. Only provider 404 is treated as absence; authentication or transport failures remain uncertain. Reconcile the original resource rather than allocating another to test whether the first succeeded.

Diagnose and verify

For authentication failures, check key/account permissions. For allocation failures, check size/quota. For unknown background startup, inspect the original process and Runtime. For tunnel disconnects, check service, exec channel, and output consumption. buffer_limit means queued output; request_limit means cumulative input. Do not include raw API keys or unsanitized task content in reports. Completion includes real execution, binary integrity, private access, two-turn file/conversation continuity, confirmed absence after close, and readable retained artifacts. The historical expanded matrix can include earlier paths. Check current recovery scope against the serverless ledger. This page is source-reviewed with no new live-cloud execution. Sources: Box connector, transport. Next: Sandbox overview, artifacts.

Distinguish a slow consumer from an oversized request

A consumer that has not drained 7 MiB of queued output can fail when another 2 MiB arrives. That is a queue-pressure failure, not a rule forbidding every 9 MiB response. Conversely, a 17 MiB cumulative request through one relay exceeds the 16 MiB input budget even if sent in small chunks. Neither limit overrides smaller initial-upload, artifact or proxy limits elsewhere in Hexagon. After upstash_tunnel_buffer_limit or an abnormal exit, do not accept the received prefix as a complete file. Retain the operation identity and verify whether the underlying request had side effects before retrying. For a pure download, use its expected size/hash to reject incomplete data. The relay tests cover exact bytes/EOF, a slow reader receiving an oversized burst and abnormal remote exit using a fake exec session; they are not a large live Box transfer test. Historical Box evidence includes the earlier EphemeralBox investigation. Use current connector code for onboarding and the serverless record for persistent Box next-turn evidence. Do not copy native TTL or earlier absence of pause support into current configuration instructions. Sources: current lifecycle contract. Next: private previews, idle/wake, limits.