OpenSandbox Integration

opensandbox is AgentCompass’s client adapter for an OpenSandbox lifecycle service, not a concrete sandbox runtime. AgentCompass uses the official Python SDK to request a sandbox and operate it through OpenSandbox’s common command and file APIs. The runtime configured on the server creates the actual workload and determines its placement and isolation strength. Selecting --env opensandbox does not select the underlying runtime in AgentCompass.

Understand the Integration

The official OpenSandbox architecture separates clients, the lifecycle service, and runtime backends. The official server currently supports Docker and Kubernetes runtimes, with runtime selection and security configuration handled on the server. See the OpenSandbox architecture.

Layer	Responsibility
AgentCompass opensandbox adapter	Translates Environment creation, command, and file operations into OpenSandbox SDK calls.
OpenSandbox lifecycle service	Handles API authentication, sandbox lifecycle orchestration, and request forwarding.
Server-side runtime	Creates the actual workload, pulls images, and determines placement, isolation, and available resources.

Before using the adapter, prepare an OpenSandbox service and select a server-side runtime that matches the evaluation. AgentCompass does not deploy the service or configure Docker, Kubernetes, registry credentials, or the underlying isolation mechanism for you.

Prepare the Integration

1. Deploy the lifecycle service by following the OpenSandbox Quick Start and installation guide.
2. Configure the runtime and authentication on the server. The selected runtime must be able to pull the evaluation image and provide the commands, directories, and resources required by the Benchmark and Harness.
3. Confirm that the AgentCompass host can reach the lifecycle service and that the server proxy can forward sandbox command and file requests.
4. If API authentication is enabled, prepare a key that can create and destroy sandboxes.

Connection settings default to OPEN_SANDBOX_DOMAIN and OPEN_SANDBOX_API_KEY. You can instead set domain and api_key in a private configuration file. Production deployments should enable an API key; do not commit real keys.

Validate the Configuration with run

The current adapter supports image-based creation only, so you must explicitly provide an image compatible with both the server-side runtime and the evaluation task. This example uses sample_ids to run one task:

agentcompass run <benchmark> <harness> "$MODEL_NAME" \
  --env opensandbox \
  --env-params '{"image":"registry.example.com/eval-image:tag"}' \
  --benchmark-params '{"sample_ids":["<sample-id>"]}'

Replace the placeholders with real component and sample IDs. The command above is a minimal agentcompass run check; see agentcompass run for model endpoint and other shared options.

opensandbox also supports agentcompass launch. Put shared settings under defaults.environment in the orchestration file, or request-specific settings under requests[].environment; write id: opensandbox and the adapter parameters at the same level. See the launch mapping rules.

AgentCompass currently has no built-in, provider-specific recipe for opensandbox, so it does not select an image or workspace automatically.

Parameter Reference

Pass parameters with --env-params, or place them under environments.opensandbox in a configuration file.

The complete command under “Validate the Configuration with run” already shows the minimum Environment parameter: the current adapter requires an explicit image.

Connection and Credentials

Field	Default	Meaning
api_key	OPEN_SANDBOX_API_KEY	API key for the OpenSandbox lifecycle service, not a registry or underlying-runtime credential. Leave it empty only when server-side API authentication is disabled.
domain	OPEN_SANDBOX_DOMAIN; the SDK uses localhost:8080 if unset	Root address of the lifecycle service. It may be host[:port] or an address with an http:// or https:// scheme. A value without a scheme uses HTTP; include https:// explicitly for an HTTPS service. Do not include /v1; the SDK appends it.

Image and Startup

Field	Default	Meaning
image	None; required	Container image that the server-side runtime must pull. This AgentCompass adapter supports image-based creation only. Configure private-registry credentials on the OpenSandbox server or runtime.
entrypoint	[]	Container entrypoint argument array passed to OpenSandbox, for example ["bash","-lc","python app.py"]; it cannot be a single shell command string. When left empty, the SDK uses ["tail","-f","/dev/null"] as its default entrypoint.

Identity and Metadata

The current AgentCompass adapter does not expose OpenSandbox sandbox name or metadata parameters. There are no corresponding fields under --env-params or environments.opensandbox.

Workspace and Environment Variables

