OpenSandbox Runtime

Relevant source files

• e2e/testdata/sandbox-mcp/evals/eval.yaml
• go.mod
• go.sum
• internal/runtime/opensandbox.go
• internal/runtime/opensandbox_test.go

The OpenSandboxRuntime provides remote code execution capabilities by provisioning on-demand sandboxes via the OpenSandbox SDK. It implements the runtime.Runtime interface, allowing skill-up to execute agent instructions and evaluation scripts in a secure, isolated, and remote environment.

Overview and Provisioning

The runtime manages the lifecycle of a remote sandbox, from creation to cleanup. Provisioning is triggered by the Create method, which utilizes the OpenSandbox SDK to request a new environment based on a container image or a sandbox template.

Configuration and Authentication

The runtime requires several configuration parameters, typically provided via environment.kwargs in eval.yaml or environment variables:

• API Key: Provided via the OPENSANDBOX_API_KEY environment variable internal/runtime/opensandbox.go39
• Base URL: Specified via environment.kwargs.base_url or OPENSANDBOX_BASE_URL internal/runtime/opensandbox.go34-38
• Image/Template: The runtime requires either environment.image or environment.sandbox_template to define the environment internal/runtime/opensandbox.go157-172
• Parallelism: File transfer concurrency is set via file_transfer_parallelism (defaulting to 8) internal/runtime/opensandbox.go43

Provisioning Flow

The Create function internal/runtime/opensandbox.go152-193 initializes the connection and calls createOpenSandbox (a wrapper around the SDK's LifecycleClient) to provision the remote resource internal/runtime/opensandbox.go65-112

Provisioning Sequence

Sources: internal/runtime/opensandbox.go152-193 internal/runtime/opensandbox.go65-112

Workspace and File Transfer

The OpenSandbox runtime defaults the remote workspace to /workspace unless overridden by WorkspaceMount internal/runtime/opensandbox.go27 internal/runtime/opensandbox.go144-148

Batch File Upload

To optimize network overhead and stay within system limits (e.g., ulimit -n), UploadFiles implements a batching strategy. Files are uploaded in chunks defined by openSandboxUploadBatchSize (set to 128) internal/runtime/opensandbox.go48

Key characteristics of file transfer:

• Parallelism: Controlled by file_transfer_parallelism (default 8) internal/runtime/opensandbox.go43
• Mapping: Local paths are mapped to the remote workspace using filepath.Rel to maintain directory structures internal/runtime/opensandbox.go274-295
• Implementation: Uses opensandbox.UploadFileEntry to transport file content and metadata internal/runtime/opensandbox.go57

Data Flow: File Upload

Sources: internal/runtime/opensandbox.go255-324 internal/runtime/opensandbox.go43-48

Network Policy

The runtime supports fine-grained egress control via the NetworkPolicy configuration. This is critical for evaluations that require internet access (e.g., downloading dependencies) while maintaining a "secure by default" posture.

The allow_declared policy is the primary mechanism for controlled egress:

• Default Action: When allow_declared is used, the default action is set to deny internal/runtime/opensandbox.go617-622
• FQDN Egress: Specific hostnames or wildcards (e.g., pypi.org, *.github.com) provided in AllowedEgress are added to the Egress rules with an allow action internal/runtime/opensandbox.go623-633
• Deny All: If the policy is set to deny_all, all egress is blocked by default internal/runtime/opensandbox.go614-616

Sources: internal/runtime/opensandbox.go606-636 internal/runtime/opensandbox_test.go126-200

Execution and Lifecycle

Execution within the sandbox is handled by Exec, which wraps the SDK's RunCommandWithOpts.

Command Execution

The Exec method performs the following:

1. Environment Merging: Merges runtime-level environment variables with command-specific overrides internal/runtime/opensandbox.go376-381
2. Working Directory: Commands are executed relative to the workspace path internal/runtime/opensandbox.go385
3. Stream Handling: Standard output and error are streamed back via opensandbox.ExecutionHandlers internal/runtime/opensandbox.go387-392

Sandbox Lifecycle

The lifecycle is governed by the Delete configuration internal/runtime/opensandbox.go205-214:

• Cleanup: If Delete is true (default), the sandbox is destroyed via Kill when the runtime is closed internal/runtime/opensandbox.go211-214
• Persistence: If Delete is false, the sandbox remains active, and the runtime simply closes the local connection. The sandbox ID is logged for future manual debugging internal/runtime/opensandbox.go205-209
• Timeout: Sandboxes are provisioned with a TimeoutSeconds (from environment.sandbox_timeout) to ensure they are eventually reclaimed by the server even if the client crashes internal/runtime/opensandbox.go176

Code Entity Mapping

The following diagram maps high-level runtime operations to specific code entities and SDK interfaces.

Entity Relationships

Runtime Interface Mapping

Runtime Method	OpenSandbox Implementation	SDK Call
Create	Provisions remote sandbox	LifecycleClient.CreateSandbox internal/runtime/opensandbox.go86-96
Exec	Runs command in sandbox	sandbox.RunCommandWithOpts internal/runtime/opensandbox.go387-392
UploadFiles	Batched file transfer	sandbox.UploadFiles internal/runtime/opensandbox.go316
DownloadFile	Fetches single file	sandbox.DownloadFile internal/runtime/opensandbox.go337
MergeEnv	Updates local env map	N/A (Local state) internal/runtime/opensandbox.go420-425
Close	Deletes or detaches	sandbox.Kill or sandbox.Close internal/runtime/opensandbox.go205-214

Sources: internal/runtime/opensandbox.go358-411 internal/runtime/opensandbox.go196-221 internal/runtime/opensandbox.go50-61