Skip to content

feat(multi): computers as child envs of a multi env (FD-4935) - #539

Merged
earakely-scale merged 6 commits into
mainfrom
edgararakelyan/fd-4935-computer-child-envs
Nov 8, 2026
Merged

earakely-scale merged 6 commits into
mainfrom
edgararakelyan/fd-4935-computer-child-envs

Conversation

@earakely-scale

@earakely-scale earakely-scale commented Nov 8, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

PR 3 of the four in the FD-4930 + FD-4935 design note: a multi env holds computers. computer_envs = ["desktop"] sits beside mcp_server_envs and website_envs, any number of them. Each computer deploys on a sandbox of its own, as it would alone, with its child_envs entry (PR 1). The gateway fronts it by its name on the one /mcp, its tools served as desktop_computer_screenshot (PR 2). Routing the multi env's websites into the computer, and load_artifact, snapshot_env and reset_env through the multi env, are PR 4.

Deploy order (decision 5, as refined on Nov 8): in VM mode the VM comes up first. Its services start without the gateway while every computer deploys: created, its driver answering, its tools field applied. Then the gateway starts with each computer in INTERNAL_MCP_SERVERS and REST_PROXY_URLS, and waits for each to answer, as it does for its MCP servers. The gateway itself is unchanged. In container mode the computers start beside the server containers, and the gateway, created last, has no address to give them.

agent-env

  • MultiEnv.computer_envs, in env.toml, to_dict and to_toml, the bundle plan's checks and agent-env env multi put --computer. A computer's name must make a tool prefix (at most 15 characters) and be no other child env's, refused at save.
  • A computer's child_envs entry is checked by the computer's own deploy_refusal, on the entry's sandbox_type or else the multi env's. A computer with no entry is checked the same way.
  • env_params.site_routing and sites are refused for now, since PR 4 routes the multi env's websites. A sandbox provider whose URLs take credentials (REQUEST_HEADERS) is refused too: the gateway doesn't send them to a child env.
  • The gateway provider's deploy() takes children, a callback that starts the env's children on sandboxes of their own given the gateway's address, and returns each as an ExternalChild. A provider whose deploy() takes no children is refused for a multi env with computers.
  • Each computer's network allows the gateway's host, when its network lists the hosts allowed (reach).
  • The multi env's record holds each computer's own record in a new DeployedGatewayEnv.child_envs field, and its sandbox in sandbox_ids, under the backend that made it. So from_deployed_env reattaches it, close() closes it first, and teardown reaches it by id.
  • The computers' rules and lifecycle live in envs/_multi_computers.py. Its Computers holder keeps a deploy's computers its own, as deploy_through_provider keeps its provider and sandbox: a redeploy deploys fresh ones, its failure closes only those, and its success keeps the earlier ones for close().
  • A computer that fails to deploy fails the deploy, which closes every computer and the gateway. A gateway deploy tried again on the next chained provider closes the earlier try's computers first.

Two choices to look at

  1. When a computer's sandbox fit is checked. Saving a multi env checks only what saving a computer alone checks: its provider can deploy it (save_refusal). Whether a sandbox provider runs a computer natively is checked at the deploy_env step's preflight and at deploy, with the step's sandbox fields.
  2. No credentials to children. A computer on a sandbox provider whose URLs take request headers (the Scale sandbox) is refused rather than given to a gateway that would hold those credentials. The hub's prod default is beta_scale, so on the hub each computer's child_envs entry sets a sandbox_type whose URLs take none, which the refusal says. Sending a child its provider's headers, after a design note on holding that token in the gateway, is FD-5334.

Test plan

  • Unit:
    • test_multi_env_computers.py: the field, names, child_envs, deploy order and options, the record, a failure, a retry, close, reattach, the CLI.
    • Gateway provider tests: the compose entries, the VM path's order, both paths' failures, the container wiring.
    • reach in test_computer_env.py, and the bundle plan's checks in computer_env_folder_test.py.
    • The local run on macOS failed only where main fails there: provider SDKs the venv lacks, egress_hosts_test, test_disk_recipe and the sail_vm routing test.
  • Integration test, tst/integration/computer/multi_env_computers_test.py (slow tier): the desktop example's computer and the items MCP server in one multi env, deployed by a deploy_env step with a child_envs entry.
    • Through the gateway's /mcp, the server's tools and desktop_computer_* are listed, with no unprefixed computer_*. A screenshot answers by its prefixed name.
    • A role narrowed to desktop_computer_screenshot sees only it. /svc/desktop/ serves the computer's card.
    • A later process reattaches the computer from the multi env's record. The run's teardown leaves its container gone.
    • Two computers in one deployment: both served under their own names. The desktop's container killed: its screenshot fails, and items and the laptop keep answering; started again, it answers. The gateway restarted: all answer. A redeploy of the same env whose gateway fails leaves the deployment as it was, and close() ends it all.
    • A computer that fails mid-deploy fails the deploy and leaves no container. A child_envs entry the multi env refuses (site routing, an unknown key, a provider whose URLs take credentials) is refused at preflight and makes no sandbox.
  • CI time: the four tests add 395 s to the slow tier. tst/integration/slow_durations.json is refreshed with .github/scripts/slow_test_durations.py from main's last green run plus that file, since the table had the tier at 107 min against 134 measured. Its slowest shard went from 16.1 min on main to 14.4 min here, on the same 12 shards; a 13th wouldn't help, since chromium_app_test.py's 12 min is the floor.
  • VM e2e and chaos on an agent-environments-admin VM (c6i.2xlarge, us-west-2). The VM, its security group and key pair are torn down.
    • The integration test, twice: passed both times. The multi env, child_envs and tool-prefix integration tests it builds on passed. The unit tier on Linux passed but for the 5 tests that fail on a VM from an archive, as before.
    • Chaos, after each step checking through the gateway that its tools list, a prefixed screenshot answers and an items call answers:
      • Deployed: 17 tools, all three answer.
      • Two computers at once (desktop, and laptop with tools = "standard"): 31 tools, both screenshots answer.
      • The computer's container killed: its screenshot fails and items keeps answering. Started again: all answer, first try.
      • The gateway restarted: all answer, second try.
      • The computer rebooted: all answer.
      • A computer whose tools can't be applied mid-deploy: the deploy fails and leaves no container.
      • The teardown left nothing.

