Sandbox Providers

Overview

Jinba Toolbox executes tool code in isolated sandbox environments. The sandbox system is designed around a provider-agnostic architecture: a shared interface package (@jinba-toolbox/sandbox-core) defines the contract, and individual provider packages (sandbox-e2b, sandbox-daytona) implement it. This separation means you can switch providers or add new ones without modifying any business logic.

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     API Server                              │
│                                                             │
│  Execution Service ──▶ SandboxProvider interface            │
│                                                             │
├─────────────────────────────────────────────────────────────┤
│                  Provider Implementations                   │
│       ┌────────────────┐       ┌─────────────────┐         │
│       │ sandbox-e2b    │       │ sandbox-daytona  │         │
│       │ (E2B Code      │       │ (Daytona SDK)    │         │
│       │  Interpreter)  │       │                  │         │
│       └────────────────┘       └─────────────────┘         │
├─────────────────────────────────────────────────────────────┤
│                    sandbox-core                              │
│           (Interfaces & Types only)                         │
└─────────────────────────────────────────────────────────────┘

Core Interface

The @jinba-toolbox/sandbox-core package contains only interfaces and types — no concrete implementations. All providers must conform to these contracts.

SandboxProvider

The factory that creates and resumes sandbox instances:

interface SandboxProvider {
  /** Create a new sandbox instance */
  create(options: SandboxCreateOptions): Promise<SandboxInstance>;
  /** Resume an existing sandbox by ID */
  resume(sandboxId: string, options?: SandboxResumeOptions): Promise<SandboxInstance>;
}

SandboxInstance

A running sandbox environment with code execution, shell commands, and filesystem access:

interface SandboxInstance {
  readonly sandboxId: string;
  readonly commands: SandboxCommands;
  readonly filesystem: SandboxFilesystem;

  executeCode(
    code: string,
    language: SandboxLanguage,
    options?: CodeExecutionOptions
  ): Promise<CodeExecutionResult>;

  kill(): Promise<void>;
  pause(): Promise<void>;
  getHost(port: number): Promise<string>;
}

SandboxCommands

Shell command execution within the sandbox:

interface SandboxCommands {
  run(
    command: string,
    options?: SandboxCommandOptions
  ): Promise<SandboxExecutionResult>;
}

SandboxFilesystem

File operations within the sandbox:

interface SandboxFilesystem {
  read(path: string): Promise<string>;
  readBytes(path: string): Promise<Uint8Array>;
  write(path: string, content: string | Uint8Array): Promise<void>;
  list(path: string): Promise<SandboxFileInfo[]>;
  exists(path: string): Promise<boolean>;
  mkdir(path: string): Promise<void>;
  remove(path: string): Promise<void>;
}

Key Types

type SandboxLanguage = "python" | "typescript";

interface SandboxCreateOptions {
  language: SandboxLanguage;
  runtime?: string;                  // Runtime version (e.g. "python3.11", "node22")
  packages?: string[];               // Packages to install
  envs?: Record<string, string>;     // Environment variables
  workingDirectory?: string;         // Working directory inside sandbox
  timeoutMs?: number;                // Timeout in milliseconds
  egressProxy?: SandboxEgressProxyConfig; // Network egress lockdown settings
}

interface CodeExecutionResult {
  success: boolean;
  output?: unknown;       // Parsed JSON output if available
  stdout: string;
  stderr: string;
  durationMs: number;
  error?: {
    name: string;
    message: string;
    traceback?: string;
  };
}

interface SandboxExecutionResult {
  exitCode: number;
  stdout: string;
  stderr: string;
}

E2B Provider

The @jinba-toolbox/sandbox-e2b package implements the sandbox interface using the E2B Code Interpreter SDK.

Configuration

import { createE2BProvider } from "@jinba-toolbox/sandbox-e2b";

const provider = createE2BProvider({
  apiKey: process.env.E2B_API_KEY!,
  templateId: "custom-template",  // Optional custom sandbox template
  egressTemplateId: "...",        // Optional template with the egress proxy tunnel
  timeoutMs: 300000,              // Default: 5 minutes
});

Option	Type	Default	Description
`apiKey`	`string`	(required)	E2B API key
`templateId`	`string`	`undefined`	Custom sandbox template ID
`egressTemplateId`	`string`	built-in template	Template that contains the egress proxy tunnel setup
`timeoutMs`	`number`	`300000`	Default timeout (5 minutes); the API server passes the ToolSet timeout (default 15 minutes)

How It Works

Sandbox creation: The provider creates an E2B sandbox, optionally using a custom template. When the egress proxy is enabled for your organization, tool runs use the egress template and are hardened before any user code runs.
Package installation: If packages are specified, pip install (Python) or npm install (TypeScript) runs inside the sandbox. Python standard-library modules are filtered out; for TypeScript, zod and tsx are always added.
Egress lockdown (only when the egress proxy is enabled for the organization): Outbound network traffic from the sandbox is routed through the Jinba egress proxy; the proxy credential never enters the tool’s environment.
Code execution: Python tool code is written to a file and executed through E2B’s runCode API in the Jupyter-like kernel; under egress lockdown it is run instead as a plain python3 <file> process as the sandbox user. TypeScript tool code is written to a .mts file and run with npx tsx as a regular Node.js process, so npm packages resolve normally.
Lifecycle: The sandbox is killed as soon as the run finishes.

