Modal

The Modal provider creates one cloud sandbox for each task execution. Use it for Linux task images when you need elastic compute or do not want to consume local resources.

A matched recipe can supply defaults such as the image and workspace; compatible explicit settings are usually preserved. Modal requires a valid account and a token that can create sandboxes.

Before You Start

For local development, follow Modal user account setup and run modal setup. For CI or shared runners, create a Modal service user and set MODAL_TOKEN_ID and MODAL_TOKEN_SECRET.

You can instead place token_id and token_secret in a private configuration file, but both must be present. Do not commit tokens.

Validate the Configuration with run

This example uses SWE-bench Verified with mini-swe-agent. It selects one task through sample_ids, and the matched recipe selects its Modal-compatible image and workspace:

agentcompass run swebench_verified mini_swe_agent "$MODEL_NAME" \
  --env modal \
  --benchmark-params '{"sample_ids":["astropy__astropy-12907"]}'

The command above is a minimal agentcompass run check. See agentcompass run for model endpoint and other shared options.

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

Parameter Reference

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

The example above continues to use credentials from environment variables or the Modal SDK configuration, while the recipe supplies the task image. Add the following option to request 2 CPU cores and 6 GiB of memory for each sandbox:

--env-params '{"cpu":2,"memory":"6g"}'

Connection and Credentials

Field	Default	Meaning
token_id	MODAL_TOKEN_ID	Modal token ID; it must be provided with token_secret. If neither is explicit, the Modal SDK can also read its local configuration.
token_secret	MODAL_TOKEN_SECRET	Modal token secret; it must be provided with token_id. If neither field is explicit, the Modal SDK can read its local configuration.

Image and Startup

Field	Default	Meaning
image	Unset	Registry image reference that can be pulled without credentials, such as python:3.13-slim. Mutually exclusive with named_image. The current adapter does not expose a Modal Secret parameter for private-registry credentials; publish such an image as a Modal named image and use named_image instead.
named_image	Unset	Published Modal image in {name}:{tag} form; omitting the tag selects latest. Mutually exclusive with image.
add_python	Unset	Python version string, such as 3.11, passed when loading a registry image. It applies only to image, not named_image; omit it when the image already contains a compatible Python installation.

If no recipe, image, or named_image supplies an image, the Modal provider falls back to python:3.13-slim. This basic image may not contain the dependencies or directory layout required by a benchmark.

Identity and Metadata

Field	Default	Meaning
app_name	agentcompass-sandboxes	Modal App that groups task sandboxes. It is created when missing.
environment_name	Unset	Modal Environment in which AgentCompass looks up or creates the App, looks up the named image, and creates the sandbox. When unset, Modal uses the Environment selected by the SDK configuration or calling context; new workspaces default to main.
name	Unset	Optional sandbox name. When set, it must be unique within the App, contain only letters, digits, hyphens, periods, and underscores, and be fewer than 64 characters long. An unnamed sandbox still has a Modal-generated object ID.
tags	{}	String key-value tags for ownership or evaluation-batch metadata.

Workspace and Environment Variables

Field	Default	Meaning
workdir	Image default	Working directory for sandbox commands. It must be an absolute path.
default_workspace_root	/workspace/	Non-empty absolute path used by the Harness when the Benchmark does not specify a task working directory. AgentCompass creates this directory after the sandbox starts.
env_variables	{}	Environment-variable mapping injected when the sandbox is created and commands are executed, for example {"LANG":"C.UTF-8"}. Keys must match [A-Za-z_][A-Za-z0-9_]*; values are converted to strings.

Resources

