feat(modal): build an image that is only a build context, with from_dockerfile

[earakely-scale]

An image that is only a build context (put_context) could run only on VM sandboxes, which build it themselves (#133). Modal containers refused it, and so did any chain holding Modal, such as beta_scale,modal.

With this PR, Modal builds such an image itself, with modal.Image.from_dockerfile.

• The prepare_image hook: a new SandboxProvider.prepare_image(image), which does nothing by default. Callers invoke it before asking a provider for a sandbox or container: the agent deploy, a lone server on Modal, and Modal's gateway, which builds all its images before creating anything. Modal's version:
  • downloads the context and unpacks it into a temp dir;
  • builds it on the provider's App, with the context's own ignore file;
  • caches the image id per process, keyed by Modal token, app and source_digest, so concurrent deploys of one image share one build.
• create_container uses the built image, rebuilding on a cache miss. Everything else is pulled as before.
• Chains: a chain prepares each provider just before trying it, outside its 180 s per-provider deadline, so a slow build can't time out the create. If a build fails, the chain moves on to the next provider.
• Why not pass the artifact to create_*: a chain forwards its kwargs to every provider, and a plugin provider without **kwargs would raise a TypeError on every deploy.
• Unpacking: build_context.extract accepts only files, folders and links. It refuses hard links and devices, and skips links whose target leaves the folder, so even an older Modal that follows links can't upload anything from outside the context.
• Guards:
  • Lifted: agents on Modal (including chains holding it), Modal's gateway and its MCP servers, and a lone server on Modal.
  • Kept: the local provider, a lone server on any other provider, and an agent attached to an existing container sandbox.
  • Preflight and by_name_problem()'s wording are updated to match.
• Also fixed: a Modal create cancelled mid-way, for example at a chain's deadline, now terminates its sandbox. Before, CancelledError skipped the cleanup and the sandbox ran until its TTL.

No pre-check for Dockerfile features Modal doesn't reproduce; Modal is left to try. Two forms it refuses are written as what docker build makes of them, in a copy of the Dockerfile kept beside the context (so a COPY of the context still copies the original): a JSON-form COPY/ADD whose paths hold no whitespace becomes shell form, and an ADD of files or folders in the context, none a tar archive, becomes COPY (Modal's ADD fetches only a URL). What Modal still builds differently from a VM: a link to a file is copied as the file; links to folders, dangling links, links that leave the context, and empty folders are dropped.

Tests

• Unit tests:
  • unpacking: kept and dropped links, a hard link, a FIFO, an escaping name;
  • the ignore-file choice;
  • the chain: preparing outside the deadline, a failed prepare falling through, only providers it tries being prepared;
  • Modal: one shared build for concurrent prepares, a failed build then a rebuild, create_container rebuilding on a miss;
  • a cancelled create terminating its sandbox;
  • each lifted and kept guard, and preflight;
  • the signature test, which now binds from_dockerfile, build.aio and from_id against the installed Modal.
• Full unit tier: 6679 passed on Python 3.12.

Live (Modal dev workspace, @local ids only)

