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.
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 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.