StateSet API Docs

Start with the Sandbox quickstart. It verifies deployment access, creation, command execution, and teardown using the controller’s HTTP contract. Complete that check before running generated code or a longer workflow.

Define one bounded job

For a first data-processing task, use a synthetic orders CSV and ask the runtime to compute its row count and total. Record the input file hash and expected result before invoking an agent. Use decimal arithmetic for monetary values and keep the currency explicit.

Task: summarize the supplied synthetic orders CSV.
Input: /workspace/orders.csv; amount values are decimal USD strings.
Output: /workspace/summary.json containing row count, currency, and total.
Use decimal arithmetic. Do not call external services or modify source records.
Report the command, exit code, and output file used to verify the result.

The prompt describes the task; runtime permissions and network configuration enforce its boundary. An instruction alone does not disable network access or filesystem operations.

Move inputs into the runtime

Use the deployment’s file write contract and file read contract. Confirm the route against the deployed controller: historical exports and controller versions have used different file-route aliases. This is recorded in the spec overlay; do not guess an alias after a 404. File content is base64-encoded on the documented write interface. Use absolute paths inside /workspace, reject traversal, and verify the decoded result after reading it back. File paths are runtime paths, not paths on the assistant’s host machine.

Execute and inspect

Use command execution with an argv array when possible. Set the command timeout, preserve stdout and stderr, and inspect exit_code. An HTTP 200 can contain a command failure. Read the output file independently and compare its row count, currency, and decimal total with the expected fixture. An agent’s prose summary does not replace that comparison.

Checkpoint	Evidence
Correct runtime	Returned sandbox ID and expected workspace
Correct input	File identity and decoded content match the fixture
Completed command	Saved execution result and exit code
Correct output	Parsed JSON with independently checked values
Cleanup	Stop result followed by a terminal status or authorized `404`

Lifetime and interruption

Creation and extension have different constraints; read each endpoint’s schema. Do not assume an extension succeeded because the request was accepted. Read the updated expiry and compare it with the job’s expected duration. A local client timeout does not prove remote execution stopped.

If execution or cleanup becomes uncertain, preserve the sandbox ID and inspect the existing runtime. Creating another sandbox or resubmitting a command can duplicate work and usage.

For persistent agent workflows, use the agent-session guide and verify rotation, budget, and stop behavior on the selected deployment.

Add capabilities deliberately

Capability	Reference	Acceptance check
Expose a service	Tunnels	Expected port, token scope, and expiry
Use a provider proxy	Inference	Authorized provider and redacted credentials
Monitor changes	Webhooks	Signature verification and duplicate-event handling
Connect an agent	Sandbox MCP	Tool trace and independent runtime result

Finish by rerunning the teardown check and recording the task’s IDs and outcomes in your operational log.

Last modified on September 21, 2026

Overview

Quickstarts

End-to-end

Commerce Workflows

Order Management

Returns & Warranties

Supply Chain

Agent Development

Knowledge & RAG

Response Features

Advanced Features

Integrations

Commerce Network

Self-Hosted

Best Practices

E-commerce Workflows

Give Your Agent an Isolated Runtime

Define one bounded job

Move inputs into the runtime

Execute and inspect

Lifetime and interruption

Add capabilities deliberately

​Define one bounded job

​Move inputs into the runtime

​Execute and inspect

​Lifetime and interruption

​Add capabilities deliberately

Define one bounded job

Move inputs into the runtime

Execute and inspect

Lifetime and interruption

Add capabilities deliberately