> ## Documentation Index > Fetch the complete documentation index at: https://agent-compass.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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](https://open-sandbox.ai/architecture/).
LayerResponsibility
AgentCompass opensandbox adapterTranslates Environment creation, command, and file operations into OpenSandbox SDK calls.
OpenSandbox lifecycle serviceHandles API authentication, sandbox lifecycle orchestration, and request forwarding.
Server-side runtimeCreates 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](https://open-sandbox.ai/getting-started/) and [installation guide](https://open-sandbox.ai/getting-started/installation). 2. [Configure the runtime and authentication](https://open-sandbox.ai/getting-started/configuration) 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`](/en/user_guide/modules/benchmarks/overview#shared-benchmark-fields) to run one task: ```bash theme={"system"} agentcompass run "$MODEL_NAME" \ --env opensandbox \ --env-params '{"image":"registry.example.com/eval-image:tag"}' \ --benchmark-params '{"sample_ids":[""]}' ``` Replace the placeholders with real component and sample IDs. The command above is a minimal `agentcompass run` check; see [`agentcompass run`](/en/user_guide/using_agentcompass/cli/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](/en/user_guide/using_agentcompass/cli/launch#mapping-rules). AgentCompass currently has no built-in, provider-specific [recipe](/en/user_guide/other_features/recipes) 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
FieldDefaultMeaning
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`: ```json theme={"system"} { "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
FieldDefaultMeaning
lifecycle\_seconds43200Positive 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\_seconds120Positive timeout for OpenSandbox SDK HTTP requests, in seconds. It does not replace command execution timeouts inside the sandbox.
ready\_timeout\_seconds120Positive 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](https://github.com/opensandbox-group/OpenSandbox/blob/main/sdks/sandbox/python/README.md) 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](/en/user_guide/modules/environments/configuration/network) into OpenSandbox `networkPolicy`, so it accepts only `public` and cannot switch policies between phases. OpenSandbox itself supports [egress policies](https://open-sandbox.ai/components/egress), 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
SymptomWhat to check
image is reported as requiredSet a registry image through --env-params or environments.opensandbox.image.
A lifecycle request or authentication failsCheck 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 pulledCheck the server-side runtime, registry credentials, and the relevant Docker or Kubernetes logs.
The sandbox never becomes readyCheck the in-sandbox execution service and server proxy, then adjust ready\_timeout\_seconds to the observed startup time.
A resource request is rejectedConfirm that the connected server-side runtime accepts the keys, units, and shape in resources.
Shared-storage validation failsConfirm that both paths refer to the same pre-mounted content and that the sandbox path is readable and searchable.
A network mode is rejectedThe current AgentCompass adapter does not expose shared network policies; keep all three phases public.
## Related Pages * [Official OpenSandbox Architecture](https://open-sandbox.ai/architecture/) * [OpenSandbox Server Configuration](https://open-sandbox.ai/getting-started/configuration) * [OpenSandbox Python SDK](https://github.com/opensandbox-group/OpenSandbox/blob/main/sdks/sandbox/python/README.md) * [OpenSandbox API](https://open-sandbox.ai/api/) * [Environments Overview](/en/user_guide/modules/environments/overview) * [Configure an Environment](/en/user_guide/modules/environments/configuration/overview) * [Run Controls](/en/user_guide/using_agentcompass/run_controls) * [CLI Configuration Files](/en/user_guide/using_agentcompass/cli/config)