Skip to content

make multistage built, add adjustable mb#364

Merged
breardon2011 merged 3 commits into
mainfrom
fix/upsize-default-builder
Jun 11, 2026
Merged

make multistage built, add adjustable mb#364
breardon2011 merged 3 commits into
mainfrom
fix/upsize-default-builder

Conversation

@breardon2011

@breardon2011 breardon2011 commented Jun 10, 2026

Copy link
Copy Markdown
Contributor

Settable build memory for declarative images (build big, run small)

Problem

Declarative image builds (Image.base().aptInstall(...), snapshots) ran in a
1 GB build sandbox, so heavy apt/pip/npm builds OOM.

The naive fix — give the builder more RAM — has a trap. The build checkpoint is
a savevm (it captures live memory), and ForkFromCheckpoint floors every
fork at the snapshot's running memory (shrinking below it would OOM the
restored processes). So building at, say, 8 GB would pin every image's
minimum run size to 8 GB — a silent, permanent cost floor for all template users.

Solution

Decouple build memory from the image's run memory with a two-phase build:

  1. builderMemory (default 4 GB, settable) — the only new image knob. Sets
    the RAM for the build phase; raise it when a build OOMs.
  2. Finalize pass — after the steps run, the worker cold-boots a fresh VM from
    the built disks at a 1 GB floor and snapshots that. So the build can use
    4 GB (or more) while the image still forks down to 1 GB.
  3. Run size is chosen at create timeSandbox.create({ memoryMB })
    hotplugs up from the 1 GB floor (pre-existing virtio-mem behavior). Every image
    now covers the full 1 → 16 GB range.

The cold-boot reuses the existing TemplateRootfsKey create path — no new
QEMU/checkpoint code
in the fragile subsystem, just orchestration.

API

One public knob on the image; the floor is internal.

const image = Image.base()
  .aptInstall(['build-essential', 'cmake'])
  .runCommands('make -j')
  .builderMemory(8192);          // 8 GB to build…

const sandbox = await Sandbox.create({ image, memoryMB: 4096 });  // …run at 4 GB

The image's 1 GB floor is set by an internal runtimeMemoryMB (defaults to 1 GB,
not exposed in the SDKs  available via raw manifest only, for the rare image
whose services auto-start heavy at boot).

Behavior / back-compat

- Floor stays at 1 GB; forks stay instant (still a warm savevm). Existing
manifests are unaffected  builds just stop OOMing.
- builderMemory is excluded from the content hash (a build resource, not
image content)  consistent across server + both SDKs.

Surface

- Proto: CreateCheckpointRequest.finalize_memory_mb
- Worker: CreateCheckpoint routes to the finalize path when set
- Manager: new CreateCheckpointFinalized (sync  cold-boot at floor  snapshot  cleanup)
- API: buildImage runs the build VM at builderMemory, finalizes at the floor
- SDKs: .builderMemory() / .builder_memory() (TS + Python)
- Docs: "Build memory" section + per-class SDK reference pages

Validation (dev)

30 builds across the full matrix  build sizes 1/4/8/16 GB + defaults, floors,
wake sizes 1–16 GB (clamp-up and hotplug-up), every step kind
(run/apt/pip/env/file/multi/big):
- All builds came up ready; build content survived the finalize cold-boot in
100% of cases.
- Run memory was correct in every case (clamps to floor below it, hotplugs above).
- Ephemeral finalize VMs cleaned up; no leaks. 

@mintlify

mintlify Bot commented Jun 10, 2026

Copy link
Copy Markdown

Preview deployment for your docs. Learn more about Mintlify Previews.

Project Status Preview Updated (UTC)
opencomputer 🟢 Ready View Preview Jun 10, 2026, 11:29 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

@breardon2011 breardon2011 marked this pull request as ready for review June 10, 2026 23:29
@2027-evals

2027-evals Bot commented Jun 10, 2026

Copy link
Copy Markdown

2027 — Eval complete for commit 860728e

URL Mapping
digger.dev opensandbox-fix-upsize-default-builder.mintlify.app
opencomputer.dev opensandbox-fix-upsize-default-builder.mintlify.app

2027 // complete the getting started guide at https://opencomputer.d — Did not finish

- ⚠️ Score nulled: AI judge determined the task was not completed — "Task incomplete — sandbox.create() failed with 402 'free trial credits exhausted', so the guide's Hello World command never ran."
Prompt

complete the getting started guide at https://opencomputer.dev

Commit 860728e · View report →


Evaluating agent experience using 2027.dev · View dashboard

@breardon2011 breardon2011 merged commit c051060 into main Jun 11, 2026
5 checks passed
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