> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Your first Sandbox runtime workflow

> Extend the verified create/execute/cleanup example with canonical file operations and explicit execution, lifetime, and output boundaries.

First complete [the HTTP quickstart](https://docs.stateset.com/stateset-sandbox/stateset-sandbox-quickstart-guide.md).
It supplies a provisioned URL, the right authentication, retained create identity, bounded
readiness, command-result checks, and cleanup. The examples here need a currently running
sandbox with authorized access; do not reuse an already stopped smoke-test ID.

## Write and read a file

Under the API-prefixed `SANDBOX_URL`, use the current canonical file route:

```bash theme={null}
curl --fail-with-body --silent --show-error \
  "$SANDBOX_URL/sandbox/$SANDBOX_ID/files" \
  --header "Authorization: ApiKey $STATESET_SANDBOX_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"files":[{"path":"/workspace/example.txt","content":"c2FuZGJveC1vaw=="}]}'

curl --fail-with-body --silent --show-error --get \
  "$SANDBOX_URL/sandbox/$SANDBOX_ID/files" \
  --header "Authorization: ApiKey $STATESET_SANDBOX_API_KEY" \
  --data-urlencode 'path=/workspace/example.txt'
```

Content is base64 for the bytes `sandbox-ok`. Decode the returned content and compare actual
bytes. A successful file response is separate from whether an agent produced a correct
answer. `/files/list` lists directory entries; GET `/files` reads the requested file.

## Execute and retain evidence

Use argv, save the original supported request key and returned execution ID, inspect the
confirmed exit/outcome, and verify output. A lost stream or `execution_result_unconfirmed`
requires [original receipt recovery](https://docs.stateset.com/stateset-sandbox/execution-and-recovery.md), not a new
command. For long workers use supervised processes and [prepared tasks](https://docs.stateset.com/stateset-sandbox/agent-tasks.md).

## Lifetime and sharing

Startup wait, command timeout and resource lifetime use different units/budgets. Check
returned expiry/headroom before extending; plan and durable-mode limits apply. Pause/recovery
preserves supported disk state, not a Python kernel or running process memory.

For files beyond sandbox termination, export artifacts and verify size/hash/expiry. For a
live port, create an authorized private tunnel with retained identity and supported store
configuration. See [artifacts and tunnels](https://docs.stateset.com/stateset-sandbox/artifacts-and-tunnels.md).

Finish with the [teardown check](https://docs.stateset.com/stateset-sandbox/stateset-sandbox-quickstart-guide.md#verify-teardown)
for the actual runtime you created. Accepted stop, API retirement, physical pod cleanup,
and billing reconciliation are separate observations.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.