WeKnora Sandbox Backends: Cube vs E2B Configuration Guide

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. 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.

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
• 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
• 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 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:

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 (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:

{
  "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:

{
  "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 (line 628) exposes the sandbox configuration through the SandboxType field:

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
• Cube Sandbox maintains persistent state using Docker containers and enforces network policies via internal/types/sandbox_network_policy.go
• E2B Sandbox creates disposable environments through internal/sandbox/e2b_backend.go with configurable TTL settings
• Both backends are managed through the unified API handler in 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. 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, 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 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, 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}