Skip to content

feat(env-providers): give each gateway stack its own layout on a VM - #775

Merged
mandykwok-scale merged 3 commits into
mainfrom
mandy/shared-sandbox-slot-paths
Nov 19, 2026
Merged

mandykwok-scale merged 3 commits into
mainfrom
mandy/shared-sandbox-slot-paths

Conversation

@mandykwok-scale

@mandykwok-scale mandykwok-scale commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

What and why

We want to run several tasks in one Modal sandbox to cut cost ("sandbox stuffing"). Today every gateway stack assumes it owns the whole VM: it uses /app, the default compose project, fixed host ports and shared /tmp names. So a second stack on the same VM would clash with the first.

This adds StackLayout, one value that holds a stack's folder, compose project, host-port offset and scratch-file prefix. Every place that hard-coded these now reads them from the layout: the gateway provider, snapshots, MultiEnv, website and MCP server envs. StackLayout.for_slot(n) gives slot n its own folder (/app/s<n>), project (s<n>), ports (+(n+1)*1000) and scratch prefix. The default layout keeps today's values. A slot layout is refused unless it goes into an existing sandbox whose walls between slots are verified, and no sandbox reports that yet, so no slot can be deployed until that work lands. DOCKER_COMPOSE_PATH is removed, and its users go through the layout.

The deploy record keeps a slot's layout, and a reattach takes it back, so a reload never sends a slot's commands to the default stack; a damaged recorded layout raises.

Not in this PR: tearing down a single slot (today every close ends the VM, so it needs one central refusal, built with the walls work), and exposing every slot's ports when the VM is created.

How it was tested

  • New unit tests for the layout and for stack_layout_of. The full unit suite passes except tests that also fail on a clean main (4,731 provider and env tests pass on the final commit).
  • A probe that records every command and path the default layout produces gives byte-identical output on main and on this branch. Snapshot reload, artifact copy and child gateways were not covered by the probe, and the Docker integration tests were not run.

🤖 Generated with Claude Code

RetriggerView in GreptileConfidence Score: 5/5

The reviewed changes appear safe to merge; no blocking issues were found.

Summary

The PR gives each gateway stack its own paths, Docker Compose project, ports, and scratch names while keeping the default layout unchanged.

  • Gateway stacks can use separate folders, compose projects, ports, and scratch names.
  • Artifact and snapshot work follows the layout of the gateway stack.
  • Deploy records keep slot layouts so reattach can return to the same stack.

No actionable new issues found in the changes since the previous review. Tests were not run during this review.

Reviews (6) · Last reviewed commit: "feat(env-providers): keep a slot's stack..." · Reviewed by Greptile

Sandbox stuffing will run several agent-env stacks ("slots") in one Modal
VM. Today one stack per VM is assumed throughout: one /app compose dir,
compose's implicit project, fixed host ports, fixed /tmp scratch paths,
and a gateway-running check that matches any container named gateway.

StackLayout (providers/env_providers/stack_layout.py) holds where one
stack lives: its app dir, compose project, host port offset and scratch
prefix. Every one of those call sites now asks the layout. The default
layout reproduces today's commands byte for byte, and nothing passes
another layout yet, so behavior is unchanged.

StackLayout.for_slot(index) gives slot `index` the project s<index>,
/app/s<index>, host ports shifted by (index + 1) * 1000 (container ports
unchanged), its own scratch names and its own snapshot image tag. A slot
checks its gateway with a project-scoped `compose ps`, and a slot port
without a tunnel raises instead of returning no URL. A slot's project
can never equal the default stack's implicit `app`. App dir and scratch
prefix are checked against a shell-safe charset, since they reach shell
scripts unquoted.

Persisting the layout for reattach, slot teardown, sidecar port checks
and exposing every slot's ports at VM create are left for the next PR.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@mandykwok-scale
mandykwok-scale requested a review from a team as a code owner November 18, 2026 17:05
…are verified

A slot stack may only go into an existing sandbox whose `walls_verified`
is true. That is a read-only property on Sandbox, false for every sandbox
today, so no slot can be deployed until the framework sets up and checks
the walls between slots. The check runs before the provider records the
layout, so a refused deploy leaves the provider on its previous layout.
The default layout is now also a class attribute, so a provider subclass
that skips `super().__init__` keeps working.

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

@kaihackney-scale kaihackney-scale left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The walls_verified guard is a good gate: slot deploys can't happen until the isolation work lands, so this is safe to merge as it is. Two things to settle before any sandbox reports walls_verified = True:

  1. The slot's layout lives only on the in-memory provider. _deploy_gateway sets self._stack_layout, but nothing writes it to the deployed record. A step that reloads the env from its record (snapshot, reset, trajectory read, teardown in another process) goes back to DEFAULT_STACK_LAYOUT, and on a VM that holds only slot stacks it would run docker compose -f /app/docker-compose.yml. Could the layout (or just the slot index, since for_slot rebuilds the rest) go on the record, so stack_layout_of works after a reload?
  2. Close and teardown for a slot. Nothing here changes how an env is closed or torn down. For a slot it should be compose -p s<n> down plus removing its app dir and scratch files, never ending the shared VM. I couldn't tell from the code whether the current VM teardown path would end the whole box when one slot's env closes. Worth a test either way.

Minor: slots share one docker daemon and the host network, so the walls work needs to cover container-to-container traffic between compose projects as well as host ports.

A reload rebuilt the provider with the default layout, so a slot's later
commands would have gone to /app/docker-compose.yml on a VM other runs share.
The record now keeps the slot's layout and a reattach takes it back; a damaged
recorded layout raises instead of falling back to the default stack.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@mandykwok-scale

Copy link
Copy Markdown
Contributor Author

Thanks Kai!

  1. Done (e5464a5). The deploy record keeps a slot’s layout and every reattach takes it back, so close, reset, snapshot and trajectory reads hit the slot’s own stack. A damaged layout raises instead of falling back to the default.
  2. Checked. Today every close path ends the VM: each env’s close(), close_deployed and task teardown. A guard on one path would be false safety, so the fix is one central check with the walls work: a shared VM refuses terminate() unless the box terminator calls it, plus a test that closing one slot leaves the VM and other slots running. No slot can be deployed until then.
  3. Agreed, added to the walls work: block container-to-container traffic between compose projects, not just host ports.

@kaihackney-scale kaihackney-scale left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Re-reviewed e5464a5. The deploy record now keeps the slot layout, every reattach restores it, and a damaged record raises before any sandbox is touched, which closes my first point. The other two (one central check that stops a slot close from ending the shared VM, and blocking container-to-container traffic between compose projects) belong with the walls work, and the walls_verified guard means no slot can be deployed before that lands. LGTM.

@mandykwok-scale
mandykwok-scale merged commit 96e2871 into main Nov 19, 2026
35 of 36 checks passed
@mandykwok-scale
mandykwok-scale deleted the mandy/shared-sandbox-slot-paths branch November 19, 2026 22:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants