Browse the documentation

Early preview

oee.yaml reference

oee.yaml is the policy manifest of an Executor binary. oee init scaffolds it, oee validate checks it, and oee build signs it with Ed25519 and seals it into the binary's policy segment, where nothing at run time can change it.

Top level

KeyValueMeaning
apiVersion"oee.dev/v3"The manifest format version.
kind"RuntimePolicy"The kind of document.
metadataObjectThe application's name and version.
workloadObjectWhat runs, with which runtime and which command.
sandboxObjectKernel-enforced isolation.
resourcesObjectNative CPU and memory caps and other quotas, enforced with or without the sandbox.
autoscaleObjectReplicas and the built-in load balancer.
stop_policyObjectHow the application is stopped, and the exit codes.
exit_eventsObjectThe rules that end execution, and how they combine.

The complete example

A Python uvicorn service with the sandbox, strict caps, auto-scaling, and exit events of every kind:

apiVersion: "oee.dev/v3"
kind: "RuntimePolicy"

metadata:
  name: "payment-reconciliation-api"
  version: "3.0.0"

workload:
  adapter: "python"
  python:
    version: "3.12"
    requirements: "./requirements.txt"
    bundle_paths:
      - "./app"
      - "./configs"
  entrypoint:
    - "python"
    - "-m"
    - "uvicorn"
    - "app.server:api"
    - "--host"
    - "0.0.0.0"
    - "--port"
    - "{{port}}"                        # Replica port chosen by the Executor (8000 when auto-scaling is off)
    - "--workers"
    - "4"
  passthrough_cli_args: true
  working_dir: "."

sandbox:
  enabled: true
  container_fallback: "auto"
  syscall_profile: "runtime-managed"
  filesystem:
    read_only_paths:
      - "/etc/ssl/certs"
      - "./configs"
    read_write_paths:
      - "./reports"                     # All files created here remain intact on disk
      - "./logs"
      - "/tmp/app-scratch"
  network:
    inbound_allow_ports: [8000]
    outbound_allow: true
    outbound_allow_cidrs:
      - "10.0.0.0/8"
      - "172.16.0.0/12"

resources:                              # Native capping, enforced with or without the sandbox
  cpu:
    limit: "10%"                        # 10% of this machine's cores; or "1vcpu", "0.5vcpu"
    mode: "strict"                      # strict | flexible
  memory:
    limit: "10%"                        # 10% of this machine's memory; or "10GB", "512MB"
    mode: "strict"                      # Hard ceiling: never exceeded, never changed at run time
  max_pids: 64
  max_open_files: 4096
  allow_governor_fallback: false        # strict + no kernel hard limit available => refuse to start

autoscale:
  enabled: true
  min_replicas: 1
  max_replicas: 4
  metrics:
    memory:
      upper_threshold: "80%"            # Of the per-replica memory cap: scale out above this
      lower_threshold: "30%"            # Scale in below this
    cpu:
      upper_threshold: "75%"
      lower_threshold: "20%"
  scale_out_after: "30s"                # Usage must stay above the upper threshold this long
  scale_in_after: "5m"
  cooldown: "60s"
  replica:
    port_range: "auto"                  # Or an explicit range such as "20000-20100"
    port_env: "PORT"                    # Also available as {{port}} in the entrypoint
    readiness:
      type: "http"                      # tcp | http
      path: "/healthz"
      timeout: "30s"
  load_balancer:
    listen: "0.0.0.0:8000"              # Public address; replicas listen on loopback ports
    mode: "tcp"                         # tcp | http
    algorithm: "round_robin"            # round_robin | least_connections
    health_check:
      interval: "5s"
      unhealthy_threshold: 3
    drain_timeout: "30s"
  total_limits:                         # Optional hard ceiling across all replicas together
    cpu: "50%"
    memory: "8GB"

stop_policy:
  default_mode: "GRACEFUL"              # GRACEFUL | IMMEDIATE
  graceful_signal: "SIGTERM"            # Delivered to guest process group first
  grace_period_ms: 10000                # Escalates to SIGKILL / TerminateJobObject after 10s
  allow_remote_stop_params: true
  exit_codes:
    on_exit_event: 143                  # External-source and message exit events
    on_ttl_expired: 124                 # duration, cron, timestamp, idle
    on_utilization: 76                  # utilization exit events
    on_checkpoint: 0
    on_lease_lost: 75

