DOCSEARCHbyAlgolia
Submit Docs

OpenSandbox

repository·main·Indexed 11 days ago

https://github.com/opensandbox-group/opensandbox

A general-purpose sandbox platform for AI applications such as Coding Agents, GUI Agents, and RL Training. It provides unified APIs and multi-language SDKs to manage sandbox lifecycles, command execution, and file operations across Docker and Kubernetes runtimes. Includes the opensandbox-cli for management, opensandbox-supervisor for process wrapping with crashloop protection, and a Node Agent for CRI log collection.

Tokens
320.2K
Snippets
794
Records
1.2K
Agent score
93%

What's inside OpenSandbox

  1. Overview of the OpenSandbox Developer Console

    main

    The OpenSandbox Developer Console is a standalone React web application designed for day-to-day sandbox management. It provides a user interface for lifecycle operations that are typically handled via APIs or SDKs.

    Key capabilities include:

    • Sandbox Management: List, create, renew, delete, and retrieve endpoints for sandboxes.
    • Filtering: Search and filter sandboxes by state and metadata.
    • Creation: Provision new sandboxes using specific images and basic runtime options.

    The console is designed to work alongside existing automation. While the console provides a UI for human operators, existing SDKs and CLI tools continue to use the OPEN-SANDBOX-API-KEY for programmatic access without interference.

  2. Overview of OpenSandbox Node Agent

    main
    The OpenSandbox Node Agent is a component that runs once per Linux Kubernetes node. Its primary purpose is to collect CRI stdout and stderr from non-pooled OpenSandbox Pods. The agent enriches these logs with sandbox and Kubernetes identity information and writes them to either a durable local file sink or an Alibaba Cloud OSS sink.

  3. Overview of Task Executor

    main
    The task-executor is a lightweight component designed to run and manage short-lived tasks (processes or containers) within a Kubernetes Pod environment. It acts as a local agent that receives task specifications from Kubernetes controllers (such as BatchSandboxController) and executes them on the node where it is running. It provides a RESTful HTTP API for task lifecycle management.

  4. Overview of OpenSandbox Egress Sidecar

    main

    The Egress is an FQDN-based egress control sidecar that runs alongside a sandbox application container, sharing the same network namespace. It is designed to enforce network policies by controlling outbound traffic via domain names, IP addresses, or CIDR ranges.

    Key Capabilities

    • FQDN-based Allowlist: Control outbound traffic by domain (e.g., api.github.com) or use wildcards (e.g., *.pypi.org).
    • IP/CIDR Targets: Target specific IP addresses or ranges (e.g., 10.0.0.0/8).
    • Transparent Interception: Uses transparent DNS proxying on 127.0.0.1:15353 via iptables redirection, requiring no application-level configuration.
    • Dynamic DNS (dns+nft mode): When OPENSANDBOX_EGRESS_MODE=dns+nft is used, the sidecar resolves allowed domains and adds the resulting IPs to nftables with a TTL. This allows for a defaultAction: deny posture enforced at the network layer.
    • Credential Vault: Supports automatic injection of credentials (bearer, basic, API-key, etc.) for allowed hosts via transparent MITM proxying.
    • Privilege Isolation: Only the sidecar requires CAP_NET_ADMIN; the application container remains unprivileged.

  5. Overview of the OpenSandbox Kubernetes Controller

    main

    The OpenSandbox Kubernetes Controller is an operator that manages sandbox environments using Custom Resources (CRs). It is designed for automated lifecycle management, resource pooling for rapid provisioning, batch sandbox creation, and task orchestration within Kubernetes clusters.

    Key Capabilities:

    • Flexible Creation: Use pooled (pre-warmed) or non-pooled modes.
    • Batch Management: Create single sandboxes for real-user interaction or large batches (replicas=N) for high-throughput scenarios.
    • Resource Pooling: Maintain pre-warmed compute resources to reduce latency.
    • Pause and Resume: Persist sandbox state by saving the root filesystem as an OCI image, allowing you to release cluster resources between sessions.
    • Task Orchestration: Execute custom workloads (processes) within sandboxes using task templates.

  6. Overview of the Node Agent for Sandbox Collection

    main

    The Node Agent is a Linux Kubernetes component deployed as a DaemonSet (one Pod per node). Its primary purpose is to collect stdout and stderr streams from the main sandbox container of non-pool OpenSandbox Pods.

    Key functions include:

    • Discovery & Enrichment: It identifies sandboxes via the opensandbox.io/id label and enriches logs with metadata like sandbox_id, pod, namespace, node, container, and stream.
    • Data Pipeline: It processes records through a unified Source/Pipeline/Sink contract.
    • Reliable Delivery: It supports durable delivery (at-least-once) for specific sinks, using a mechanism where the Source cursor only advances after a Sink durably accepts a batch.
    • Extensibility: While v1 focuses on container logs, the architecture is designed to support future sources like system-call, file-audit, and network-audit collection.

  8. Explore OpenSandbox project structure and components

    main

    The OpenSandbox repository is organized into several key directories for different consumer needs:

    • SDKs: Multi-language support including Python, Java/Kotlin, TypeScript/JavaScript, C#/.NET, and Go.
    • Server: A Python FastAPI-based server managing the sandbox lifecycle.
    • CLI: The OpenSandbox command-line interface.
    • Components:
      • execd: The execution daemon for commands and file operations.
      • ingress: Traffic ingress proxy.
      • egress: Network egress control.
    • Kubernetes: Deployment configurations and examples for K8s.
    • Specs: OpenAPI definitions for the sandbox lifecycle and execution APIs.
    • Sandboxes: Implementations of runtime sandboxes.

  9. Understand the Node Agent component layout

    main

    The opensandbox-node-agent is a Go-based component designed for node-level sandbox collection (e.g., container logs). Its internal structure follows standard Go conventions and is organized into several functional packages:

    • pkg/config: Handles environment variable parsing and validation.
    • pkg/store: Manages the Kubernetes watch and sandbox identity (mapping Pods to sandbox identities).
    • pkg/source: Implements the Source SPI (Service Provider Interface) to ingest data (e.g., container-logs).
    • pkg/pipeline: Handles data enrichment, admission, batching, and acknowledgement logic.
    • pkg/sink: Implements the Sink SPI to persist data (e.g., OSS, durable files, or stdout).
    • pkg/state: Manages persistence using bbolt namespaces and schemas.
    • pkg/server: Provides health, readiness, and optional pprof endpoints.

    The component reuses components/internal for logging (zap), self-telemetry, safego, and version reporting.

  10. Run Chrome Browser in OpenSandbox

    main

    You can run a Chrome Browser instance within the OpenSandbox runtime. This setup exposes two primary remote access endpoints:

    1. VNC: For remote visual interaction with the browser.
    2. DevTools: For remote debugging via the Chrome DevTools Protocol.

    For detailed configuration and implementation steps, refer to the full documentation at docs/examples/chrome.md.

  11. Explore OpenSandbox usage examples

    main

    OpenSandbox provides several categories of ready-to-run examples for different workloads:

    Coding Agents

    Run AI agent frameworks and coding CLIs in isolated environments:

    • Claude Code, Gemini CLI, Codex CLI, Qwen Code, Kimi CLI (Moonshot AI)
    • LangGraph: State-machine workflows with sandbox integration.
    • Google ADK: Agent using OpenSandbox tools.
    • OpenClaw & NullClaw: Gateway integrations.

    Browser & Desktop

    Host browser workloads and full desktop environments:

    • Chrome: Chromium with VNC and DevTools access.
    • Playwright: Headless Chromium testing.
    • Desktop: Full desktop environment accessible via VNC.
    • VS Code: VS Code Web (code-server) running in a sandbox.

    Core Usage

    Fundamental SDK workflows and infrastructure patterns:

    • Code Interpreter: End-to-end SDK workflow.
    • AIO Sandbox: All-in-One setup.
    • Agent Sandbox: Kubernetes integration.
    • AKS + Kata: Deployment with Kata VM isolation, ingress, egress, and Credential Vault.
    • Windows: Windows sandboxes via KVM/QEMU.
    • Harbor Evaluation: Running Harbor agent evaluations.

    Storage

    Patterns for persistent and shared storage:

    • Host Volume Mount: Mounting host directories.
    • Docker PVC Volume: Named volume mounts.
    • Docker OSSFS Volume: OSS FUSE mounts.
    • Kubernetes PVC: Kubernetes PersistentVolumeClaim mounts.

  12. Typical OpenSandbox Use Cases

    main

    OpenSandbox is designed for AI-driven workloads and secure execution environments. Common scenarios include:

    • Coding Agents: Running tools like Claude Code, Gemini CLI, or Codex in isolated environments.
    • Browser Automation: Executing Chrome and Playwright workloads with controlled networking, filesystem, and runtime access.
    • Remote Development: Hosting VS Code Web or desktop-like environments for secure cloud-based development.
    • AI Code Execution: Safely running model-generated code, streaming outputs, and maintaining reproducible environments via code interpreters.