Field	Default	Meaning
default_workspace_root	/workspace/	Non-empty fallback path given to the Harness when the Benchmark does not specify a task working directory. This field does not create a directory or configure storage; the image or task preparation must make the path available.
env_variables	{}	Environment-variable mapping injected at sandbox creation and command execution, for example {“LANG”:“C.UTF-8”}. Keys must match [A-Za-z_][A-Za-z0-9_]*; values are converted to strings.
shared_storage	[]	Ordered path mappings for an existing shared mount; this field does not provision or mount storage. Each item maps host_path on the AgentCompass host to env_path for the same content in the sandbox. When an upload source matches a mapping, AgentCompass copies it from the corresponding env_path inside the sandbox; unmatched sources are uploaded through the API.

The following object can be used directly as part of --env-params or placed under environments.opensandbox:

{
  "shared_storage": [
    {
      "host_path": "/mnt/shared",
      "env_path": "/mnt/shared"
    }
  ]
}

shared_storage.host_path and shared_storage.env_path must both be absolute, must not contain .., and must not be the filesystem root. host_path must be an existing host directory. env_path must already expose the same content in every sandbox and must be readable and searchable. If an upload source matches more than one host_path, the first configured mapping is used.

Resources

Field	Default	Meaning
resources	{}	String mapping passed as OpenSandbox resourceLimits, for example {"cpu":"2","memory":"4Gi"}. Keys, units, and available sizes are interpreted by the server-side runtime. When omitted, the current SDK uses {"cpu":"1","memory":"2Gi"}.

Network

The current AgentCompass adapter exposes no OpenSandbox-specific network parameters and does not yet implement shared network policies. network_policy, run_network_policy, and verifier_network_policy must all remain public. Network restrictions configured by the OpenSandbox service or server-side runtime still apply.

Lifecycle and Timeouts

Field	Default	Meaning
lifecycle_seconds	43200	Positive server-side expiration time requested for the sandbox, in seconds. The server may still remove the sandbox at this deadline when AgentCompass keeps the Environment.
request_timeout_seconds	120	Positive timeout for OpenSandbox SDK HTTP requests, in seconds. It does not replace command execution timeouts inside the sandbox.
ready_timeout_seconds	120	Positive maximum time, in seconds, to wait for the sandbox’s execd command and file services to pass their health check during creation. It does not mean that an application started by entrypoint is ready.

Parameter Sources

• Run agentcompass config docs env opensandbox to see the fields, types, and defaults supported by your installed AgentCompass version.
• See the official OpenSandbox Python SDK documentation for upstream connection, creation, and default behavior.

Use the agentcompass config docs env opensandbox output for accepted fields, types, and defaults; default_workspace_root and shared_storage are AgentCompass adapter fields. Use the upstream SDK, server configuration, and selected server-side runtime to determine how lifecycle-service requests are interpreted.

AgentCompass Adapter Scope

• The current adapter supports creating sandboxes only from image; it does not expose other startup sources available in the OpenSandbox API.
• The current adapter does not translate AgentCompass shared network policies into OpenSandbox networkPolicy, so it accepts only public and cannot switch policies between phases. OpenSandbox itself supports egress policies, and restrictions configured by the service or runtime may still affect connectivity.
• The AgentCompass host sends command and file operations through the OpenSandbox lifecycle-service proxy, so that proxy must be available.
• Normal Environment close requests sandbox destruction. There is no delete_on_close parameter. --keep-environment skips AgentCompass’s explicit destroy request but does not override the server-side lifecycle_seconds deadline.
• Harness or caller command timeouts are independent of request_timeout_seconds.

Troubleshooting

Symptom	What to check
image is reported as required	Set a registry image through —env-params or environments.opensandbox.image.
A lifecycle request or authentication fails	Check domain, api_key, and the OpenSandbox service logs. The API key does not authenticate the underlying runtime or image registry.
Creation fails or the image cannot be pulled	Check the server-side runtime, registry credentials, and the relevant Docker or Kubernetes logs.
The sandbox never becomes ready	Check the in-sandbox execution service and server proxy, then adjust ready_timeout_seconds to the observed startup time.
A resource request is rejected	Confirm that the connected server-side runtime accepts the keys, units, and shape in resources.
Shared-storage validation fails	Confirm that both paths refer to the same pre-mounted content and that the sandbox path is readable and searchable.
A network mode is rejected	The current AgentCompass adapter does not expose shared network policies; keep all three phases public.

Related Pages

• Official OpenSandbox Architecture
• OpenSandbox Server Configuration
• OpenSandbox Python SDK
• OpenSandbox API
• Environments Overview
• Configure an Environment
• Run Controls
• CLI Configuration Files