Browse the documentation

Early preview

CLI reference

You use the Executor entirely through one command-line tool, oee, a single static Rust executable. It has nine subcommands.

SubcommandWhat it does
oee initDetects your project and scaffolds an annotated oee.yaml, or runs the guided configuration.
oee validateValidates a manifest before you build.
oee keygenGenerates an Ed25519 signing key pair.
oee buildPackages the application, its runtime and the signed policy into one executable.
oee runRuns any local command under the sandbox and exit events, without building first.
oee inspectVerifies a built binary and prints what it contains.
oee statusReports on running Executor instances.
oee stopStops a running instance cleanly.
oee runtimeLists, pre-fetches and verifies the portable runtimes in the build cache.

The standard workflow

# 1. Scaffold a configuration for a Python uvicorn project
oee init --lang python --sandbox

# 1b. Or answer guided questions instead (application, runtime, start command,
#     exit events, CPU/memory caps, auto-scaling) to produce the same oee.yaml
oee init --interactive

# 2. Validate sandbox path policies and exit-event JSONPath expressions
oee validate -f oee.yaml --strict

# 3. Generate Ed25519 manifest signing keys
oee keygen --out-dir ./certs

# 4. Build a standalone single-binary executable for Linux x86_64
oee build \
  -f oee.yaml \
  --target linux-x86_64 \
  --sign-key ./certs/oee.key \
  -o ./dist/my-service

# 5. Inspect and verify the signature of the built binary
oee inspect ./dist/my-service --verify-key ./certs/oee.pub

# 6. Run the single binary directly (CLI flags pass through when configured)
OEE_API_KEY="sec_live_98a7bc..." ./dist/my-service --log-level info

oee init

oee init [--lang <auto|python|go|java|node|binary>] [--sandbox] [--interactive]

Detects the project structure (pyproject.toml, requirements.txt, go.mod, pom.xml, package.json) and scaffolds an annotated oee.yaml.

FlagMeaning
--lang <value>The application's language: auto (detect it), python, go, java, node or binary (any compiled executable).
--sandboxScaffold the manifest with the sandbox enabled.
--interactiveRun the guided configuration: application, runtime, start command, exit events, CPU and memory capping, auto-scaling and sandbox. It validates every answer, writes no secret unless you choose a sealed static token, and prints the exact oee build command to run next.
oee init --lang python --sandbox
oee init --interactive

oee validate

oee validate [-f <oee.yaml>] [--strict]

Validates the manifest's syntax, sandbox path permissions, cron expressions, JSONPath queries and environment variable references before you build.

FlagMeaning
-f <oee.yaml>The manifest to validate.
--strictValidate in strict mode.
oee validate -f oee.yaml --strict

oee keygen

oee keygen [--out-dir <dir>]

Generates an Ed25519 key pair: oee.key, the private key that signs the policy, and oee.pub, the public verification key that is embedded into oee-stub.

FlagMeaning
--out-dir <dir>The directory to write oee.key and oee.pub to.
oee keygen --out-dir ./certs

oee build

oee build [-f <oee.yaml>] [--target <triple>] [-o <binary>] [--sign-key <path>]

Packages the guest workload, its portable language runtime and the signed policy atop oee-stub into a single standalone executable, choosing the smallest supervisor variant that satisfies the manifest. It builds for other platforms than the one it runs on, for example windows-x86_64 from a Linux CI runner.

FlagMeaning
-f <oee.yaml>The manifest to build from.
--target <triple>The platform the binary runs on, such as linux-x86_64 or windows-x86_64.
-o <binary>The output file.
--sign-key <path>The Ed25519 private key that signs the policy, such as ./certs/oee.key.
oee build -f oee.yaml --target linux-x86_64 --sign-key ./certs/oee.key -o ./dist/my-service
oee build -f oee.yaml -o order-service-oee

oee run

oee run [-f <oee.yaml>] -- <cmd> [args...]

Development supervisor mode: runs an arbitrary local command directly under the Executor's sandbox and exit events, without building a packaged binary first.

Flag or argumentMeaning
-f <oee.yaml>The manifest whose policy applies.
-- <cmd> [args...]The command to run and its arguments, after --.
oee run -f oee.yaml -- python -m uvicorn app.server:api --port 8000

oee inspect

oee inspect <oee-binary> [--verify-key <oee.pub>]

Verifies the OEE! footer, the BLAKE3 Merkle root and the Ed25519 signature, and prints the embedded policy summary, the target operating system and architecture, and the bundled runtime versions.

Flag or argumentMeaning
<oee-binary>The binary to inspect.
--verify-key <oee.pub>The public key to verify the signature with.
oee inspect ./dist/my-service --verify-key ./certs/oee.pub

oee status

oee status [--instance <id>] [--json]

Queries the Executor instances running locally through authenticated, user-scoped control sockets. It reports the process-tree count, the sandbox state, uptime, the status of the last exit-event poll, the resolved CPU and memory caps with current usage, the replica count, each replica's port, readiness and usage, and the health and active connections of each load-balancer backend.

FlagMeaning
--instance <id>Report on one instance only.
--jsonMachine-readable output.
oee status
oee status --instance <id> --json

oee stop

oee stop <instance-id | --all> [--mode <graceful|immediate>]

Sends an authenticated local operator stop command to a running supervisor, which runs the state-preserving stop of its whole process tree. The instance exits with code 143.

Flag or argumentMeaning
<instance-id>The instance to stop.
--allStop every running instance.
--mode <mode>graceful: signal, bounded drain, then hard termination. immediate: terminate the tree at once.

The local control socket can stop an instance, but it can never raise or disable a sealed CPU or memory cap.

oee stop <instance-id> --mode graceful
oee stop --all --mode immediate

oee runtime

oee runtime list
oee runtime fetch
oee runtime verify

Manages the portable runtimes that oee build bundles, in the local build cache.

ActionMeaning
listLists the portable CPython, jlink JDK and Node.js distributions in the cache.
fetchPre-fetches them, so builds do not wait for downloads.
verifyChecksum-verifies them.

Running a built binary

A built binary is run directly, like any program:

./dist/my-service --log-level info

With workload.passthrough_cli_args: true, its command-line arguments reach your application. Environment variables named by from_env are read by the supervisor at startup and, with scrub_from_guest_env: true (the default), never reach the application.