ECS Fargate

The ecs_fargate provider runs each sandbox as an AWS ECS Fargate task reached over an SSH sidecar. It implements the provider-neutral SandboxProvider contract, so any sandbox-backed agent or resources server can use it by selecting ecs_fargate in its sandbox config.

Setup

ECS Fargate needs the AWS SDK and a provisioned account/region:

$
uv pip install boto3

• Infrastructure. The reference Terraform stack publishes its outputs to SSM at /<ssm_project>/ecs-sandbox/config (ssm_project defaults to harbor): cluster, subnets, security groups, task/execution roles, ECR mirror, EFS, and the SSH-sidecar key ARNs. A missing parameter raises an actionable error.
• Credentials. AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY (or an instance role) plus AWS_REGION.
• Network. The host must reach each task’s SSH sidecar port (52222). Run inside the sandbox VPC/peered network, or allow the host IP on the sidecar security group. Exec, file transfer, and model reverse-tunnels all ride this SSH connection.

Provider Configuration

NeMo Gym ships this provider config at nemo_gym/sandbox/providers/ecs_fargate/configs/ecs_fargate.yaml. It defines a top-level sandbox block that an agent selects with sandbox_provider: sandbox. Region-only is enough; everything else auto-discovers from SSM (explicit YAML always wins), and task cpu/memory/disk come from the agent’s sandbox_spec.resources:

1
sandbox:
2
  default_metadata:
3
    sandbox-api: ecs-fargate
4
  ecs_fargate:
5
    region: ${oc.env:AWS_REGION}

Cluster, subnets, security groups, roles, ECR mirror, EFS defaults, and the SSH-sidecar key ARNs are filled in from SSM when omitted.

Provider Options

Per-sandbox options go in SandboxSpec.provider_options:

Common SandboxSpec fields map onto the task as follows: ttl_s → sidecar watchdog that stops the task, ready_timeout_s → task-startup timeout, env / files / workdir → container environment, seed files, and working directory.

Resource Mapping and Isolation

SandboxResources maps onto the Fargate task definition:

Each sandbox is a dedicated Fargate task with its own kernel, network namespace, and microVM boundary — there is no host sharing between sandboxes. The orchestrator holds a per-task SSH connection for exec and file transfer, and TTL is enforced by a sidecar watchdog that stops the task.

Images and On-Demand Mirroring

ECS pulls task images from the account ECR mirror rather than their origin registry. A bare/public image (e.g. docker.io/swebench/sweb.eval.x86_64.<id>:latest) resolves to the mirror tag <ecr_repository>:<sanitized-name>. Resolution order:

1. environment_dir set → build the image via CodeBuild and use it.
2. Image is already an ECR reference → use verbatim (never re-mirrored).
3. Bare/public name + auto_mirror=true → mirror into ECR on demand (CodeBuild pull → retag → push) during create, then launch.

The first task for a new image waits on a one-time build (~1–3 min for typical SWE-bench images); later tasks hit the ECR cache, and concurrent tasks for the same image de-duplicate onto a single build. Set auto_mirror: false to require a pre-populated mirror and fail fast on a miss.

First-Run Example

Drive a sandbox directly through the provider-neutral API:

1
import asyncio
2
3
from nemo_gym.sandbox import AsyncSandbox, SandboxResources, SandboxSpec
4
5
6
provider_config = {"ecs_fargate": {"region": "us-east-1"}}
7
spec = SandboxSpec(
8
    image="python:3.12-slim",
9
    ttl_s=1800,
10
    ready_timeout_s=300,
11
    resources=SandboxResources(cpu=2, memory_mib=8192),
12
)
13
14
15
async def main() -> None:
16
    async with AsyncSandbox(provider_config, spec) as sandbox:
17
        await sandbox.start()
18
        result = await sandbox.exec("python3 --version", timeout_s=60)
19
        print(result.stdout or result.stderr)
20
21
22
asyncio.run(main())

For an end-to-end agent run, add this provider config to mini_swe_agent_2’s config paths — the agent config is unchanged:

$
ng_run "+config_paths=[responses_api_agents/mini_swe_agent_2/configs/mini_swe_agent_2.yaml, nemo_gym/sandbox/providers/ecs_fargate/configs/ecs_fargate.yaml, <MODEL_CONFIG>]"

Troubleshooting