# WeKnora Sandbox Backends: Cube vs E2B Configuration Guide

> Explore WeKnora sandbox backends, comparing Cube vs E2B configuration. Choose between stateful Cube Sandbox or stateless E2B Sandbox for your WeKnora setup.

- Repository: [Tencent/WeKnora](https://github.com/tencent/WeKnora)
- Tags: how-to-guide
- Published: 2026-09-13

---

**WeKnora supports two distinct sandbox backends—the stateful Cube Sandbox (default) and the stateless E2B Sandbox—selected via the `sandbox_type` field in tenant configuration.**

The Tencent WeKnora project implements a flexible sandboxing architecture that lets administrators choose how agent skill scripts execute. Whether you need persistent state for long-running workflows or disposable environments for security-sensitive tasks, understanding these **sandbox backends supported by WeKnora** is essential for proper deployment.

## Overview of Sandbox Backends

WeKnora routes skill execution to one of two providers based on the `sandbox_type` value stored in [`internal/types/tenant_sandbox_config_entity.go`](https://github.com/Tencent/WeKnora/blob/main/internal/types/tenant_sandbox_config_entity.go). The choice determines whether sessions maintain state across calls or spin up fresh, isolated environments for every invocation.

### Cube Sandbox (Default)

The **Cube Sandbox** is the built-in, stateful backend that uses Docker containers to preserve files, variable state, and network connections throughout the session lifetime. When `sandbox_type` is omitted or set to `"cube"`, WeKnora instantiates this provider via [`internal/sandbox/cube_backend.go`](https://github.com/Tencent/WeKnora/blob/main/internal/sandbox/cube_backend.go).

Key characteristics include:
- Stateful execution environment with persistent storage
- Docker-network routing and file-mount handling
- Resource-limit enforcement (CPU, memory, PID) defined in [`internal/types/sandbox_network_policy.go`](https://github.com/Tencent/WeKnora/blob/main/internal/types/sandbox_network_policy.go)
- Ideal for multi-step workflows requiring data persistence

### E2B Sandbox

The **E2B Sandbox** integrates with the external "execution-to-backend" service, creating isolated, short-lived environments for each skill call. This backend is activated when `sandbox_type` is set to `"e2b"` in the tenant configuration.

Key characteristics include:
- Stateless execution with automatic teardown after TTL expiration
- Configuration via `e2b_sandbox_ttl_seconds` and custom endpoint URLs
- Implementation located in [`internal/sandbox/e2b_backend.go`](https://github.com/Tencent/WeKnora/blob/main/internal/sandbox/e2b_backend.go)
- Suitable for highly secure or stateless workloads where process isolation is paramount

## Configuration and Implementation Details

Both backends share a unified configuration schema defined in `TenantSandboxConfigEntity` ([`internal/types/tenant_sandbox_config_entity.go`](https://github.com/Tencent/WeKnora/blob/main/internal/types/tenant_sandbox_config_entity.go) line 37). The system resolves the appropriate provider at runtime through the sandbox service layer.

The routing logic distinguishes backends through a simple type switch. When a session initializes, WeKnora inspects the tenant's sandbox configuration and instantiates the corresponding backend implementation:

```go
func (s *SandboxService) ResolveBackend(cfg *TenantSandboxConfigEntity) Backend {
    switch cfg.SandboxType {
    case "e2b":
        return NewE2BBackend(cfg)
    default: // "cube" or empty → built-in Cube sandbox
        return NewCubeBackend(cfg)
    }
}

```

The `sandbox_type` field is also exposed through the REST API handler in [`internal/handler/sandbox_config.go`](https://github.com/Tencent/WeKnora/blob/main/internal/handler/sandbox_config.go) (line 86), allowing dynamic configuration updates without code changes.

## Practical Configuration Examples

### Setting Up a Cube Sandbox

To configure the default stateful backend, specify `"cube"` as the sandbox type. Optional parameters include CPU and memory limits:

```json
{
  "name": "production-cube-sandbox",
  "description": "Stateful Docker sandbox for complex workflows",
  "sandbox_type": "cube",
  "config": {
    "cpu_limit": 2,
    "memory_limit_mb": 4096
  }
}

```

### Configuring an E2B Sandbox

For stateless execution, set `sandbox_type` to `"e2b"` and configure the TTL and endpoint:

```json
{
  "name": "secure-e2b-sandbox",
  "description": "Stateless execution environment",
  "sandbox_type": "e2b",
  "config": {
    "e2b_sandbox_ttl_seconds": 300,
    "e2b_endpoint": "https://api.e2b.dev/run"
  }
}

```

### Accessing Sandbox Type in Go

The tenant struct in [`internal/types/tenant.go`](https://github.com/Tencent/WeKnora/blob/main/internal/types/tenant.go) (line 628) exposes the sandbox configuration through the `SandboxType` field:

```go
type Tenant struct {
    // … other fields …
    SandboxType string `json:"sandbox_type,omitempty"` // "cube" or "e2b"
    // …
}

```

## Summary

- WeKnora provides two **sandbox backends**: the stateful **Cube Sandbox** (`"cube"`) and the stateless **E2B Sandbox** (`"e2b"`)
- Backend selection occurs via the `sandbox_type` field in `TenantSandboxConfigEntity`, stored in [`internal/types/tenant_sandbox_config_entity.go`](https://github.com/Tencent/WeKnora/blob/main/internal/types/tenant_sandbox_config_entity.go)
- **Cube Sandbox** maintains persistent state using Docker containers and enforces network policies via [`internal/types/sandbox_network_policy.go`](https://github.com/Tencent/WeKnora/blob/main/internal/types/sandbox_network_policy.go)
- **E2B Sandbox** creates disposable environments through [`internal/sandbox/e2b_backend.go`](https://github.com/Tencent/WeKnora/blob/main/internal/sandbox/e2b_backend.go) with configurable TTL settings
- Both backends are managed through the unified API handler in [`internal/handler/sandbox_config.go`](https://github.com/Tencent/WeKnora/blob/main/internal/handler/sandbox_config.go)

## Frequently Asked Questions

### How do I switch between Cube and E2B sandboxes in WeKnora?

Update the tenant's sandbox configuration via the REST API endpoint handled in [`internal/handler/sandbox_config.go`](https://github.com/Tencent/WeKnora/blob/main/internal/handler/sandbox_config.go). Change the `sandbox_type` field from `"cube"` to `"e2b"` (or vice versa) in the JSON payload. The system automatically instantiates the correct backend implementation on the next skill invocation without requiring a service restart.

### Does the E2B sandbox preserve state between skill calls?

No. According to the implementation in [`internal/sandbox/e2b_backend.go`](https://github.com/Tencent/WeKnora/blob/main/internal/sandbox/e2b_backend.go), the E2B backend creates a fresh, isolated environment for every skill call and automatically tears it down after the TTL expires (configured via `e2b_sandbox_ttl_seconds`). This design ensures complete state isolation but requires external storage for data persistence across executions.

### Where is the sandbox type stored in the WeKnora codebase?

The `sandbox_type` value is persisted in the `TenantSandboxConfigEntity` struct defined in [`internal/types/tenant_sandbox_config_entity.go`](https://github.com/Tencent/WeKnora/blob/main/internal/types/tenant_sandbox_config_entity.go) at line 37. This record stores the sandbox name, description, and type identifier. The field is also mapped to the `Tenant` struct in [`internal/types/tenant.go`](https://github.com/Tencent/WeKnora/blob/main/internal/types/tenant.go), making it accessible throughout the application layer.

### What are the security implications of each backend?

The **Cube Sandbox** maintains long-running containers with potential network access defined in [`internal/types/sandbox_network_policy.go`](https://github.com/Tencent/WeKnora/blob/main/internal/types/sandbox_network_policy.go), requiring careful resource limit configuration to prevent container escape or resource exhaustion. The **E2B Sandbox** minimizes attack surface by using ephemeral, single-use environments that exist only for the duration of one skill call, though it requires trusting the external E2B service provider with code execution.