Skip to main content
A Session pins a working configuration and holds successive Runs. Creating one does not submit a task or prove that a cloud Sandbox can execute it. This page describes the source contract for creation, inspection, initial files and lifecycle operations. Paths include /v1; examples assume an authenticated backend and an origin in HEXAGON_API_URL without that prefix.

Create and preflight

Both accept the same strict JSON body and allow owner/application tokens. Preflight also invokes configured credential-ingress readiness handling and checks tenant-owned connection state, secrets and compatibility. It is not a pure offline schema check, a capacity reservation, a model inference or a cloud execution receipt. A successful preflight does not reserve its checked configuration against later changes.

Request fields

Saved-Agent Sessions cannot override identity, instructions, context, name, resources, network, required_capabilities or nonempty optional_tools. They still require explicit Sandbox/model IDs and required Tool bindings; do not assume saved bindings are automatically supplied by this endpoint. Environment values overlay the saved Agent’s defaults. An archived Agent cannot create new Sessions, including by selecting an older revision. Every declared Tool requires a binding, including optional-at-start Tools. Optional means readiness may be deferred, not that the binding may be omitted. Bound Sandbox/model and protected HTTP connections must be enabled and ready. Connections must belong to the tenant and match their expected kind. A saved Agent rejects undeclared Tool names and missing declared bindings.

Initialization and environment

Behavior text cannot contain NUL. File paths cannot be absolute, contain backslashes or empty/./.. segments. Behavior JSON and compiled initialization have additional 65,536-byte checks. Identity is behavioral guidance, not an authenticated principal. File references describe initial uploaded content; their existence, exact hash and valid text are checked when submitting a Run. Preflight does not certify that files have already been uploaded. Environment names follow ^[A-Za-z_][A-Za-z0-9_]{0,127}$. Reserved names include the HEXAGON_, OPENCODE_, PI_ prefixes and PORT, NODE_OPTIONS, PYTHONPATH, PYTHONHOME, LD_PRELOAD, LD_LIBRARY_PATH. Values are strings ≤16,384 characters without NUL; there may be at most 64 entries and 65,536 UTF-8 bytes of serialized JSON. Ordinary environment values are available to Agent processes; they do not provide the protected Provider/model credential boundary. See configuration and credentials.

Request example

Save this as session-request.json, replacing the two example UUIDs with your verified connection IDs. The all-zero suffixes are placeholders, not provisioned resources:
First preflight, then explicitly create using the same saved body:
Creation does not accept the Run submission idempotency guarantee. If its response is lost, inspect the original creation before retrying. Save the returned Session ID, then upload initial files and submit a Run.

Response shapes

Preflight returns ready: true, combination, readiness: {status:"ready", checked_at}, lifecycle and connections. Failure uses an error response rather than {ready:false}. combination is the resolved capability/protocol contract, not measured execution evidence. lifecycle includes mode (serverless, provider_managed, retained), preservation (filesystem, memory, provider_managed, none), automatic_wake: true and effective idle_timeout_seconds capped at timeout minus ten seconds. connections maps model and protected API aliases to implementation, raw_secret_in_sandbox:false and delegated_token_in_sandbox. Implementation is external_proxy_with_native_auth when native credential auth is declared, otherwise external_proxy. This map is not a list of Tool readiness statuses. Creation returns id, nullable agent_id/agent_revision, definition, env_names, state, nullable sandbox, created_at, updated_at. Environment values are not returned. definition contains effective behavior/resources/network, resolved capabilities/combination, optional initialization digest and OCI image, pinned connection config/version, tool_bindings, protected_api_bindings, message_policy:"reject_if_busy", lifecycle and credential boundary. Treat its evolving nested provider fields as versioned metadata, not a universal Sandbox schema.

Inspect the Session and initialization

GET /v1/sessions/{id} returns 200 with the Session fields above plus pause_scope. state is open, pausing, paused, resuming, closing or closed; sandbox is a nullable provider resource descriptor. A Session’s existence or open state is not proof of a live Harness process. Both owner/application tokens may read it. Missing/foreign IDs return 404 session_not_found.
GET /v1/sessions/{id}/initialization returns 200 with schema_version:1, session_id, created_at, source:{kind,agent_id,agent_revision}, definition, and environment:{names,values_redacted:true}. Kind is direct or agent. It reads the historical effective snapshot, not the latest Agent definition or current connection version.

Upload and list initial files

