Skip to main content
Run a Harness in E2B while Hexagon manages tasks, private previews, and resource lifecycle. This page describes the current E2B connector. Use an account credential authorized to create and delete the target Sandboxes; the OCI path also needs Template build and deletion permissions.

Template and connection

Prepare an E2B API key and an available template identifier. The connection schema contains only template, defaulting to base. Do not add undefined CPU or memory fields to config. Built-in Harnesses use this template; its configuration determines machine resources. Built-in OpenCode requires at least 2048 MiB. Do not assume the default base meets that requirement. Choose an explicitly configured template and inspect actual resource information. Pi and custom Harnesses also require interpreter, dependency, and real memory checks; successful installation is insufficient. Supply the following environment values through private configuration. These examples create a new connection; rerunning creates additional connections, so retain and reuse the returned ID. The local client targets a local workspace; see self-hosting for hosted client initialization.
Validation performs list_sandboxes. It does not run a model or a full Harness and does not prove that the template can allocate successfully. Explicitly enable after ready validation. Revalidate and enable after template or credential changes; existing Sessions retain their pinned configuration.

Complete a first task

Use the returned ID as the Sandbox input in the first Session tutorial, with an enabled, validated model connection and compatible Harness. Its Python and TypeScript examples independently cover creation, Run, artifacts, and close. Success in one SDK does not substitute for the other. Start with a small task writing fixed content to the export directory. Check terminal state, actual response, and downloaded bytes. For previews, have the task start a service and use the authorized Hexagon private preview entry. Public traffic is disabled; the control plane uses the provider traffic token in its proxy, never as a browser credential or share-link parameter. Completion means successful execution, readable artifacts, correct preview authorization where required, and confirmed resource cleanup after close. Listing or allocating alone is insufficient.

OCI image path

For a registered public OCI Harness, E2B builds a Session-owned Template, currently with 2 CPU / 4096 MiB. This path selects the prepared template; putting an image name into the connection template field does not invoke OCI preparation. Image preparation and compute creation have separate operation records. Follow the OCI guide to register, record the digest, and preflight. E2B currently does not declare private_oci_image. Do not bypass this by placing registry passwords in ordinary environment. A completed image build does not verify Harness, Tool, or conversation behavior. After a lost build receipt, reconciliation looks for the Template belonging to the original operation. If the current build cannot be reliably identified, the outcome remains unknown instead of blindly rebuilding. Close handles compute before deleting the Session-owned Template. A shared user-configured template is not deleted as a Session-owned image.

Networking, idle, and recovery

E2B declares network_allowlist. It restricts Sandbox egress; include required destinations following network policy and verify real allowed/denied probes. Do not troubleshoot by putting account credentials into the Sandbox. Idle uses native pause, with connect on the next turn. Submit another Run to the same Session; no direct provider resume call is needed. The strategy preserves memory and filesystem, but independently verify the selected Harness’s second turn, conversation, and file continuity. Active Runs, including authorization/approval waits, are not idle suspension candidates. Close is terminal; pause is not deletion. E2B also reports provider runtime expiry. Hexagon lifecycle and reconciliation track resources; stopping a local process does not prove cloud absence.

Diagnose and verify

The E2B SDK owns its dispatcher; the connector explicitly selects environment proxy settings. NODE_USE_ENV_PROXY=0 disables that selection. Diagnose control-plane outbound connectivity as well as Sandbox network policy. This page is implementation-reviewed; cloud tasks were not rerun. Historical built-in dual-SDK results are in the execution matrix, with idle branches in the serverless ledger. Do not extend built-in success to a new OCI image. Sources: E2B connector, image contract. Next: first task, idle and wake, cleanup reconciliation. Later evidence: the E2B OCI increment records independent OpenCode Python/Chat and TypeScript/Messages journeys, byte-level recovery and template cleanup. It does not cover every SDK/protocol intersection; failed attempts remain recorded. See reading combination evidence.

Keep three template/resource identities separate

The base schema default is a name, not a verified memory specification. The serverless record preserves an E2B/OpenCode failure on a 1 GiB base template and the subsequent selection of the configured 2 GiB template. For an OCI path, the connector’s build request explicitly uses 2 CPUs and 4096 MiB; this does not change the resources of the built-in connection template. For domain enforcement, the public API network record compares allowed and denied requests inside real E2B resources. It uses a deterministic probe Harness and TypeScript, not a model-driven dual-SDK task. For built-in Web execution and browser access, use the Web journey and independent Python journey, preserving their dates and combinations. Do not relabel a later version or a new template as having passed those historical runs.