Introducing Stagefiles: Sub-200ms Rebuilds Without Dockerfile Hand-Tuning
Wendy Labs · Wendy Labs Team · August 20, 2026
WendyOS Stagefiles
Describe the app. Wendy optimizes the build.
Get fast, reproducible, target-aware containers without hand-tuning a Dockerfile or maintaining the build tricks yourself.
Typed build formatWorks with wendy runStill produces OCI images
Rebuild after editing app.py
<200 ms
150× faster
Stagefile<0.20s
Normal Dockerfile~30s
Change sourcerebuild only sourcerun on device
Automatic cache graph
Only the part you changed rebuilds.
Reproducible by default
Resolved dependencies are written to a lockfile.
Target-aware output
Wendy generates the details for your device.
Stagefiles reduce an example Python source rebuild from roughly 30 seconds to under 200 milliseconds while Wendy manages caching, dependency locking, and device-specific build details.
Turn a roughly 30-second Python edit-build loop into one that takes under 200 ms. A Stagefile gives the build
system enough intent to cache source, OS packages, and language dependencies independently. The surprising part is not
the shorter file. It is the build graph Wendy can generate from it.
Today we are introducing Stagefiles, a typed build format built into WendyOS. Add build.stagefile.yaml to an app and the same wendy run command builds, deploys, starts, and streams it.
This is not a new container runtime or a replacement for Docker. It is a way to describe the build with enough structure for Wendy to make it fast, reproducible, and target-aware automatically.
A Dockerfile can do almost anything. That freedom is useful, but a RUN line does not tell the build system whether it installs a dependency, compiles a tool, downloads a model, or works around CUDA.
Stagefiles make that intent explicit. The project says what it needs; Wendy owns the cache graph, locking, and target-specific details.
What the compiler learns from a Stagefile
01
Typed intent
APT, pip, copies, health checks, and CUDA are declared as data.
02
Parallel cache branches
Changing an OS package does not automatically invalidate Python dependencies.
03
Narrow build context
Only declared local paths enter the build, so large nearby files stay out.
04
Locked inputs
Mutable tags, downloads, and CUDA profiles resolve to reviewable pins.
The number developers will feel
Most projects begin with a readable Dockerfile that builds successfully:
The problem appears on the second build. COPY . . invalidates every later layer after a source edit, and neither package manager has a cache mount.
The cache map shows which branch each edit invalidates.
Stagefile versus a normal Dockerfile
Edit app.py
Only app.py changed. Stagefile rebuilt the source layer; COPY . . forced the normal Dockerfile through its dependency chain again.
More than 150× faster
wendy build · Stagefile
<0.20s
docker build · normal Dockerfile
~30s
What happened to each layer
Stagefile
Base
cached
APT
cached
pip
cached
App
build
Dockerfile
Base
cached
APT
build
pip
build
App
build
Scenario
Wendy Stagefile
Normal Dockerfile
Edit only app.py
<0.20 s
~30 s
Add one APT dependency
2.73 s
~30 s
For the Python edit, Stagefile only rebuilds the source layer. For the APT edit, it rebuilds the APT branch while the independent pip branch stays cached. The normal Dockerfile walks through both package installs again in either case.
Stagefile generates the optimized graph automatically and carries it forward as the compiler improves. Every comparison in this article uses the normal Dockerfile above.
What Wendy generates for you
A Stagefile copies source last, gives each package manager a locked cache, and compiles independent dependency branches. That structure makes iteration faster.
We placed an unused 128 MB training-data.bin beside the app.
The normal COPY . . Dockerfile transferred 134.25 MB and copied it into the image.
Stagefile transferred 63 bytes because copy.from: local creates an allowlist.
Build-context upload with a 128 MB training artifact in the project
Stagefile
Declared local paths
63 B
<0.1s
Normal Dockerfile
COPY . .
134.25 MB
0.5s
COPY . . sends the whole repository unless a maintained .dockerignore says otherwise. Stagefile derives a narrow allowlist directly from the files declared in the build.
Stagefile makes the narrow context the default and derives it from the build declaration, so there is no separate ignore list to keep in sync.
The resulting local images were 196.9 MB for Stagefile and 207.6 MB for the Dockerfile. That is not a device-upload benchmark: compressed layers and warm device caches change transfer behavior.
Meet build.stagefile.yaml
The canonical filename is build.stagefile.yaml.
Build a Stagefile one decision at a time
build.stagefile.yaml
1version: 1
2stages:
3 - name: app
4 from: python:3.11-slim
5 workdir: /app
Step 1
Choose the runtime
Start with one named stage, a base image, and a working directory.
There is deliberately no RUN field. Package installation, downloads, language builds, copies, health checks, and processes are typed operations with known inputs.
Put the file beside the app and run:
wendy run
The command detects the Stagefile, builds for the selected device, deploys the image, starts the app, and streams its output. Use wendy build when you only want the image.
What happens when Wendy builds it
A short source file does not remove the hard work. It moves that work into a compiler that can be tested once and reused across projects.
What happens between build.stagefile.yaml and a finished image
Stage 1 of 5
Read intent
Wendy detects build.stagefile.yaml and parses its typed fields.
The first build also creates build.stagefile.lock.yaml. Check it into source control: it records the exact image digests, download hashes, and target-specific CUDA profiles resolved from readable declarations.
Click a declaration to reveal the build detail Wendy owns
You write
from: python:3.11-slim
Wendy derives
FROM python:3.11-slim@sha256:90744cff…
A tag becomes an immutable input
The readable tag stays in source control. Its digest is resolved into the lockfile, so the same Stagefile cannot silently pick up different base bytes tomorrow.
These generated details are not an interface your project maintains. As BuildKit and target devices evolve, the compiler can improve while the Stagefile continues expressing the same intent.
cuda: true replaces board-specific trivia
GPU containers make the value obvious. The correct CUDA runtime, wheel index, loader paths, and supported package builds depend on the target Jetson.
The stage-level flag requests the supported GPU stack. The nested flag selects the matching GPU wheel source. Wendy resolves the profile for the device architecture and pins it in the lockfile.
If no tested profile exists, the build stops before deployment instead of producing a container whose first GPU operation fails on the robot.
Stages mean container build stages
They do not mean staging versus production. One stage can compile an artifact; a later stage copies only the runtime output.
The final image receives the packages but not the compiler. Structured from, copy, and install fields also let Wendy validate stage references and paths before building.
No hidden shell escape hatch
Adding run: curl ... | sh would erase the facts Stagefile needs for input validation, digest locking, safe quoting, and cache planning.
That does not make Stagefiles a replacement for every Dockerfile.
Choose the build file by the job
Use a Stagefile
The compiler knows the operation
Package installation and language builds
Local files, downloads, health checks, and processes
CUDA profiles for supported targets
Keep a Dockerfile
The build genuinely needs shell freedom
Custom commands the schema does not model
Specialized third-party installers or toolchains
Low-level control is more important than compiler guarantees
Wendy auto-detects all three formats. The escape hatch stays at the build-file level, where choosing unrestricted behavior is explicit.
Start with the app you already have
Translate one concern at a time: base image, dependencies, local files, build step, runtime process, then health check. Run wendy build after each move.
The WendyOS examples include Python, GPU, ONNX, ROS 2, Swift, Rust, Go, web, and multi-service Stagefiles. Install or update the Wendy CLI, add build.stagefile.yaml, and run it on the device you already use.
A Stagefile is small because it leaves out decisions the application should never have owned. You describe the software; Wendy carries the container knowledge forward.
Trending
Related posts
Expand your knowledge with these hand-picked posts.
Wendy Net is a private, zero trust network built into WendyOS. Devices connect over Ethernet, Wi-Fi, Wi-Fi Aware, Bluetooth Low Energy and Wendy Cloud, and your apps find each other with ordinary mDNS and talk over plain HTTP, TCP and UDP.
Build one small Python app that lets a Qualcomm Dragonwing IQ9, a Raspberry Pi 5 and an NVIDIA Jetson find each other, encrypt their messages and hold them when a board goes dark, all without an internet connection.
Wendy Labs · Wendy Labs Team
Get started
Start with one device. Close the loop around it.
Use WendyOS on your hardware or add Wendy Agent to an existing Linux or Apple Silicon Mac. Connect sensors, run your code, and carry what you learn into the next release.