Environment Overview

An Environment determines where evaluation commands run and where task files are stored. AgentCompass schedules the evaluation on the host, while task-file preparation and command execution usually use the selected Environment. The Benchmark determines where verification runs.

Core Concepts

Concept	Meaning
Environment	The execution environment used by one task. It provides command execution, file access, and a working directory.
provider	The Environment implementation selected with --env. It may manage an execution instance directly or delegate creation to a runtime behind an external service. An Environment provider is unrelated to the provider serving the model API.
sandbox	An isolated instance created for a task by a concrete execution backend. It may be a local container or a remote instance. opensandbox is an API integration rather than a backend itself; the connected service delegates creation to its configured backend. host_process creates no sandbox.
workdir	The Environment’s default command directory, selected with setup.workdir or inherited from the image or provider.
workspace	The task root selected by the Benchmark and passed to the Harness. It may equal the workdir, but it is not an Environment provider setting. Unless you use host_process or explicitly mount a directory, a path here is not the same path on the host.

Workspace resolution

TerminalBench 2, 2.1, and Verified, SkillsBench, and SWE-Marathon use the Environment’s actual current directory as their prepared workspace. They have no separate Benchmark workspace setting. Set setup.workdir to override the task’s environment.workdir; without either declaration, Docker retains the image’s WORKDIR. Dockerfile parsing is only a fallback in selected remote-provider recipes.

The Harness uses the prepared workspace, or the same actual-current-directory fallback when its protocol allows an empty workspace. It does not create another task root. OpenEvolve still requires a workspace supplied by the Benchmark. Benchmarks must isolate task files themselves when sharing an environment, including concurrent host_process runs.

A reused verifier runs in the prepared workspace. A fresh verifier uses its own Environment’s effective workdir, not the run workspace; use evaluation_setup.workdir to override it. Benchmarks with independent evaluation layouts, such as SWE-bench, retain their own layout fields.

Benchmarks with their own layout keep their directory settings independently of setup.workdir. PinchBench’s workspace_root is the parent of isolated task directories; WildClawBench uses its root directly as the task workspace; SciCode’s root is a local temporary-code directory. Changing the default command directory does not relocate an explicitly selected absolute Benchmark workspace. TauBench has no external Harness workspace: its isolated runtime directory holds inputs, results, and temporary data only.

Relative command directories and remote file paths share one base: the Environment’s effective default workdir. Providers resolve relative paths before passing them to SDK command or file APIs. Benchmarks that accept relative layouts resolve them before preparing materials and pass the resulting absolute task directory to the Harness and evaluator. Relative Harness output-file paths are relative to that task directory. SWE-bench workspace roots, and SWE-bench Pro evaluation directories, require absolute POSIX paths without .. because artifact paths are declared before environment startup.

Remove workspace_root from these Benchmarks’ configuration. If you need to override the task directory, use the shared Environment field, for example --env-params '{"setup":{"workdir":"/repo"}}'. Do not migrate an old /root fallback into a global override unless every task requires it. Environment parameters no longer accept workspace or default_workspace_root.

Task Execution Flow

The same Benchmark sample may run once or multiple times because of repeated evaluation or error retries. Each execution usually uses an Environment in this order:

1. AgentCompass resolves the Benchmark, Harness, and applicable Recipe to determine the task files, execution method, and required environment.
2. The provider opens an Environment. An isolated provider either creates a sandbox or asks an external service to create one; host_process uses a working directory on the host directly.
3. The Benchmark prepares the repository, dependencies, and other materials needed by the task in the workspace.
4. The Harness creates a run session and executes the agent through the Environment. If the evaluation has no separate Harness, the Benchmark handles this execution stage itself.
5. AgentCompass collects task outputs and runs verification. Depending on the Benchmark, verification may run on the host, reuse the current Environment, or open a separate verification Environment.
6. AgentCompass closes the Environment when the task ends. Normal cleanup is skipped only when the Environment is explicitly kept for debugging.

This sequence is why the Environment image, workdir, network, and resource settings—and the Benchmark workspace—directly affect whether an evaluation runs and whether its results are reproducible.

Choose an Environment Provider

Provider	Where commands run	Environment form	Use it when
host_process (default)	The host running AgentCompass	No sandbox isolation	The task is trusted, you are debugging locally, or it must directly use host files and tools.
docker	A Docker container on the host running AgentCompass	Container	You want a separate filesystem and reproducible image on a local machine.
daytona	A remote sandbox created by Daytona	Remote sandbox	You already use Daytona and want it to create and manage task environments remotely.
modal	A Modal cloud sandbox	Remote sandbox	You want on-demand cloud compute or GPU resources.
opensandbox	A sandbox created by the runtime behind the OpenSandbox service	Depends on the server runtime and security configuration	You have a reachable OpenSandbox lifecycle service and want to use its server-side runtime through the common API.

First decide whether the task is trusted and requires isolation. Then consider image availability, resources, network controls, and provider credentials. Each provider page documents its prerequisites, required parameters, and limitations.

opensandbox is AgentCompass’s adapter to the OpenSandbox API, not a fixed sandbox backend. See the official OpenSandbox architecture for how the service maps requests to a Docker or Kubernetes runtime backend.

After choosing a provider, you can configure its image, default workdir, resources, network, or lifecycle. The Benchmark owns the task workspace. See Configure an Environment for the available input methods and their override rules.

Next Steps

• Configure an Environment: pass parameters through the CLI, a configuration file, the Python SDK, or an orchestration file.
• Network Policies: control network access during setup, agent execution, and verification.
• Resource Limits: set CPU, memory, storage, and GPU resources for one Environment.