Skip to main content
Choose Modal for cloud Sandboxes, OCI images, domain egress restrictions, or filesystem snapshot recovery. Applications retain the same Session / Run API; the control plane manages image preparation, allocation, and restoration.

Account and configuration

Prepare a Token ID and Token Secret from the intended Modal workspace. The account needs Sandbox listing, creation, execution, termination, and relevant image permissions. Validation only lists Sandboxes; it does not establish every build/allocation permission. Submit credentials as a JSON string retained in the control plane, never in Agent environment. Do not invent resource fields beyond this schema. Initial provisioning can trigger a cloud image build. These examples use a local management client; see self-hosting for hosted initialization. Supply environment values privately. Rerunning creates additional connections, so save and reuse the ID.
Revalidate and enable after configuration or credential edits. Tokens must belong to the intended account/workspace; the current browser login does not change the ownership of a saved Token.

Built-in or OCI Harness

The built-in path derives an environment from connection.image and adds Node/npm, curl, git, and CA packages. Use the returned connection ID and model connection in the first Session, checking actual output, artifacts, and close. The OCI path uses a registered digest through image registration, rather than connection.image. One historical starting combination is:
  • Image: docker.io/nousresearch/hermes-agent@sha256:2fd023efbb8d3d2b0ce1a73d028b07370cff34f567cfe0e999553e8c327ea283.
  • protocol: hermes-v1; command: ["/opt/hermes/.venv/bin/hermes"].
  • Combination: Modal, openai-compatible, deepseek-ai/DeepSeek-V4-Flash; independently verified Python and TypeScript continuation, remote Tool, environment, artifacts, and cleanup.
  • Recorded on 2026-11-18 in Harness delivery evidence. This does not cover all endpoints or later versions and is not a fresh run for this page.
Private images use a registry Secret with username/password associated during registration. Registry credentials and Modal Tokens serve different purposes and cannot replace each other. OCI preparation installs Python, Node, Bash, and other Runtime prerequisites as root using Alpine/Debian-family package managers, then clears Entrypoint/Cmd. Runtime launches the registered command separately. Current code reapplies the recorded image USER to the derived image, while existing repository runtime notes report Modal execution as root. Do not treat the USER declaration as a verified isolation boundary. Verify actual uid for the exact combination if execution identity matters. The source digest does not describe an unchanged filesystem after preparation.

Private access and network policy

The connector maps domain allowlists to Modal’s native egress restrictions. Follow network policy, include required task/credential paths, and probe both allowed and denied destinations. Control-plane model access and direct Sandbox internet traffic are different paths. Preview uses a server-side Connect Token Cookie through the Hexagon proxy. Use Hexagon preview authorization; do not send Modal account Tokens or private connection Cookies to the browser. The user service must listen on the right port and remain alive.

Idle snapshots and the next turn

Modal snapshots the filesystem, terminates the old Sandbox, and recreates from the snapshot. Session identity remains stable while the underlying resource ID can change. Persist Session IDs, not provider URLs as stable application entrypoints. The next submit triggers restoration and Runtime preparation. Files and managed conversation data can continue; arbitrary processes, memory, and network connections are not preserved guarantees. Preview services may need restarting. A Run waiting for authorization or approval remains active rather than idle. Snapshot and restore have independent durable operation records. Unknown snapshot outcomes or lost restore responses remain subject to reconciliation instead of duplicate allocation. Follow idle and wake to verify both turns, files, conversation, resource mapping, and cleanup. A successful single OCI turn does not prove recovery.

Close and diagnose

Close terminates current Session compute and handles its tracked snapshots. Shared Modal Apps and general image caches are not all deleted with one Session. A closed Session also does not prove the provider account contains no other billable resources. This page was reviewed against the connector, registration evidence, and snapshot cleanup. No cloud task was rerun. Later success does not erase failed historical attempts. Consult the Harness serverless matrix for exact recovery scope. Sources: Modal connector, checkpoint operations, cleanup lifecycle. Next: OCI Harness, reconciliation.

Inspect one snapshot restoration

Record Session S, first Sandbox A and its checkpoint operation before waiting for idle. After snapshot/recreate, query S again for current Sandbox B rather than continuing to address A. The second Run remains attached to S; verify the file bytes and native conversation identity independently. Keep the snapshot ID until its cleanup is confirmed, even after B executes successfully. For an application using SQLite-backed Harness history, file existence alone is particularly weak evidence. The November 19 serverless record documents Modal/OpenClaw’s initial file-identity failure after filesystem restore and the bounded copy-up repair. Both initial failures remain failures; subsequent continuation checks do not imply arbitrary databases or running processes are preserved. Use the matrix’s exact Harness/SDK row and the recorded file/native-session checks. This snapshot path does not promise to preserve the UID of every image, a running HTTP process, a live socket or arbitrary memory. Inspect actual execution identity for your digest; reestablish services only after confirming the restored workspace and original invocation state. Do not blindly start another Harness to compensate for ambiguous recovery. Additional sources: Modal integration notes, image contract. Next: OCI registration, idle and wake, resource reconciliation.