Field	Default	Meaning
cpu	0.125 (Modal platform default)	Positive request in physical CPU cores, or a two-item [request, limit] list of positive values. The second value is a hard limit and cannot be smaller than the request. When unset, Modal uses its current platform default.
memory	128 MiB (Modal platform default)	Positive memory request in MiB, a size string such as 6g, or a two-item [request, limit] list of positive values. The second value is a hard limit and cannot be smaller than the request; AgentCompass converts sizes to MiB. When unset, Modal uses its current platform default.
gpu	Unset	Modal GPU specification, such as H100 or H100:2 for two GPUs. Available models and counts depend on current Modal capacity.
cloud	Unset (unrestricted)	Restricts the sandbox to one cloud provider supported by Modal, such as aws, gcp, oci, or auto. Availability depends on workspace access, region, and current capacity.
region	Unset (unrestricted)	One region or a list, such as us, us-west, or ["us-central","us-west"]. Narrower placement usually reduces the available capacity pool.
resources	{}	Optional nested resource object. A child field is read only when its matching top-level field is unset.
resources.cpu	Unset	Uses the same format as top-level cpu. Alias: resources.cpus.
resources.memory	Unset	Uses the same format as top-level memory. It also accepts resources.memory_mb and resources.memory_gb, where the latter is interpreted as GiB and accepts only a single number.
resources.gpu	Unset	Uses the same format as top-level gpu. Alias: resources.gpus.

Choose either top-level fields or resources child fields for a given resource rather than defining both. The two-item request-and-limit form for CPU works in either location. For memory, use top-level memory, resources.memory, or resources.memory_mb; do not use resources.memory_gb for a pair.

Network

Field	Default	Meaning
block_network	false	Blocks all outbound traffic when set to true. In that case, it cannot be combined with any of the three allowlist fields below.
outbound_cidr_allowlist	[]	CIDR ranges that the sandbox may reach using any protocol, for example ["203.0.113.0/24"]. Other outbound IP ranges are blocked unless a domain rule also permits the traffic.
outbound_domain_allowlist	[]	Domain names that the sandbox may reach over TLS on port 443, for example ["api.example.com","*.example.org"]. A wildcard also matches the parent domain; CIDR and domain rules combine additively.
inbound_cidr_allowlist	[]	Source CIDR ranges allowed to connect through Modal tunnels and Sandbox Connect Tokens, for example ["198.51.100.0/24"].

When all three phases use the same policy, set a shared network policy directly. For phase transitions, keep the base network_policy set to public, keep block_network=false, and create the sandbox with both outbound_domain_allowlist: ["*"] and outbound_cidr_allowlist: ["0.0.0.0/0"] before configuring the later phase policies. The current adapter sends both allowlist types on every dynamic update but does not infer their initial values from later phases. Modal may reject an update if either type was absent at creation. See Modal sandbox networking for the upstream restrictions.

Lifecycle and Timeouts

Field	Default	Meaning
timeout	43200	Maximum lifetime of one Modal sandbox, in seconds. It must be an integer from 1 through 86400. Verification counts toward the same lifetime when it reuses that sandbox; a separate verifier sandbox has its own timer.
idle_timeout	Unset	Non-negative number of seconds Modal waits before terminating a sandbox with no active command, stdin writes, or open tunnel connection.
sandbox_start_timeout	300	Positive number of seconds AgentCompass waits for sandbox creation.
operation_timeout	1800	Positive default timeout, in seconds, for one sandbox command when the Harness or caller does not provide a timeout for that execution.

See Run Controls for concurrency and retained environments, and Resource Limits for sizing guidance.

Parameter Sources

• Run agentcompass config docs env modal to see the fields, types, and defaults supported by your installed AgentCompass version.
• See Modal’s Sandbox API reference and the official guides for resources, GPUs, region selection, sandbox networking, registry images, named images, and Modal Environments.

Use the agentcompass config docs env modal output for accepted fields, types, and defaults. Use Modal’s documentation for provider-native values and platform behavior.

Provider-Specific Behavior

• Set only one of image and named_image: the first loads from a registry; the second is looked up in the selected Modal Environment.
• Normal environment close terminates and detaches the sandbox. With --keep-environment, AgentCompass skips close.
• Phase network transitions require both an SDK that supports dynamic updates and both outbound allowlist types to be initialized as described above. A sandbox created with block_network=true cannot switch policies dynamically.

Troubleshooting

Symptom	What to check
Only one token field is provided	Set both token_id and token_secret, or remove both and use Modal’s local configuration.
A named image cannot be found	Check named_image, environment_name, and the workspace associated with the token.
The fallback image lacks commands or files	Use a compatible recipe, or set an image / named_image that contains the task dependencies.
workdir is rejected	Use an absolute path inside the sandbox.
Sandbox creation times out	Check the image and account quota first, then increase sandbox_start_timeout based on observed creation time.

Related Pages

• Environments Overview
• Configure an Environment
• Network Policy
• CLI Configuration Files