Browse the documentation

Early preview

How it works

The Executor has two parts: the oee command-line tool, which builds the binary, and oee-stub, the native supervisor at the head of every binary it builds. Both are written entirely in Rust.

From your application to one binary

  1. Build your application as you always do.
  2. Describe it in oee.yaml: its runtime, its start command, and its exit events, CPU and memory caps, auto-scaling and sandbox. oee init --interactive asks for each answer in turn; see Guided configuration.
  3. Validate the manifest with oee validate.
  4. Build with oee build. The Executor bundles the application, its portable runtime and the Ed25519-signed policy atop the supervisor, and writes one binary file.

The binary is made of five integrity-protected segments; Single-binary layout describes them.

When the binary starts

  1. oee-stub verifies the binary: the OEE! footer, the BLAKE3 Merkle root over all segments and the Ed25519 signature. Any byte change fails verification before your application runs.
  2. For Python, JVM and Node.js workloads it extracts the runtime and the application into the runtime cache, or reuses the verified cache.
  3. It resolves your CPU and memory caps once against the machine it runs on, and acquires a kernel-enforced limit for the whole process tree.
  4. If the sandbox is enabled, it builds the isolation boundary: process tree, filesystem, system calls, network and quotas.
  5. If an exit event asks for it (check_before_start: true), it polls once before launch and refuses to start while a stop is already active.
  6. It launches your start command, forwarding standard input and output, environment variables and command-line arguments.

While it runs

A single-threaded asynchronous event loop inside oee-stub multiplexes exit-event polling, monotonic timers, the local checkpoint socket and the child-process wait queues (pidfd on Linux, I/O completion ports on Windows, kqueue on macOS), with negligible idle CPU. It reads the tree's CPU and memory use for oee status, for the heartbeat payload and for the auto-scaler, which starts and removes replicas behind the built-in load balancer.

All of this runs outside the guest language's virtual machine. When the guest deadlocks, holds the Python GIL in a hung C extension, loops forever or thrashes in garbage collection, the supervisor still stops it on time.

When it stops

When an exit event matches, the supervisor latches the stopping state, records an audit event, sends the graceful signal to the guest process group, waits up to the grace period, terminates whatever remains of the tree, flushes the output streams and exits with a deterministic exit code. The binary, the runtime cache, the logs and every file your application wrote stay on disk. See Stopping and exit codes.

Three scenarios

A Go service in Docker

  1. A compiled Go service, order-service, is wrapped in CI with oee build -f oee.yaml -o order-service-oee.
  2. The image (FROM gcr.io/distroless/static-debian12 or FROM alpine) starts it with ENTRYPOINT ["/app/order-service-oee"], so the Executor is the container's PID 1.
  3. oee-stub forwards signals and reaps zombie processes, applies the seccomp and Landlock rules, launches the Go binary and polls the remote exit-event URL every minute.
  4. When the remote API returns the stop tag, such as {"ep_flag": "ABC"}, the Executor sends SIGTERM to the Go process, waits for active HTTP connections to drain up to the configured timeout, stops anything left and exits with status 143 (or your configured code). The container stops with all logs and volume data intact.

A Python uvicorn service that writes 100 files

  1. A FastAPI service served by uvicorn is packaged with its .py files and .whl dependencies into one binary, analytics-api.
  2. analytics-api starts uvicorn --workers 4 inside the Executor's sandbox (or directly on the host with sandbox.enabled: false) and writes 100 report files into ./reports/.
  3. After one hour (after: "1h"), or earlier if the one-minute exit-event poll returns "XYZ", the Executor stops the uvicorn master process and all four workers.
  4. The binary and all 100 files in ./reports/ remain on disk, immediately usable.

A capped Node.js API that scales itself out

  1. A Node.js API is built with resources.cpu.limit: "10%" and resources.memory.limit: "10%", both strict, and autoscale.enabled: true with one to three replicas, a memory upper threshold of "80%" and a lower threshold of "30%".
  2. On a host with 10 cores and 24 GB of memory, each replica's caps resolve once to 1.0 core and 2.4 GB; on a host with 5 cores the same binary resolves to 0.5 core. The load balancer listens on port 8000, and replica 1 starts on a free loopback port.
  3. Under load, replica 1 stays above 80% of its memory cap for the configured window. The supervisor starts replica 2 on another free port, waits for its readiness check and adds it to the load balancer.
  4. When every replica stays below 30% for the scale-in window, the supervisor removes the newest replica from rotation, drains its connections and stops it.
  5. When an exit event fires, the load balancer stops accepting connections and every replica stops. No replica ever exceeds its cap.