🤖 Generated with Claude Code

RetriggerView in GreptileConfidence Score: 5/5

The PR appears safe to merge; no new actionable issues were found.

Summary

Adds computers as children of MultiEnv, each on its own sandbox and served through the shared gateway.

  • Multi environments can deploy computers on their own sandboxes.
  • The gateway serves each computer’s tools under its name.

Diagram

sequenceDiagram
    participant Multi as MultiEnv
    participant Provider as Gateway provider
    participant Computers as Child computers
    participant Gateway as Gateway
    Multi->>Provider: Deploy with children callback
    Provider->>Computers: Deploy each on its own sandbox
    Computers-->>Provider: Named MCP and base URLs
    Provider->>Gateway: Start with child routes
    Gateway-->>Multi: Ready deployment
    Multi->>Multi: Save child records and sandbox IDs
    Multi->>Computers: Close children
    Multi->>Provider: Close gateway deployment
Loading

Reviews (10) · Last reviewed commit: "ci: refresh the shard durations from mai..." · Reviewed by Greptile

A multi env holds computer_envs beside its MCP servers and websites. Each
computer deploys on a sandbox of its own, as it would alone, with its
child_envs entry; the gateway fronts it by its name on the one /mcp, its
tools served under its name and "_". In VM mode the services start without
the gateway while the computers deploy, then the gateway starts and waits
for each. The multi env's record holds each computer's own, so reattach,
close and teardown reach it; a computer that fails fails the deploy.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@earakely-scale
earakely-scale requested a review from a team as a code owner November 8, 2026 08:06
Comment thread src/agent_env/env/envs/multi_env.py Resolved
earakely-scale and others added 5 commits November 8, 2026 00:15
… is no route of the gateway's

A later deploy of a multi env deploys fresh computers, so its failure closes
only them and leaves the earlier deployment's running; its success keeps the
earlier ones for close(). A computer may not be named mcp-<server>, the
gateway's route to that MCP server.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… the fix

It says to set child_envs.<name>.sandbox_type to a sandbox type whose URLs
take no credentials, which the hub's default (beta_scale) doesn't.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…corded in a typed field

The computers' rules and lifecycle move from multi_env.py into
_multi_computers.py: a Computers holder whose begin, rollback and commit
keep a deploy's computers its own, as deploy_through_provider keeps its
provider and sandbox. Each computer's record moves from metadata["computers"]
into DeployedGatewayEnv.child_envs, a field the record round-trips. The test
fake binds its calls to ComputerEnv's signatures, and a test keeps every
compose service independent of the gateway, which a VM deploy with
children starts last.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…redeploy, a mid-deploy failure and refused entries

Two computers keep serving through the gateway while one is killed and
started again and while the gateway restarts; a redeploy whose gateway fails
leaves the earlier deployment serving, and close() ends it all. A computer
that fails mid-deploy, and a child_envs entry the multi env refuses, leave
nothing up. One deployment carries the restarts and the redeploy, to keep
the tier's time.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
… computer tests'

Regenerated with .github/scripts/slow_test_durations.py from main's last
green Local backends run (b1ee404), plus multi_env_computers_test.py's
395 s from this branch's run. The table had the slow tier at 107 min of
tests against 134 measured, which left shards from 9.5 to 17.4 min; it
now predicts 11.0 to 12.1 min on the same 12 shards, whose floor is
chromium_app_test.py's 12 min.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@earakely-scale
earakely-scale merged commit 03babcf into main Nov 8, 2026
35 checks passed
@earakely-scale
earakely-scale deleted the edgararakelyan/fd-4935-computer-child-envs branch November 8, 2026 18:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant