Store

Each sandbox has a built-in key-value store. Values are arbitrary JSON — no schema required. Use it to persist agent progress, share state between steps, or cache intermediate results without touching the filesystem.

The store lives inside the sandbox's data plane and is accessed via the same short-lived JWT as exec and files.

Set a value

// Simple scalar
await sandbox.store.set('status', { value: 'processing' })

// Structured object
await sandbox.store.set('progress', {
  value: { step: 3, total: 10, score: 0.91 },
  ttl_seconds: 3600,
})

PUT /v1/store/{key}

{ "value": { "step": 3, "score": 0.91 }, "ttl_seconds": 3600 }

ttl_seconds is optional. Omit it for no expiry. Overwrites any existing value for that key.

Get a value

const entry = await sandbox.store.get('progress')
const state = entry.value as { step: number; total: number; score: number }
console.log(`Step ${state.step} of ${state.total}`)

GET /v1/store/{key}

{ "value": { "step": 3, "score": 0.91 }, "expires_at": "2024-05-11T11:00:00Z" }

Returns 404 when the key does not exist or has expired.

Delete a key

await sandbox.store.delete('temp_state')

DELETE /v1/store/{key}

{ "deleted": true, "ok": true }

List keys

const { keys } = await sandbox.store.list({ prefix: 'run_' })
console.log(keys)

GET /v1/store?prefix=run_&limit=100

{ "keys": ["run_1", "run_2", "run_3"], "truncated": false }

Use prefix to namespace keys and retrieve only those belonging to a particular run or agent.

Batch operations

await sandbox.store.batch([
  { op: 'set', key: 'result', value: { score: 0.95 }, ttl_seconds: 7200 },
  { op: 'delete', key: 'temp_state' },
])

POST /v1/store/batch

All operations in a batch apply atomically — either all succeed or none do.

{
  "operations": [
    { "op": "set", "key": "result", "value": { "score": 0.95 }, "ttl_seconds": 7200 },
    { "op": "delete", "key": "temp_state" }
  ]
}

{ "applied": 2, "ok": true }

Use cases

Agent step tracking — write the current step and any intermediate outputs at each decision point. If an agent crashes, resume from the last committed step.

for (let step = 0; step < steps.length; step++) {
  const result = await runStep(sandbox, steps[step])

  await sandbox.store.set(`step_${step}`, {
    value: { output: result.stdout, ok: result.ok },
  })
}

Passing data between forked branches — write shared config to the store before forking; each branch reads it independently.

await sandbox.store.set('config', { value: sharedConfig })

const branches = await Promise.all([sandbox.fork(), sandbox.fork(), sandbox.fork()])
// Each branch can read store.get('config')

TTL-gated caches — set a TTL so cached values expire automatically without manual cleanup.

await sandbox.store.set('api_response', { value: data, ttl_seconds: 300 })

Notes

Values are arbitrary JSON. Strings, numbers, arrays, and objects all work.
Keys are plain strings. Use a naming convention (e.g. agent_:id:_step_:n:) to avoid collisions in long-running sandboxes.
The store is not a replacement for a database — it has no indexing, no range queries, and no transactions beyond the batch endpoint.
Store contents are included in checkpoint snapshots, so a restore brings key-value data back to the state it was in at checkpoint time.