Banata

Core Concepts

Lifecycle

Understand how sandboxes move from creation to readiness, active work, pause, resume, and end, and how that affects application design.

Lifecycle is not just an implementation detail.
It affects:

  • when your app can send work
  • how you design async flows
  • how you manage cost
  • when outputs are safe to collect

The common lifecycle path

text
queued -> assigning -> ready -> active -> paused -> ready -> ended

Not every sandbox visits every state, but this is the normal shape.

What each state means

queued

The request was accepted, but the sandbox is not usable yet.

assigning

The sandbox is being prepared.

ready

The sandbox can accept:

  • commands
  • code execution
  • file operations
  • browser work
  • AI agent tasks

active

The sandbox is doing work now.

pausing

Pause was requested and the sandbox is moving toward a resumable state.

paused

The sandbox is suspended and can be resumed later.

ending

The sandbox is shutting down.

ended

The sandbox is finished.

failed

The sandbox could not continue.

Create vs launch

launch()

Use launch() when:

  • you want the SDK to wait until the sandbox is usable
  • you want the simplest integration path

create()

Use create() when:

  • your backend has its own queue
  • you want to create first and wait later
  • another worker should handle readiness

What “manage readiness yourself” actually means

If you use create(), you are separating:

  • creation
  • waiting

That is useful when your backend wants to:

  1. accept a job quickly
  2. enqueue it internally
  3. wait for readiness in a worker later

Example:

ts
const sandbox = await client.create({
  capabilities: {
    agent: { enabled: true, defaultAgent: "build" },
    browser: { viewport: { width: 1280, height: 800 } },
  },
});
 
await client.waitForReady(sandbox.id, 120_000);

Pause vs end

Use pause() when:

  • the work is unfinished
  • the workspace still matters
  • someone will resume later

Use kill() when:

  • the job is complete
  • outputs are already collected
  • you do not plan to continue

Checkpoints in the lifecycle

Checkpoints are useful before meaningful transitions:

  • before a risky browser step
  • before human handoff
  • after a valuable intermediate result

Long-running tasks and lifecycle

For long-running agent work:

  • keep the sandbox alive
  • prefer promptAsync()
  • track the task separately from the original request
  • use webhooks for completion

Practical production pattern

  1. launch or create a sandbox
  2. wait for ready
  3. queue an async agent task
  4. receive task completion via webhook
  5. collect outputs
  6. pause or end depending on whether more work is expected

Related pages