Running a program
oel run checks, builds and runs a program in one step, on the machine you are working on.
Usage
oel run
oel run <path>
oel run <path> --run-id <id>
oel run <path> --placement <record.json> --serving-run <run>
oel run --pairs <dir>
oel run --json
| Argument or option | Meaning |
|---|---|
[path] | The project folder. Without a path, the project in the current folder. |
--run-id <id> | The identifier of the run, in place of a generated one. See Naming a run. |
--pairs <dir> | A folder of pairs written by oel compile --pairs, in place of a project. See Running without the source. |
--placement <record.json> | Place some of the project's edges away from this process. See Placing edges on other machines. |
--serving-run <run> | With a placement: the run that every call to a network peer you started yourself carries. |
--json | Diagnostics and reports from the command in machine-readable form. |
What it does
oel run goes through the same steps as oel build, for the machine you are working on:
- check and compile the project;
- compute and verify the complete reference map, starting at
main; - build the native program, named after the application, then start it.
A shortcut never skips a step: a program that oel run starts has passed exactly the checks a build applies. If any step fails, nothing runs, and the diagnostics point at your source.
The program starts at main in main.oel, which carries the application's name, such as main support(). When a main without a result type finishes, the program exits successfully; a main that declares an i64 result exits with the value it returns.
A program that declares functions in other languages builds them with your toolchains, as oel build does, and runs them with their runtimes on the machine you work on.
Packages at startup
Nothing downloads when the program starts. oel run uses only the packages already installed and pinned by your lock files, and a missing package is reported before anything runs, with the command that installs it. Your lock file pins the exact versions you built with, so a run repeats, even offline.
Time and token reports
Time and token usage is reported by default. For a program started from the command line, the report is a summary on standard error, so the program's own output on standard output stays unchanged for pipes and scripts.
You can turn off each field without disabling the limits behind it: all reporting at once, time or tokens alone, or single token counts. Reporting, logs and replay describes the report and its settings.
Agents and configuration
An agent that the program runs gets its own run ID and budget, and its configuration is locked into a snapshot for that run. Agents, nodes and edges and Configuration describe both.
Naming a run
Every run of an application that calls a workflow has an identifier. By default oel run makes one from the process, the time and a counter. --run-id names it instead:
oel run --run-id nightly-2026-10-23
An identifier has 1 to 128 characters, each a letter, a digit or one of _ . : / -, and it starts with a letter, a digit or _. Any other name is refused before anything runs.
Running without the source
oel run --pairs starts a program from the folder that oel compile --pairs wrote, with no source present:
oel run --pairs build/pairs
It links the folder as oel build --pairs does, checking every pair first, and starts the result. When the program calls functions in other languages, its summary ends with a foreign: line that counts the calls, their time and their failures.
Placing edges on other machines
A project whose agents communicate through edges can place some of them away from the process that runs the program. This applies to an application whose main calls a workflow. A placement record names, for each edge, where it is served, and oel run takes it with --placement:
oel run --placement placement.json
- An edge placed as a process is served by a child process that
oel runstarts. - An edge placed on the network is called at the address the record names, where a peer serves it.
- Every other instance runs in the program itself.
Each placed call adds a line to standard error, such as oel edge: <instance> replied, and the three outcomes that are not a reply: refused with a status, unavailable after the stated number of attempts, and effect unknown.
A peer you start yourself
You start a network peer with the same command line tool, before the program:
oel --edge-serve ... --transport network --tenant local --run support-run [--many]
The ... stands for the project, the placement record and the edge the peer serves. A peer serves one run for one tenant, and it compares the run of every call to its own before it reads the call. A program that oel run starts gives each call a run of its own that a peer started earlier cannot know, so you name the run on both sides: the peer with --run, and the program with --serving-run.
oel run --placement placement.json --serving-run support-run
Every call the program places on an operator-run network peer then carries support-run, and a peer started by oel run itself, or a process edge, keeps the identity of each call. A program that presents another run, or none, is refused before any payload is read. The name is an identity the peer and the program agree on, not a secret; the tenant, interface, deadline and capacity checks still apply to every call. The name follows the rule for --run-id.
- One call, or many. A peer admits one call. With
--manyit admits the next one after each completed call, so it serves the successive calls of its run, one connection at a time. A peer is bounded by a deadline, 60 seconds after it starts unless you set another. - Events. An edge that does not reply, an event or a fire-and-forget edge, is acknowledged by the peer, which runs the served node to the end for each call and keeps its output. The peer prints one line for each call it enters,
oel edge <edge>: entered call <n>. - A peer that stops. The calls are delivered at least once. If a peer is killed while it handles a call, the program delivers again under the same idempotency key, and a replacement peer of the same run enters the call once and answers a repeat of the key from its own memory. The effect may therefore run twice but never zero times; delivery is not exactly once.
Many subagents
A program started with oel run can fan out to 128 subagents at once, all of them running together. The command line sets these bounds for itself; other Hosts keep their smaller ones:
| Bound | Value |
|---|---|
| Subagents one run admits | 256 |
| Nesting depth | 256 levels |
| Subagents one agent starts at the same time | 128 |
| Requests waiting | 256 |
| Logical memory budget of the run | 512 MiB |
The memory budget is a limit the run is accounted against, not a measurement of the machine.
An agent that starts N children at the same time has to declare room for them: a depth limit of at least N plus the levels it needs, and queue, step and CPU limits for N children. Each live child reserves its share from the agent that started it, and a refusal names the limit that decided it. Subagents describes spawning, refusals and the budget a subagent draws on.
Build or run
Use oel run while you work. Use oel build when you need a file to deploy or copy to another machine, or a program for another target: oel run always builds for the machine it runs on.
Related
- A first program:
oel runin a small project. - Running tests: the project's tests, without a network or a model account.