[earakely-scale]

M0.7 of the CUA env epic (FD-4345): computer envs deploy on local Docker, FD-4358, with M0.8 (deploy_env env_params, FD-4349), M0.5 (the computer skill, FD-4355) and M0.11 (Env.close at teardown, FD-4464) folded in. It follows the reviewed design, CUA Env M0.7: Deploying a Computer Env on Local Docker, with its 15 choices confirmed and the changes below decided in review. It builds on #358 (M0.6), now merged, and is rebased onto main.

What's in it

• The ubuntu-24.04 base's user has a desktop's standard folders (Documents, Downloads, ... from xdg-user-dirs), so the driver's default data paths exist and a task can name them.
• Providers say what they run natively, and containers can have no network.
  • native_platforms(): linux/amd64 by default, the host's for local Docker. A computer boots only on a provider that runs its arch natively; create_container takes no platform (decided in review), since that choice is made before it's called.
  • NetworkPolicy.closed is an allowlist of nothing. Local Docker enforces it for a container: it runs on an internal network of its own, with a relay container (providers/sandbox_providers/local_docker/relay/, built here from its sources) publishing its port to the computer's address there. A VM given a restricting policy is refused.
  • The local Docker provider moves into providers/sandbox_providers/local_docker/ with its relay (local_sandbox.py is local_docker/provider.py; decided in review); the package still exports LocalSandbox and LocalSandboxProvider, and the plugin-API check reports no break.
  • reset_container(sandbox, ...) resets a sandbox's container to a fresh one of the image, on the same sandbox and port; local Docker replaces the relay too. A computer env's reset uses it, since a computer's state is its whole filesystem and running session, with no seed to reload in place as an MCP server does.
• The computer env provider (providers/env_providers/env_computer_provider.py) deploys a computer env with no gateway in front:
  • it boots the first ready build, in the base's order of forms and arches (or env_params.form's), on a sandbox provider that runs its arch natively;
  • the driver's card is the env card, served under the env's environment_name;
  • it checks the driver reports the env's display;
  • the record's metadata.computer keeps the form, arch, provider, image, computer, display, network, computer_settings (a secret's or a generated one's withheld) and env_params.