exit_events:
  combinator: "ANY"                     # First matched rule stops the application cleanly
  rules:
    - id: "one-hour-max-ttl"
      type: "duration"
      after: "1h"

    - id: "end-of-window-cutoff"
      type: "cron"
      schedule: "0 23 * * *"
      timezone: "UTC"

    - id: "reconciliation-done-checkpoint"
      type: "checkpoint"
      ipc_event: "RECONCILIATION_FINISHED"
      stop_mode: "GRACEFUL"

    - id: "remote-api-exit"
      type: "http_poll"
      url: "https://controlplane.example.org/api/v1/runtime/gate"
      method: "GET"
      interval: "1m"                    # Polls every 1 minute
      jitter: "5s"
      timeout: "8s"
      check_before_start: true          # Blocks launch if exit event is already active
      auth:
        scheme: "bearer"
        from_env: "OEE_AUTH_TOKEN"      # Read from host env var & hidden from guest process
        scrub_from_guest_env: true
      tls:
        min_version: "1.3"
        pinned_spki_sha256: "sha256/VjLZe/p3W/PJnd6lL8JVNBCGQBZynFLdZSTIqcO0SJ8="
      stop_when:
        match: "ANY"
        conditions:
          - json_path: "$.ep_flag"
            in: ["ABC", "XYZ", "HALT"]
          - body_exact: "ABC"
          - http_status: [410, 423]
      on_network_error:
        mode: "FAIL_OPEN"               # Or FAIL_CLOSED with max_consecutive_failures: 5

    - id: "license-file-removed"
      type: "file_watch"
      path: "/var/run/payments/license.lock"
      events: ["deleted"]               # deleted | created | modified | content_match

    - id: "ops-control-topic"
      type: "kafka"
      brokers: ["kafka-1.internal:9093", "kafka-2.internal:9093"]
      topic: "ops.runtime.control"
      tls:
        enabled: true
      auth:
        mechanism: "scram-sha-512"      # none | plain | scram-sha-256 | scram-sha-512
        username_from_env: "OEE_KAFKA_USER"
        password_from_env: "OEE_KAFKA_PASSWORD"
      stop_when:
        match: "ALL"
        conditions:
          - json_path: "$.app"
            equals: "payment-reconciliation-api"
          - json_path: "$.action"
            in: ["STOP", "HALT"]

    - id: "status-update-webhook"
      type: "webhook"
      listen: "127.0.0.1:9911"
      path: "/oee/status"
      auth:
        scheme: "none"                  # Open endpoint; or bearer | header | hmac
      stop_when:
        match: "ANY"
        conditions:
          - json_path: "$.status"
            in: ["REVOKED", "SUSPENDED"]

    - id: "redis-flag-probe"
      type: "command"
      run: ["/usr/local/bin/check-halt-flag.sh"]
      interval: "30s"
      timeout: "5s"
      stop_when:
        match: "ANY"
        conditions:
          - exit_code: [10]             # Or stdout_contains / stdout_regex

    - id: "idle-for-30-minutes"
      type: "idle"
      after: "30m"
      cpu_below: "1%"

    - id: "sustained-memory-pressure"
      type: "utilization"
      metric: "memory"                  # cpu | memory | pids | disk_used | disk_free
      above: "95%"                      # Of the memory cap (or an absolute amount such as "2GB")
      for: "5m"

    - id: "reports-volume-full"
      type: "utilization"
      metric: "disk_used"
      path: "./reports"
      above: "10GB"
      for: "1m"

    - id: "database-gone"
      type: "tcp_probe"
      address: "db.internal:5432"
      interval: "10s"
      exit_when: "unreachable"          # unreachable | reachable
      failures: 3

    - id: "launcher-exited"
      type: "process_watch"
      watch: "parent"                   # parent | pid_file (with pid_file: "/run/app/sidecar.pid")

    - id: "operator-signal"
      type: "signal"
      signal: "SIGUSR1"

    - id: "fleet-control-mqtt"
      type: "mqtt"
      broker: "mqtts://mqtt.internal:8883"
      topic: "fleet/+/control"
      stop_when:
        match: "ANY"
        conditions:
          - json_path: "$.command"
            equals: "shutdown"

metadata

KeyExampleMeaning
metadata.name"payment-reconciliation-api"The application's name, available to the heartbeat payload as {{app_name}}.
metadata.version"3.0.0"The application's version, available as {{app_version}}.

workload

KeyExampleMeaning
workload.adapter"python"The runtime adapter: native binary, Python, JVM or Node.js.
workload.<adapter>.version"3.12"The runtime version: Python 3.10 to 3.13, JVM 17, 21 or 25.
workload.<adapter>.requirements"./requirements.txt"The Python dependencies to resolve and bundle.
workload.<adapter>.bundle_paths["./app", "./configs"]The application's files and directories to bundle.
workload.entrypoint["python", "-m", "uvicorn", ...]The exact command line that starts the service, one list item per argument. {{port}} is replaced by the replica's port, or by the port of autoscale.load_balancer.listen when auto-scaling is off.
workload.passthrough_cli_argstrueWhether arguments given to the binary pass through to the application.
workload.working_dir"."The working directory of the application.

