Sandbox Management

The lifecycle of a ROCK sandbox — from a per-instance SWE-Bench Docker image to a live pexpect bash session and back — as driven by the in-house SWE agent.

Beneath the Environment Engine overview, this page traces one ROCK sandbox end to end — created, executed against, torn down — and the knobs and failure modes that matter. Its consumer is the in-house SWE agent (rl_engine/examples/swe_agent/); three parts do the work:

Every action crosses two HTTP hops: agent → admin on :8080, then the admin's Ray actor → the container's rocklet on :8000. Which node a sandbox lands on is decided upstream by the Task Scheduler's PlacementPool, not by ROCK (see §8).

1 The moving parts

A sandbox is one Docker/Podman container plus the machinery that manages it — four processes across the two planes:

In --env local mode there is no Redis, so the expiry reaper is disabled and each container self-terminates on its own auto-clear timer instead. (Endpoints and admin flags are in §10.)

2 Lifecycle state machine

A sandbox moves through a fixed set of phases. Only start is expensive, dominated by the image step — a multi-minute first pull, then a ~10–25 s warm start. The timing chips below show every other phase is sub-second.

Phase notes

3 SandboxConfig & the start call

SandboxConfig (rock/sdk/sandbox/config.py) is small and deliberately CPU-oriented: no GPU, volume, or network-mode fields. Bind mounts go through the raw docker_args escape hatch on the admin-side DockerDeploymentConfig instead.

SandboxGroupConfig adds size (2), start_concurrency (2), and start_retry_times (3) for starting a fleet with bounded concurrency and per-sandbox retry.

A worked example (the ROCK smoke test)

The getting-started health check exercises the full SDK path — start, session, command, stop:

import asyncio, time
from rock.actions import CreateBashSessionRequest
from rock.sdk.sandbox.client import Sandbox
from rock.sdk.sandbox.config import SandboxConfig

async def main():
    cfg = SandboxConfig(
        image="swebench/sweb.eval.x86_64.django_1776_django-10097:latest",
        memory="4g", cpus=1.0,
    )
    sb = Sandbox(cfg)
    await sb.start()                                  # POST /start_async, then poll is_alive
    await sb.create_session(CreateBashSessionRequest(session="bash-1"))
    r = await sb.arun(cmd="cat /etc/os-release | head -3", session="bash-1")
    print(r.output)                                # BashObservation.output
    await sb.stop()

asyncio.run(main())

start() calls /start_async, then blocks polling get_status().is_alive. The SWE agent instead calls the synchronous /start (via RockSandbox.start) with its own retries; both reach the same SandboxManager.

4 Sessions & the action model

Two execution modes. A session is a long-lived /bin/bash REPL whose state (cwd, exported vars, jobs) survives across calls — what agents use; execute is a stateless one-shot subprocess.run. One sandbox can hold many named sessions at once (LocalSandboxRuntime._sessions).

Request & response types

Wire schema (rock/actions/sandbox/{request,response}.py):

Three call styles sit over these types: run_in_session (blocking, one command), arun (adds a nohup background mode — submit, poll kill -0 <pid>, return output), and execute (stateless). Output is fully buffered into one response (no streaming channel); the per-command timeout bounds its runtime.

Inside the container: how a command really runs

BashSession (rock/rocklet/local_sandbox.py) is a pexpect wrapper around /bin/bash. A few correctness tricks explain its quirks:

• Prompt & exit codes. A unique PS1 marker (SHELLPS1PREFIX) and an inline echo EXITCODESTART$?EXITCODEEND let pexpect detect completion and read the status — so the SWE client strips that marker and (testbed) noise from output. A bash -n check runs first, so malformed commands fail fast.
• Heredocs & pagers. Heredocs desync prompt detection, so cat <<EOF is auto-rewritten to a base64 -d pipe; GIT_PAGER/PAGER are pinned to cat so no pager stalls a turn. For multi-line content, prefer write_file or the editor tool.

5 How the SWE agent drives a sandbox

The agent handler (rl_engine/examples/swe_agent/agents/swe_agent.py and its DAgger subclass) drives one trajectory end to end:

1. Placement. node_ip = context.placement["node_ip"], chosen by the Task Scheduler; the handler addresses http://{node_ip}:8080.
2. Start. RockSandbox.start(image, cpus=4, memory="16g", docker_args=[…]), image from get_swe_bench_image(instance_id), up to 10 retries.
3. Repo setup. The SWE-Bench repo is already at /testbed, so setup_repo_in_sandbox just git checkouts the base commit; init_session activates the conda testbed env and cds in.
4. Turns. Each action becomes an execute_swe_tool call: execute_bash → run_in_session; str_replace_editor → the in-container entrypoint.
5. Teardown. The handler stops the sandbox and, unless STACX_KEEP_IMAGES=1, removes the per-instance image (§6).

The editor tool & the bind-mounted entrypoint

Bash runs through run_in_session, but structured edits (view / create / str_replace / insert) go to a small in-container script (rl_engine/examples/swe_agent/environment/execute_sandbox.py), bind-mounted read-only from SWE_ENTRYPOINT_LOCAL to /home/swe_execute_sandbox.py. It targets Python 3.5+ (no f-strings), since some SWE-Bench images ship an old interpreter.

6 Image management

Each SWE-Bench instance has its own pre-built image (2–8 GB), named from the instance id (swe_sandbox.py:get_swe_bench_image):

# django__django-16911  ->  swebench/sweb.eval.x86_64.django_1776_django-16911:latest
image = f"{namespace}/sweb.eval.x86_64.{instance_id.lower().replace('__','_1776_')}:latest"

A run touches hundreds of unique instances, so image handling dominates first-run cost and disk. Three mechanisms manage it:

Warmup (rock/sandbox/service/warmup_service.py) pre-pulls a configured image list onto every alive Ray worker node at admin start (one WarmupActor per node); it does not keep a pool of running containers. The SWE recipes configure no warmup images, so this path is dormant — cold starts are amortized by the Docker cache and the optional tar cache instead.

7 GEM environments

GemManager (rock/sandbox/gem_manager.py) — the SandboxManager subclass the admin actually instantiates — adds env_make / env_step / env_reset / env_close to host a Gymnasium-style environment inside a sandbox (via gem.make(env_id) in LocalSandboxRuntime), one container per env.

8 Resource accounting: scheduler vs. runtime

Two layers account for resources:

The DAgger evaluator budgets a node at cpu=96, memory_gb=320, gpu=0 and gives each sandbox 4 CPU / 16 GB — ~20 concurrent containers per node (evaluator_config_dagger.py). Per-actor start concurrency is capped by STACX_DAGGER_ENV_CONCURRENCY (default 4, lowered from 12) to stay under the daemon's start throughput.

9 Failure modes & ops

When infrastructure fails a turn — generation aborted, or the sandbox unreachable — the trajectory ends with _termination_reason = "aborted", distinct from a clean finish and from budget/loop/context-overflow exits. The finish-only filter (STACX_FINISH_ONLY_FILTER) then drops everything that is not finish, so it never reaches the trainer.

10 Knob & endpoint reference

Sandbox REST API (prefix /apis/envs/sandbox/v1, rock/admin/entrypoints/sandbox_api.py)

The GEM env API lives separately under /apis/v1/envs/gem/{make,step,reset,close,list}.

Environment variables that touch sandboxes

Admin launch flags (rock/admin/main.py)

See also Environment Engine (surrounding architecture), Task Scheduler (how sandboxes are scheduled onto nodes), and Rollout Architecture (the consuming agent loop).