Check on Modal	Result
Context-only echo agent, first deploy (build)	31 s
Same process, second deploy	3 s, no rebuild
New process, new version of the same sources	3 s (Modal's server cache)
Slack MCP server through Modal's gateway	32 s, build included
items server as a lone server	19 s
Failing build on modal,modal_vm	Modal's build fails, the chain falls through to modal_vm, whose build fails too, each with its own message

Since review

• Chaos battery (12 cases, Modal dev workspace, @local ids, a dedicated Modal App):

  • the integration bundle (four agent Dockerfile shapes and a gateway server) passed on --sandbox modal and on beta_scale,modal;
  • a chain whose first provider fails builds and runs on Modal;
  • four deploys of one source share one build;
  • a cancel mid-build leaves nothing cached and no temp folder, and a cancel mid-create leaves no sandbox;
  • a deleted or corrupt context, and bad credentials, each give a clear error;
  • a gateway multi with one failing build is refused before any container is created;
  • a 150 MB, 3,000-file context builds in 67 s;
  • a stale id with four waiting deploys gives one rebuild, and all four run;
  • no sandbox was left behind.

  It found three things, fixed here:

  • A project's build ran in the shared App. prepare_image now takes the deploy's attribution (every caller and the chain pass it), so a provider can attribute the build as it does the sandbox. The sdk's per-project App wrapping covers it in agentenvhub-sdk 0.33.8. Verified live: the build and the container both go in <app>-<project_id>.
  • A JSON-form COPY failed in Modal's context parser.
  • A local ADD was refused by Modal's builder. Both now build, through the Dockerfile copy above.

  Found but not part of this change: modal_vm's VMs have no buildx, so a VM build using a BuildKit-only flag (COPY --chmod, RUN --mount) fails there; beta_scale's have it.

• Rebased onto feat(bundle): write a built image as its build context when its deploys build it in their VMs #136. The bundle form decision now counts Modal as a provider that builds these images: any provider that overrides prepare_image, alongside those that create VMs. A bundle-built agent, gateway server or lone server on modal, or on beta_scale,modal (the Scale default chain), is written as a build context. A lone server on any other provider is still refused. The dry-run line and ledger reason no longer say only VMs build a context.

• A built image Modal no longer holds is built again, once. The process cache never forgot an image id, so if Modal dropped a built image, every later deploy of it would fail until the process restarted. A create that fails with Modal's NotFoundError for an image built from a context now rebuilds it and retries once. Concurrent deploys waiting on the same stale id share one rebuild. Verified live by planting a missing id in the cache: the next deploy rebuilt and ran in 3 s.

• Checked against the hub and worker's Modal client, 1.5.4.dev20: the provider tests pass with it, and a real build from a fresh context deployed in 23 s.

🤖 Generated with Claude Code

Confidence Score: 5/5

The PR appears safe to merge; no new actionable issue was established, and the previous findings are closed.

Findings

1.  Modal builds fail on early Python 3.11 ▶

Fix with agent prompt

### Issue 1
src/agent_env/utils/build_context.py:undefined-107
On Python 3.11.0–3.11.3, `extract()` uses tar filters that those releases lack. The package allows those versions, so preparing a context-only image on Modal fails before the build starts. Require a compatible Python patch release or use an extraction path that works on every supported version.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

Modal can now build images saved only as Docker build contexts before creating containers, while provider chains prepare each provider only when they try it. Bundle planning also recognizes Modal as a builder, and context extraction keeps links from reaching outside the build folder.

• Modal builds context-only images before creating containers.
• Provider chains prepare each image only when they try a provider.
• Bundles can store context-only images for deploys on Modal.
• Context extraction keeps links inside the build folder.
• Modal terminates a sandbox when setup is cancelled.
• Repository setup now targets Python 3.11.4 and updated guidance.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A[Context-only image] --> B[Prepare image]
  B --> C{Provider}
  C -->|Modal| D[Build image on Modal]
  C -->|VM| E[Build image in VM]
  D --> F[Create sandbox]
  E --> F

Loading

_{Reviews (5) · Last reviewed commit: "fix(modal): drop the build-log pointer, ..." · Reviewed by Greptile}

[earakely-scale]

@greptileai review

[greptile-apps]

Modal builds fail on early Python 3.11

On Python 3.11.0–3.11.3, extract() uses tar filters that those releases lack. The package allows those versions, so preparing a context-only image on Modal fails before the build starts. Require a compatible Python patch release or use an extraction path that works on every supported version.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/agent_env/utils/build_context.py
Line: 107

Comment:
**Modal builds fail on early Python 3.11**

On Python 3.11.0–3.11.3, `extract()` uses tar filters that those releases lack. The package allows those versions, so preparing a context-only image on Modal fails before the build starts. Require a compatible Python patch release or use an extraction path that works on every supported version.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

[earakely-scale]

Fixed in 1387697: the package now requires Python 3.11.4 (pyproject, uv.lock, and the README/CONTRIBUTING/AGENTS floor), the release that added tarfile's extraction filters as the fix for CVE-2007-4559. Every CI job and consumer runs 3.11-latest or 3.12, so this only rules out 3.11.0–3.11.3.

[earakely-scale]

@greptileai review

[earakely-scale]

@greptileai review

[earakely-scale]

@greptileai review