• Gate 3 (composer.py): after a build, the composer boots it at the env's settings and display, as a deploy does, on a configured provider that runs its arch natively, and probes it at full. The build becomes ready with the driver's card, or failed at the probe with the report stored as a FileArtifact. A build no configured provider runs natively stays unverified, saying why, and env build probes it once one does. A probe's sandbox, and a boot that fails (a closed-network one whose setup fails, or one that fails its name or display check, too), go with their local work folders.
• deploy_env env_params (M0.8), one table per layer: a computer env takes form, computer_settings (deploy-phase values of the base's settings, checked as the env's are; a secret one, here or on the env, only as a bare secret:/env: reference, since the env, the task and the deploy record keep what's given) and driver_settings (the driver's ComputerSettings, such as its default coordinate space, passed in AGENTENV_COMPUTER_SETTINGS). Preflight now asks every env type's deploy_refusal, so another type, or an option a type's deploy doesn't name, is refused before anything deploys.
• Reset returns the computer to boot state: the driver ends its recordings, then a fresh container of the same image boots in the old one's place, readied as a deploy readies it. A sandbox provider that can't replace a container (Modal today) fails the reset step, naming itself, rather than skipping it. The computer keeps its address, so the agent's registered MCP URL stays valid, but an agent's MCP session ends with the old driver: the fresh one answers it with 404, after which an MCP client starts a new session (decided in review; Claude Code opens a new one every turn). Redeploying into a new sandbox instead was ruled out: a run's stored context can add a deployed env but not replace one, so the new address wouldn't be saved.
• Env.close at teardown (M0.11): teardown_run and the teardown_sandboxes step share one core (task.teardown.tear_down). First the recordings the run left open end, each through its driver with a fresh grant, whatever env serves it; then each env still up closes under the per-sandbox timeout (a plugin's own env class through its own close); a recording still open after that is registered from its namespace; then every sandbox is terminated by id as before and a local one's folder removed (the step now does both too). Env.close and Env.reset keep their signatures, so out-of-tree overrides are unaffected.
• A computer env ends its own recordings. computer-recording/v1 gains end_all, which ends every recording not yet ended under the grant each started with, and every end uploads the manifest beside the segments (<recording_id>/manifest.json). A computer env's close and reset call it before the computer goes, so a recording open at a reset, or at a close outside a run's teardown, is saved too. Teardown, and end_computer_recording when the driver no longer knows a recording (as after a reset), register it from what its namespace holds, reading that manifest.
• Env skills, and the computer's (M0.5): any env built on the protocol SDK can serve agents a skill. skill/v1 (SKILL_EXTENSION_URI) answers get {name} with {name, description, skill_md}, written under the name the caller gives, and an env serves it by marking the method that writes it with @agent_skill (description and body). The computer driver's base class serves one written from the computer as it booted, ending with the driver class's new notes; computer/v1 now only declares the seven tools and the driver's features, and the conformance probe checks the skill. add_skills takes env_ids: for each env the run deployed and bound to the agent, it installs the env's skill under its environment name (the agent's MCP alias for it, with a digest of the env id when the name had to be normalized or shortened), or, for an env whose own card serves none, as an MCP server behind its gateway, each child env's under that child's name, and records each SKILL.md in the run's context (env_skills, by skill name).
• data/get takes paths (decided in feat(computer): the computer env type and the composer (container forms) #358's review): a computer returns the files under the paths it's given, or under the default_data_paths its card declares (Desktop, Documents, Downloads). A get hook that doesn't take paths refuses them; one that does gets None when the call names none. ComputerSettings.data_paths is gone.
• A recording on a computer with no network is refused at start, since its segments couldn't reach the store.
• The desktop example (src/agent_env/examples/desktop/, the eighth shipped bundle): a computer env of ubuntu-24.04 and reference, a probe task (deploy, probe at full) and an agent task (Claude Code, given the computer skill, makes a folder through the file manager under a recording; the check reads it back through the driver).
• The M0.3 scaffold is gone. Its probe and agent tasks are the example's; its scripted drive under a recording runs on the example env (tst/integration/computer/recording/); the recording chaos tests run on the example's composed image, with the conformance fixture started through computer-exec as the probe starts it.

Where this differs from the design

1. A computer env ends its own recordings at close and reset (decided in review), through the driver's new end_all, instead of Env.close(context) and Env.reset(deployed, context) ending them from the run's context, which would have broken out-of-tree overrides of both. Teardown still ends the run's open recordings first, each with a fresh grant (decided in review of Greptile's finding that a recording served by another env type would lose its last segment). What remains: an end at reset uses the grant the recording started with, so on a store whose grants expire before a long recording is reset, the segments recorded after expiry are lost.
2. Teardown terminates an env's sandboxes by id even after its close, instead of marking them torn down. A built-in close logs a failed terminate rather than raising, so trusting it could leak a sandbox; terminate_sandbox is idempotent, so the second terminate costs one lookup.
3. A close that fails or times out is logged, and its sandboxes go into the report by what their terminate by id did, so failed keeps meaning "may still be running".
4. env_params takes computer_settings and driver_settings (decided in review), one table per layer, instead of settings by layer and spaces.
5. A deploy hides no tools (decided in feat(computer): the computer env type and the composer (container forms) #358's review): a task that wants fewer tools uses modify_env_tool_access, which works through the driver's disable-tool/v1.
6. The skill is any env's, not the computer's (decided in review): skill/v1 and @agent_skill replace a skill method on computer/v1, and add_skills takes env_ids instead of computer_env_ids, so other env types can hand agents a skill the same way. get takes the name to write into the SKILL.md's frontmatter, so add_skills names it per env.
7. A DeployedAgent records the env_ids its deploy_agent registered, since nothing in a run's context said which envs an agent is bound to.
8. data/get paths and the driver's default replace data_paths (decided in feat(computer): the computer env type and the composer (container forms) #358's review; snapshot_env gains computer_file_paths in M1.8, FD-4382).
9. The recording refusal on a computer with no network is new: local Docker's closed network relays only inbound, so a recording there could never upload.
10. create_container takes no platform (decided in review). The design passed it so a provider would refuse a platform it would emulate, but both callers, the deploy and gate 3, choose a provider by native_platforms() first, so that check could never fire, and the new parameter broke out-of-tree overrides of create_container (the plugin-API check).

Review

Greptile's review of 9e775d5 raised seven threads. Six are fixed in 7655132, as the bullets above now say: teardown ends the run's open recordings first; gate 3 probes at the env's settings; a reset a provider can't carry out fails; skill names that come out alike get an env-id digest; a get hook that takes paths gets None; a failed closed-network boot removes its folder. The seventh, a secret setting given as its value reaching the deploy record, is fixed in 77cbffb (decided in review): a secret setting takes only a bare secret:KEY or env:NAME reference. The plugin-API check's break, create_container's new platform, is gone (difference 10); the check now reports no break. #358's fix for a driver file named outside the build folder (98e139a) applies here too. Greptile's review of 3abc1fa raised four more, fixed in 83e9837: skills of child envs behind a gateway, a plugin env class's own close at teardown, a boot that fails its checks leaving its folder, and a secret setting with a non-string default refusing its reference.