sandbox

KeyValuesMeaning
sandbox.enabledtrue, falseTurns the isolation boundary on or off. With false, the application runs on the host with standard user permissions, still under supervision, caps and exit events.
sandbox.container_fallback"auto" (default), "strict"Inside a container: layer the unprivileged primitives that are available, or refuse to start (exit code 69) when a requested namespace primitive is not.
sandbox.syscall_profile"strict", "runtime-managed", "custom"The system-call filter. strict is the default for Go and Rust static binaries; runtime-managed is selected for Python, JVM and Node.js.
sandbox.filesystem.read_only_pathsList of pathsHost paths or workspace folders the guest may read.
sandbox.filesystem.read_write_pathsList of pathsPaths the guest may change. Files written there persist after a stop.
sandbox.network.inbound_allow_portsList of ports, such as [8000]Ports the guest may accept connections on. With auto-scaling, it governs the public load-balancer port only.
sandbox.network.outbound_allowtrue, falseWhether the guest may open outbound connections.
sandbox.network.outbound_allow_cidrsList of CIDRsWhere outbound connections may go.

Sandboxing explains each dimension on Linux, Windows and macOS.

resources

KeyValuesMeaning
resources.cpu.limit"10%", "1vcpu", "0.5vcpu", "2"A share of the machine's logical CPUs, or an absolute number of cores.
resources.cpu.mode"strict" (default), "flexible"A hard ceiling, or a proportional share with optional bursting.
resources.cpu.burst_limitA CPU quantityIn flexible mode, the hard ceiling of bursting.
resources.memory.limit"10%", "10GB", "512MB", "2GiB"A share of the machine's physical memory, or an absolute amount.
resources.memory.mode"strict" (default), "flexible"A hard ceiling that is never exceeded, or a soft target the kernel reclaims toward.
resources.memory.burst_limitA memory quantityIn flexible mode, the hard ceiling.
resources.max_pids64The most processes the tree may hold.
resources.max_open_files4096The file descriptors per process.
resources.allow_governor_fallbackfalse (default), trueOn Linux without a kernel hard limit: refuse to start a strict cap (exit code 69), or enforce it with the supervisor governor.

CPU and memory capping explains resolution, modes and enforcement.

autoscale

KeyExampleMeaning
autoscale.enabledtrueTurns auto-scaling and the load balancer on.
autoscale.min_replicas1The fewest replicas.
autoscale.max_replicas4The most replicas.
autoscale.metrics.memory.upper_threshold"80%"Scale out above this share of the per-replica memory cap.
autoscale.metrics.memory.lower_threshold"30%"Scale in below this share.
autoscale.metrics.cpu.upper_threshold"75%"Scale out above this share of the per-replica CPU cap.
autoscale.metrics.cpu.lower_threshold"20%"Scale in below this share.
autoscale.scale_out_after"30s"How long usage must stay above an upper threshold.
autoscale.scale_in_after"5m"How long usage must stay below every lower threshold.
autoscale.cooldown"60s"The pause after every scaling action.
autoscale.replica.port_range"auto", or a range such as "20000-20100"Where replica ports come from.
autoscale.replica.port_env"PORT"The environment variable that carries the replica's port; it is also {{port}} in the entry point.
autoscale.replica.readiness.type"tcp", "http"The readiness check: a TCP connect, or an HTTP GET returning a success status.
autoscale.replica.readiness.path"/healthz"The path of an HTTP readiness check.
autoscale.replica.readiness.timeout"30s"How long a new replica has to become ready before it counts as a failed start.
autoscale.load_balancer.listen"0.0.0.0:8000"The public address; replicas listen on loopback ports.
autoscale.load_balancer.mode"tcp" (default), "http"Balance TCP connections, or individual HTTP/1.1 requests with X-Forwarded-For.
autoscale.load_balancer.algorithm"round_robin" (default), "least_connections"How backends are chosen.
autoscale.load_balancer.health_check.interval"5s"How often backends are checked.
autoscale.load_balancer.health_check.unhealthy_threshold3Failed checks before a backend is marked unhealthy.
autoscale.load_balancer.drain_timeout"30s"How long a removed replica's connections may drain.
autoscale.total_limits.cpu"50%"Optional hard ceiling of CPU across all replicas together.
autoscale.total_limits.memory"8GB"Optional hard ceiling of memory across all replicas together.

