Banata

Core Concepts

Network & Access

Use region, environment variables, and supported outbound routing controls to shape how a sandbox behaves for a particular job.

Most sandbox configuration is about context, not about low-level infrastructure choices.

This page is about the inputs that shape:

  • where a sandbox starts
  • what configuration the job sees
  • how outbound access should behave

Region

Use region when a workflow should start closer to a particular geography.

ts
const sandbox = await client.create({
  region: "iad",
});

Good reasons to set a region:

  • most of your users are in one area
  • the workflow targets a service where latency matters
  • a person will use the preview and you want lower interaction delay

Treat region as a placement preference for the job.

Environment variables

Use env to pass job-specific configuration.

ts
const sandbox = await client.create({
  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://app.example.com",
    CUSTOMER_ID: "cust_123",
    JOB_ID: "job_456",
  },
});

Good uses for env:

  • URLs
  • customer identifiers
  • credentials the workflow may need later
  • model or provider settings
  • tenant-specific configuration

For AI agent work, the model provider values should be explicit.

Use:

  • OPENROUTER_API_KEY
  • OPENROUTER_MODEL

Recommended:

  • OPENROUTER_SMALL_MODEL

Example:

ts
const sandbox = await client.create({
  env: {
    OPENROUTER_API_KEY: process.env.OPENROUTER_API_KEY!,
    OPENROUTER_MODEL: "openai/gpt-5.3-codex",
    OPENROUTER_SMALL_MODEL: "openai/gpt-5.3-codex",
    JOB_ID: "job_456",
  },
  capabilities: {
    agent: { enabled: true, defaultAgent: "build" },
  },
});

Without these values, the browser and filesystem can still work, but agent prompts may not have the provider configuration they need.

The key idea is:

  • env belongs to this sandbox job
  • not to your whole Banata account

Outbound routing on supported plans

Some workflows need outbound traffic to leave through a controlled path.

On supported plans, you can configure outbound routing like this:

ts
const sandbox = await client.create({
  capabilities: {
    browser: {
      byoProxyUrl: "http://user:pass@proxy.example.com:8080",
    },
  },
});

Use this when:

  • your traffic must leave through your own proxy route
  • you need a controlled network path for the workflow

How to think about this page

This page is really about sandbox context:

  • where the job runs
  • what values the job can see
  • how outbound network access should behave

That context should be chosen per workflow, not treated as a global setting for everything.

Related pages