Testing

• Unit. Rebased onto main, and again with the secrets change, 11,341 passed; the one failure, the known test_deep_nesting timing flake, passes alone. On the review round before the rebase, 11,288 of 11,292 passed. Three failures were in the round's own new tests, which were fixed and rerun with their files (1,983 passed); the fourth is the known test_deep_nesting timing flake, which passes alone.
• After the review rounds, at 837d495 (laptop arm64): tst/integration/computer 19 passed and 1 skipped (the agent task, which needs a model endpoint), including reset with and without network, recordings open at a reset and at teardown, and the base's standard folders. The agent run passed in 25.3 s: Claude Code, given the computer's skill as desktop through skill/v1, made /home/user/Documents/Reports through Thunar in 8 tool calls; the recording ended with 2 segments and none missing, and nothing was left. At 83e9837 the same run scored 0 because the base had no Documents folder and the agent asked rather than create one (the run before the review created it unasked), which 837d495 fixes in the base. The bullets below are from before the review rounds.
• Integration (tst/integration/computer, laptop arm64, real Docker and the local registry), before the review round: 18 passed and 1 skipped (the agent task, which needs a model endpoint). The scripted-drive recording test failed that run: its pixel check compared against the recording's first frame, which can predate the Fixture Desk now that the drive starts it. Fixed to compare against the frame before the click, it passed twice on its own. CI's integration jobs run the same tier on Linux amd64.
• Chaos on the laptop (arm64), 8/8, with deploy_chaos.py (scenarios from the design's chaos row; each also checks that no container, relay, network or work folder is left):
  • the driver killed mid-deploy: supervisord restarts it and the deploy goes on;
  • the computer killed mid-deploy: the deploy fails, naming the last thing it saw, and nothing is left. It waits out the 180 s ready timeout first, since readiness doesn't watch the container;
  • the computer killed mid-task: the call fails, and teardown still reports the sandbox terminated;
  • the probe's computer killed during gate 3: the pair fails at the probe, and env build resumes it to ready. This found a hang: the probe had no deadline, and on Docker Desktop a dead computer's connection stays open, so the put waited indefinitely. The probe now has 120 s;
  • a boot past its timeout: the deploy fails naming what it last saw;
  • a close with an open recording whose driver is gone: teardown goes on and registers the segment already uploaded;
  • two computer envs at once: separate sandboxes and ports, both pass the basic probe, deployed in 2.0 s;
  • teardown cancelled part-way: it returns what it reached, and a second teardown finishes the rest.
• Chaos on EC2 (amd64, c6i.2xlarge), at 4ba6146: the same 8/8, and gate 3 again with Docker itself restarted mid-probe: the pair fails at the probe, and env build resumes it to ready once Docker is back. There the probe's computer dying fails fast, since the port closes with the container. The box had no arm64 emulation, so the arm64 pair fails at build, as gate 1 promises.
• The agent run (agent-env run desktop --task agent, laptop only, the model key held in-process): passed in 52.7 s. Claude Code, given the computer's skill (then named computer-desktop; it is desktop since the review), made the folder through the file manager in 36.4 s, the check confirmed it through the driver, and the recording ended with 4 segments and none missing. Nothing was left.

🤖 Generated with Claude Code

Confidence Score: 5/5

The PR appears safe to merge; the latest change fixes the remaining cleanup finding.

Summary

Computer envs can now deploy on local Docker, reset in place, serve agent skills, and save recordings before teardown.

• Computer environments build, pass a probe, and deploy on a native sandbox.
• Local Docker runs computer containers on closed networks and reports native architectures.
• Computer recordings save their manifests and can end before reset or close.
• Run teardown closes deployed environments before it terminates their sandboxes.
• Agents can receive named skills from computer and other environments.
• Computer data reads can return requested folders or the desktop defaults.
• Supporting documentation and example scaffolding move with the new computer workflows.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A[Compose image] --> B[Boot and probe]
  B --> C[Ready build]
  C --> D[Deploy computer]
  D --> E[Agent uses tools and skills]
  E --> F[Reset or close]
  F --> G[End recordings]
  G --> H[Replace container or terminate sandbox]

Loading

_{Reviews (14) · Last reviewed commit: "fix(sandbox): a closed container whose m..." · Reviewed by Greptile}