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.

Store contents are included in checkpoint snapshots — forking or restoring also forks or restores the store.

Set a value

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

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

sandbox.store.set("status", "processing")  # stored as {"v": "processing"} on the wire

sandbox.store.set("progress", {"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')
console.log(`Step ${entry.value.step} of ${entry.value.total}`)

entry = sandbox.store.get("progress")
state = entry.value  # {"step": 3, "total": 10, "score": 0.91}
print(f"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')

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)

result = sandbox.store.list()
print(result.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' },
])

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 },
  })
}

for i, step in enumerate(steps):
    result = run_step(sandbox, step)

    sandbox.store.set(f"step_{i}", {"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')

sandbox.store.set("config", shared_config)

branches = [sandbox.fork(), sandbox.fork(), sandbox.fork()]
# Each branch can read sandbox.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 })

sandbox.store.set("api_response", data, ttl_seconds=300)

Notes

Values are arbitrary JSON. Strings, numbers, arrays, and objects all work. In Python, non-dict values are wrapped as {"v": value} on the wire — get(key).value is always a dict.
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.