Tool Code Wrapping

The API wraps your code before execution: the input JSON is passed to the entrypoint (run by default) as Input(**data) in Python or as a plain object in TypeScript, and the return value is printed as JSON on the last line of stdout, which becomes the run’s output.

Daytona Provider

The @jinba-toolbox/sandbox-daytona package implements the sandbox interface using the Daytona SDK.

Configuration

import { createDaytonaProvider } from "@jinba-toolbox/sandbox-daytona";

const provider = createDaytonaProvider({
  apiKey: process.env.DAYTONA_API_KEY!,
  apiUrl: "https://app.daytona.io/api",  // Default
  target: "us",                           // Region: "us" or "eu"
  timeoutMs: 300000,                      // Default: 5 minutes
});

Option	Type	Default	Description
`apiKey`	`string`	(required)	Daytona API key
`apiUrl`	`string`	`https://app.daytona.io/api`	Daytona API URL
`target`	`string`	`us`	Target region (`us` or `eu`)
`timeoutMs`	`number`	`300000`	Default timeout (5 minutes)

How It Works

Sandbox creation: The provider initializes the Daytona SDK and creates a sandbox with the specified language.
Package installation: If packages are specified, the provider runs pip install or npm install inside the sandbox.
Code execution: Tool code is executed via Daytona’s process.codeRun API.
Lifecycle: Sandboxes can be started, stopped, and deleted.

The Daytona provider does not implement the egress proxy lockdown and refuses egress-restricted runs. The console only offers E2B when creating a ToolSet; daytona can be selected through the API.

ToolSet Sandbox Configuration

When creating a toolset, you specify which sandbox provider and settings to use:

await client.createToolSet({
  slug: "data-tools",
  name: { default: "Data Tools" },
  description: { default: "Data processing tools" },
  sandbox: {
    provider: "e2b",          // or "daytona"
    language: "python",       // or "typescript"
    packages: [
      { name: "pandas", version: "2.0" },
      { name: "numpy" }
    ],
    resources: {
      cpu: "2",
      memory: "4Gi",
      timeout: 120000       // milliseconds; max 3600000, default 900000 (15 min)
    }
  }
});

Only resources.timeout currently affects execution (it bounds sandbox creation and the tool run); cpu and memory are accepted and stored but not applied by the providers. The SandboxConfig stored on each toolset:

interface SandboxConfig {
  provider: "e2b" | "daytona";
  language: "python" | "typescript";
  runtime?: string;
  packages: { name: string; version?: string }[];
  resources: {
    cpu?: string;
    memory?: string;
    timeout?: number;
  };
  providerConfig?: Record<string, unknown>;
}

Error Handling

All sandbox packages use a unified SandboxError type:

class SandboxError extends Error {
  constructor(
    message: string,
    code: SandboxErrorCode,
    cause?: unknown
  );
}

type SandboxErrorCode =
  | "CONNECTION_FAILED"    // Failed to connect to provider
  | "TIMEOUT"              // Execution timed out
  | "EXECUTION_FAILED"     // Code execution failed
  | "NOT_FOUND"            // Sandbox not found (resume)
  | "PERMISSION_DENIED"    // Operation not permitted
  | "RESOURCE_EXHAUSTED"   // Provider resources exhausted
  | "INTERNAL";            // Unexpected internal error

Adding a New Provider

The architecture is designed for extensibility. To add a new sandbox provider:

Create a new package

Create packages/sandbox-<provider> with the standard package structure.

Implement the SandboxProvider interface

Implement create() and resume() methods that return a SandboxInstance.

Add the provider case to the API server’s getSandboxProvider function. No changes to sandbox-core or business logic are needed.

REST API — Endpoints for managing toolsets and running tools
Versioning & Publishing — How sandbox config is frozen in versions
Security & Access Control — Isolation and tenant boundaries

​Overview

​Architecture

​Core Interface

​SandboxProvider

​SandboxInstance

​SandboxCommands

​SandboxFilesystem

​Key Types

​E2B Provider

​Configuration

​How It Works

​Tool Code Wrapping

​Daytona Provider

​Configuration

​How It Works

​ToolSet Sandbox Configuration

​Error Handling

​Adding a New Provider

​Related

Overview

Architecture

Core Interface

SandboxProvider

SandboxInstance

SandboxCommands

SandboxFilesystem

Key Types

E2B Provider

Configuration

How It Works

Tool Code Wrapping

Daytona Provider

Configuration

How It Works

ToolSet Sandbox Configuration

Error Handling

Adding a New Provider

Related