Browse the documentation

Early preview

Troubleshooting and FAQ

Start with the exit code: every way an Executor binary ends has its own. The table below says what each one means and where to look.

What an exit code tells you

Exit codeCauseWhat to check
The guest's own codeThe application exited by itself.Your application's logs. The Executor passes the code on unchanged.
0A checkpoint stop.Expected when your application reports its completion checkpoint.
69Required enforcement is unavailable: a strict cap or a container_fallback: "strict" sandbox primitive cannot be enforced on this host. The guest never started.See The binary refuses to start with 69.
70A quota or policy violation: the guest exceeded a strict memory cap or the PID quota, or triggered a fatal syscall trap.Raise the cap in a new build, or check the syscall_profile.
75The exit-event lease was lost under FAIL_CLOSED.Reachability of the control API, credentials, TLS pinning, and max_consecutive_failures.
76A utilization exit event matched.The rule's metric, threshold and for window.
78The pre-launch gate blocked startup: the stop tag was already active.Your control API's response; check_before_start: true polls before launch.
124A time-based exit event: duration, cron, timestamp or idle.Expected at the configured time.
143An external or message exit event matched, or an operator ran oee stop.The audit event names the rule.

The codes of planned stops can be changed in stop_policy.exit_codes; see Stopping and exit codes.

The binary refuses to start with 69

A strict cap must be held by a kernel-enforced limit before the guest starts; the Executor never silently downgrades it.

  • Linux without a writable cgroup. The Executor needs a delegated cgroup v2 subtree, a transient scope from your user's systemd manager, or a writable container cgroup. Provide one, or set resources.allow_governor_fallback: true in a new build to accept the supervisor governor.
  • A container that blocks namespaces. With sandbox.container_fallback: "strict", a missing namespace primitive stops the launch. Use "auto" to layer Landlock, seccomp-BPF, subreaper containment and setrlimit instead.
  • The startup audit event always names the enforcement tier the Executor selected.

The binary refuses to start: verification failed

Any byte change to the supervisor, the policy or the runtime fails BLAKE3 and Ed25519 verification, and the guest never starts. Rebuild and re-sign with oee build, and check a binary with oee inspect <binary> --verify-key oee.pub.

A sandboxed application cannot read a file

Paths outside read_only_paths and read_write_paths are rejected by the kernel with EACCES or ERROR_ACCESS_DENIED. Add the path to the right list and rebuild. Files the application must write go in read_write_paths; they persist after the application stops.

A sandboxed application cannot reach the network

Check sandbox.network.outbound_allow and outbound_allow_cidrs, and inbound_allow_ports for listening ports. Exit-event polling is not affected: the supervisor polls from its own network context.

A JIT runtime crashes under the sandbox

Python, JVM and Node.js need the runtime-managed syscall profile, which keeps the memory protection transitions a JIT needs. It is selected automatically for those runtimes; check that the manifest does not force strict.

The application is slower than expected

A strict CPU cap throttles the whole tree to its limit in every enforcement period. Check the resolved caps with oee status. A percentage cap resolves against the machine or the container the binary runs in, once, at startup.

An exit event never fires

  • Run oee status to see the status of the last exit-event poll.
  • With FAIL_OPEN, transient errors are only logged; use FAIL_CLOSED with max_consecutive_failures if a lost control plane must stop the application.
  • Check the stop_when conditions and match (ANY or ALL), and the top-level combinator.
  • With combinator: "ALL", every rule must match before the application stops.
  • Validate JSONPath expressions and cron schedules with oee validate --strict.

Workers survive a stop

They do not: the Executor stops the whole process tree, including workers that double-fork or call setsid, through the cgroup, the PID namespace or the Job Object. If a process outlives the stop, check that it was started outside the binary.

Replicas do not scale out

  • Auto-scaling needs a cap on every metric it uses.
  • Usage must stay above an upper threshold for the whole scale_out_after window, and a cooldown follows each action.
  • max_replicas and autoscale.total_limits bound the count.
  • A replica that fails its readiness check within the timeout counts as a failed start.

Frequently asked questions

Is the Executor available?

The Executor is in early preview — message us for access, and OpenEng sends you the build by email; Install lists the platforms.

Do I have to change my application?

No. Exit events, caps, the sandbox and scaling all run in the supervisor, outside your code. Checkpoints are optional, for applications that want to report their own progress.

Does stopping delete anything?

No. A stop ends execution; the binary, the runtime cache, the logs and every file your application wrote remain on disk.

Can an operator raise a strict cap on a running instance?

No. Environment variables, CLI arguments, the control socket and remote responses cannot raise or disable a strict cap. Changing it requires a new signed build.

Does the Executor need root, Docker or Kubernetes?

No. Sandboxing uses unprivileged kernel primitives, capping uses a delegated cgroup or a Job Object, and scaling runs inside the supervisor. The Executor also runs as PID 1 in containers; see Containers and Kubernetes.

Which languages does the Executor support?

Native binaries (Go, Rust, C, C++), Python 3.10 to 3.13, Java and Kotlin on JVM 17, 21 and 25, and Node.js, Deno and Bun. See Runtimes and adapters.

How large is the overhead?

The design targets are less than 3.0 MB for the core supervisor and less than 6.0 MB for extended, less than 15 ms of warm startup overhead, and less than 6 MB of RSS at one-minute polling. These are targets, not measured results; see Performance specifications.

Can I try a policy without building?

Yes. oee run -f oee.yaml -- <cmd> runs any local command under the sandbox and exit events.