Single-binary layout
oee build produces one standalone host executable made of five sequential segments. The operating system starts it like any other program; the supervisor in the first segment does the rest.
The five segments
+---------------------------------------------------------------------------+
| Segment 1: Native Rust supervisor oee-stub (ELF / PE / Mach-O) |
| - Signature verifier, sandbox builder, exit events, PID reaper |
+---------------------------------------------------------------------------+
| Segment 2: Signed policy manifest (Ed25519-signed binary oee.yaml) |
| - Sandbox rules, CPU/memory caps, auto-scaling, exit events, timeouts |
+---------------------------------------------------------------------------+
| Segment 3: Portable language runtime archive (zstd, read-only) |
| - Standalone CPython + wheels, jlink JRE, Node binary, or 0 bytes (Go) |
+---------------------------------------------------------------------------+
| Segment 4: Guest application bundle (zstd) |
| - Wrapped Go binary, Python package/uvicorn app, fat JAR, or JS bundle |
+---------------------------------------------------------------------------+
| Segment 5: Fixed 128-byte OEE! footer |
| - Segment byte offsets and uncompressed sizes (u64 x 4) |
| - 32-byte BLAKE3 Merkle root across segments 1..4 |
| - 64-byte Ed25519 detached signature |
| - 4-byte magic trailer 0x4F454521 ("OEE!") + schema version (u16) |
+---------------------------------------------------------------------------+
| Segment | Contents | Notes |
|---|---|---|
| 1. Supervisor | oee-stub for the target: ELF on Linux, PE on Windows, Mach-O on macOS. Its design target is under 3.0 MB for core and under 6.0 MB for extended. | The core or extended variant, whichever is the smallest that satisfies the manifest. |
| 2. Policy | Your oee.yaml, in binary form, signed with Ed25519. | Holds the sandbox rules, the CPU and memory caps, auto-scaling, exit events and timeouts. Caps sealed here cannot be raised at run time. |
| 3. Runtime | A standalone CPython with its wheels, a jlink JRE, or a Node.js binary, compressed with zstd, read-only. | Empty (0 bytes) for native Go, Rust, C and C++ binaries. |
| 4. Application | Your Go binary, Python package or uvicorn app, fat JAR, or JavaScript bundle, compressed with zstd. | |
| 5. Footer | 128 bytes: the offsets and uncompressed sizes of the segments, the BLAKE3 Merkle root over segments 1 to 4, the Ed25519 signature, and the magic 0x4F454521 (OEE!) with a schema version. | oee inspect reads and verifies it. |
Verification before anything runs
Before the guest application starts, oee-stub checks the OEE! trailer, recomputes the BLAKE3 Merkle root across segments 1 to 4 and verifies the Ed25519 signature with the public key embedded at build time. Any byte modification to the supervisor, the embedded policy or the bundled runtime archive fails verification, and the application never starts. See Security and integrity.
You can run the same verification yourself:
oee inspect ./dist/my-service --verify-key ./certs/oee.pub
What the layout gives you
- One file to ship and sign. Nothing else needs to be installed, copied or kept in step on the host.
- No host drift. The runtime travels inside the file, so a mismatched system Python or Java, or a missing shared library, cannot break the application.
- Small static overhead. The supervisor is built with
lto = "fat",codegen-units = 1andpanic = "abort"againstmuslon Linux and the static CRT on Windows, and runs insideFROM scratchimages.