Sandboxes

A sandbox is the main unit of work in Banata.

It is the remote workspace where your:

• commands
• code
• browser state
• AI agent work
• handoff flow
• files
• outputs

all come together.

What a sandbox is for

The right way to think about a sandbox is:

one meaningful workflow, running in one consistent environment

Examples:

• research a group of sites and produce a report
• log into a service, complete a manual approval, then continue automatically
• transform a group of files and return the outputs
• run a browser-led workflow that saves artifacts your app downloads later

What you configure when creating a sandbox

The main configuration points are:

• region
• env
• capabilities

Example:

const sandbox = await client.create({
  region: "iad",
  env: {
    OPENROUTER_API_KEY: process.env.OPENROUTER_API_KEY!,
    OPENROUTER_MODEL: "openai/gpt-5.3-codex",
    OPENROUTER_SMALL_MODEL: "openai/gpt-5.3-codex",
    APP_URL: "https://example.com",
    JOB_ID: "job_42",
  },
  capabilities: {
    agent: { enabled: true, defaultAgent: "build" },
    browser: {
      viewport: { width: 1440, height: 900 },
    },
    documents: { libreofficeHeadless: true },
  },
});

If the sandbox will run AI agent tasks, the most important part of that example is the env block.

Treat these as required for agent-enabled sandboxes:

• OPENROUTER_API_KEY
• OPENROUTER_MODEL

Recommended:

• OPENROUTER_SMALL_MODEL

Region

region is a placement preference.

Use it when:

• your users are mostly in one geography
• you want the browser closer to a target service
• latency matters for human preview or handoff

The actual assigned region is returned on the sandbox once placement is complete.

Environment variables

Use env for values that belong to this specific workflow.

Good examples:

• target URLs
• customer-specific settings
• model or provider settings for the task
• credentials the agent may need later
• identifiers from your own system

Think of env as job-scoped context, not account-wide configuration.

For AI agent work, this is the minimum recommended shape:

env: {
  OPENROUTER_API_KEY: process.env.OPENROUTER_API_KEY!,
  OPENROUTER_MODEL: "openai/gpt-5.3-codex",
  OPENROUTER_SMALL_MODEL: "openai/gpt-5.3-codex",
}

If you omit these values, sandbox creation can still succeed, but the agent path may not have the model configuration it needs to complete prompts.

Capabilities

Capabilities tell Banata what the sandbox should be prepared to do.

Typical capability choices:

• enable the AI agent for multi-step work
• enable the browser for web workflows
• enable document tools for conversion and file-heavy jobs
• enable recording when you need an audit trail
• set outbound proxy configuration on supported plans

How to choose the right sandbox boundary

This matters more than it first appears.

A sandbox should usually map to:

• one customer job
• one workflow run
• one approval flow
• one automation unit with shared files and browser state

Why:

• job ownership stays clear
• files stay easier to reason about
• handoff is easier to scope
• cleanup becomes straightforward

Sandbox states

You will see these states most often:

When to create vs launch

Use launch() when:

• you want a usable sandbox returned directly
• you want the SDK to wait for readiness
• you want the simplest onboarding flow

Use create() when:

• your own system already has job orchestration
• you want to create first and wait later
• you want your caller to control readiness timing explicitly

When to pause, resume, or end

Use pause() when:

• the work is incomplete
• you want to keep the workspace
• you want to continue later

Use kill() when:

• the job is complete
• the sandbox is no longer needed
• you already retrieved the outputs you care about

Practical design advice

A strong first design is:

1. one job enters your backend
2. your backend launches a sandbox
3. your backend queues one or more agent tasks
4. the agent writes results into /workspace
5. Banata notifies your backend when important work is done
6. your backend reads files or downloads artifacts
7. your backend ends the sandbox

Related pages

• Lifecycle
• Execution
• Capabilities
• Browser Workflows