Auto-scaling and load balancer explains the scaling model.

stop_policy

KeyValuesMeaning
stop_policy.default_mode"GRACEFUL", "IMMEDIATE"How exit events stop the application unless a rule says otherwise.
stop_policy.graceful_signal"SIGTERM", "SIGINT"The signal delivered to the guest process group first.
stop_policy.grace_period_ms10000The drain budget before hard termination (SIGKILL or TerminateJobObject).
stop_policy.allow_remote_stop_paramstrue, falseWhether an exit-event response may choose stop_mode and grace_period_ms.
stop_policy.exit_codes.on_exit_event143External-source and message exit events, and oee stop.
stop_policy.exit_codes.on_ttl_expired124duration, cron, timestamp and idle.
stop_policy.exit_codes.on_utilization76utilization exit events.
stop_policy.exit_codes.on_checkpoint0Checkpoint stops.
stop_policy.exit_codes.on_lease_lost75A lost lease under FAIL_CLOSED.

Stopping and exit codes lists every exit code.

exit_events

KeyValuesMeaning
exit_events.combinator"ANY" (default), "ALL"Stop on the first matching rule, or when every rule has matched.
exit_events.rulesList of rulesThe exit events.

Keys every rule takes

KeyMeaning
idA unique name for the rule, used in audit events.
typeThe kind of exit event (below).
stop_modeOptional: "GRACEFUL" or "IMMEDIATE", overriding stop_policy.default_mode.

Keys by rule type

typeKeys
durationafter (such as "1h", "30m", "24h")
cronschedule (a cron expression such as "0 23 * * *"), timezone (such as "UTC")
timestampat (an ISO-8601 time such as "2026-12-31T23:59:59Z")
idleafter, cpu_below (default "1%")
utilizationmetric (cpu, memory, pids, disk_used, disk_free), above or below, for, and path for the disk metrics
http_pollurl, method (GET, POST, HEAD), interval, jitter, timeout, check_before_start, auth, tls, stop_when, on_network_error
webhooklisten (default address 127.0.0.1), path, auth, stop_when
file_watchpath, events (deleted, created, modified, content_match)
commandrun, interval, timeout, stop_when with exit_code, stdout_contains or stdout_regex
tcp_probeaddress, interval, exit_when (unreachable, reachable), failures
process_watchwatch (parent or pid_file); with pid_file, the key pid_file names the PID file
signalsignal (such as "SIGUSR1")
kafkabrokers, topic, tls.enabled, auth.mechanism (none, plain, scram-sha-256, scram-sha-512), auth.username_from_env, auth.password_from_env, stop_when
mqttbroker (such as "mqtts://mqtt.internal:8883"), topic, stop_when
nats, redisThe subject or channel, connection, TLS and credential settings of the source, and stop_when
checkpointipc_event
log_matchThe sentinel pattern to watch for on stdout and stderr
on_task_completeNo further keys

auth

KeyValuesMeaning
auth.scheme"none", "bearer", "header", "hmac", Basic, mutual TLSHow requests are authorized. Left out, no credentials are sent.
auth.from_envAn environment variable name, such as "OEE_AUTH_TOKEN"Read the credential from the host environment at startup.
auth.from_fileA file path, such as "/run/secrets/oee_api_token"Read the credential from a mounted secret file.
auth.scrub_from_guest_envtrue (default), falseStrip the from_env variable from the guest's environment.

tls

KeyExampleMeaning
tls.min_version"1.3"The lowest TLS version accepted.
tls.pinned_spki_sha256"sha256/VjLZe/p3W/PJnd6lL8JVNBCGQBZynFLdZSTIqcO0SJ8="One or more pinned SHA-256 Subject Public Key Info hashes.
tls.enabledtrueFor message sources: connect over TLS.

stop_when

KeyMeaning
stop_when.match"ANY" or "ALL" of the conditions.
stop_when.conditionsA list of conditions: json_path with in or equals; body_exact; a substring or a regular expression; http_status; a response header; exit_code, stdout_contains or stdout_regex for commands.

on_network_error

KeyValuesMeaning
on_network_error.mode"FAIL_OPEN" (default), "FAIL_CLOSED"Keep running through outages, or treat a lost lease as a stop.
on_network_error.max_consecutive_failuresSuch as 5With FAIL_CLOSED, how many polls may fail in a row before the stop.

Exit events explains every rule type with examples.

Validation

oee validate -f oee.yaml --strict checks the syntax, sandbox path permissions, cron expressions, JSONPath queries and environment variable references. The guided oee init --interactive validates every answer with the same rules.