POST /v1/sessions/{id}/files allows owner/application tokens and returns 200 with {files:[{path,sha256,size}]} for the files in that request. Body: strict {files:[{path,content_base64}]}. There must be 1–100 entries with unique relative paths, each ≤500 characters and subject to the path restrictions above. Base64 strings use the schema’s padded Base64 alphabet and contain at most 2,097,152 characters each. Total decoded bytes per request cannot exceed 8 MiB. See limits for encoded versus decoded bounds. A file with the same path replaces the stored initial input while uploads remain permitted. Other paths remain intact. Uploads require an open Session with no submitted Run and no allocated Sandbox; they cannot edit a live workspace. Even an already cancelled first Run closes this initial-upload window. With initialization enabled, SOUL.md is reserved. Save this body as files-request.json (the example content is hello):
GET on the same path returns 200, {files:[{path,sha256,size}]} for stored inputs ordered by path. It lists metadata, not bytes or the current Agent-edited filesystem. Inspect these hashes when reconciling a lost upload response.
Upload-specific errors: 400 duplicate_input_path, 400 reserved_initialization_path, 413 upload_too_large, 409 workspace_already_started, 409 session_closed; malformed bodies use 400 invalid_request. Missing/foreign Session is 404. Structural validation can fail before a resource lookup.

Pause, resume and close

These routes exist when the lifecycle service is configured. Pause/resume require an owner token; close allows an application token too. All are POST operations, scoped to the tenant.
Logical scope session does not establish stopped compute. Native scope sandbox depends on Provider capabilities; provider-managed standby is reported separately. A completed transition can include compute_paused and provider_managed_standby, but a repeat at the target state may return only state/scope. Do not interpret absent fields as a full fresh inspection. Pausing requires no nonterminal Run; incompatible transition/scope requests return session_transition_pending or session_pause_scope_conflict. Unsupported native pause returns sandbox_pause_unsupported, all 409. Closing/closed Sessions reject pause/resume. Run submission can wake a paused Session; explicit resume is not required for every new task.
Explicit close rejects a nonterminal Run with 409 session_busy: cancel/observe it first. Close persists intent and reconciles owned resources before confirming closure. sandbox_creation_unconfirmed, sandbox_checkpoint_unconfirmed or sandbox_deletion_unconfirmed require inspection of resource operations; a timeout/error is not evidence of absence. Repeating close on the same Session reconciles its resources; an already closed Session returns {state:"closed"}. Exported artifacts and historical Runs remain accessible; preview access is invalidated. See resource reconciliation.

Lifecycle failure handling

A lifecycle response is an observation of a specific transition, not a promise that the Harness is already healthy. After resume, native/provider-managed paths can leave Runtime in restoring; the next execution must establish readiness. Do not turn a lost-resource or unknown-operation error into an automatic replacement Session. Malformed strict schemas return 400 invalid_request. Common domain failures include 404 agent_not_found, 404 agent_revision_not_found, 409 agent_archived, 404 connection_not_found, 400 connection_kind_mismatch, 409 connection_not_ready, 409 tool_not_ready, 400 missing_tool_binding, 400 undeclared_tool_binding, 400 ambiguous_variables and 413 initialization_too_large. Harness/model/network/capability incompatibility returns the corresponding compatibility reason with 400; credential readiness can fail before definition validation. Consult errors rather than assuming every failure is a cloud quota problem. This page does not substitute for the remaining operation references: tenant-wide Session lists/activity, sensitive environment retrieval, current authorization, per-Session connection revocation and access/preview grants. Their route permissions remain in the HTTP inventory; their behavior is described in connection lifecycle, private previews and initialization. Sources: Session schemas and operations, initialization, environment, file inputs, lifecycle, HTTP routes. These are source-reviewed examples; no HTTP or cloud execution is claimed by this reference. Related endpoint contracts: Session collections and activity, environment, authorization and proxy grants, artifacts and browser preview grants. These routes return distinct projections and have separate permissions; do not reuse a single Session response schema for all of them.

Decide whether to repeat a request

For uploaded notes.txt containing the five bytes hello, the metadata has size:5 and SHA-256 2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824. This is a calculated example, not a server response receipt. Upload returns the request’s file order; listing sorts by path, so compare by path and digest rather than array position. Neither response represents later Agent edits inside the Sandbox. Schema validation, domain validation and actual execution are separate stages. For example, an unknown top-level field fails the strict request schema, a syntactically valid but unavailable Harness fails catalog resolution, and a valid ready Session can still fail later during cloud provisioning. variables together with a nonempty env is rejected by domain handling, not by the initial Session schema alone. Do not classify all of these as identical validation failures or claim an HTTP schema fixture verifies cloud readiness.