oz0-node run
Run the node in the foreground.
For: Operators and developers looking up a command.
Run the node in the foreground. It installs uv, Python and the runtime bundle if they are missing, opens the control stream to the edge, and runs the runtime on the task queues the edge assigns, behind a local proxy that holds the node's certificate. Certificates are renewed in place; a blocked node stops its runtime and waits.
On SIGTERM, a service stop or a binary update it drains first: it takes no new work and waits up to --stop-grace for what runs to end, then stops; a second signal stops it at once.
Usage
oz0-node run [flags]
Flags
| Flag | Type | Default | Description |
|---|---|---|---|
--activity-slots | int | how many activities (model requests, tool calls, sessions) the runtime runs at once on each task queue, half while the edge says the node is degraded; 0 for the default: 100 a queue, and on a shared pool 100 for each of its plugins up to 50 per logical CPU (or set OZ0_ACTIVITY_SLOTS) | |
--models | string | <data-dir>/models.yaml | the model servers this node runs or reaches on loopback, for local/<model> agents |
--offline | bool | never download uv, Python, the runtime's packages or Node.js from the internet, only from the edge's toolchain (or set OZ0_NODE_OFFLINE=1) | |
--plugin-sandbox | string | strict | on a node with tier 1, how each installed plugin's MCP servers and hooks run: strict runs them in a sandbox of their own that reaches only the hosts on the egress allowlist, as a session does, a tool that says sandbox: host or sandbox: own does not start, and a plugin's build runs none of its code; auto keeps the host's network, for a plugin that must reach what its manifest does not list yet or that diagnoses the node's own network, and then only its own code holds it to the list (bubblewrap nodes; on macOS auto sandboxes only private candidates); off sandboxes only private candidates, for a node whose plugins cannot run in a sandbox at all |
--plugin-sandbox-exempt | stringArray | under --plugin-sandbox strict, run this plugin's sandbox: host and sandbox: own tools outside the sandbox, as the node's user, for a tool that must see the node itself, and run its build's code as that user too, for a plugin that needs a build backend or a dependency with no wheel: PLUGIN, or PLUGIN@COMMIT to allow that version alone, with its whole commit or digest as the node's finding gives it, since a name also covers what the tenant installs under it next (repeatable). Only this flag allows it, so that neither a plugin nor an edge can; a private candidate is never exempt | |
--remote-sandbox | string | a remote-sandbox backend for tools with isolation remote, as NAME=COMMAND, such as e2b='oz0-sandbox-e2b --api-key-file FILE' (or set OZ0_REMOTE_SANDBOX); the tenant's admins must allow remote sandboxes too | |
--runtime-bundle | dir | download the edge's, which make dist builds | runtime bundle dir |
--sandbox | string | auto | sandbox tier 1 for harness sessions and outside-started jobs: auto uses bubblewrap or Seatbelt when the machine has it, off runs tier 0; psec, on Windows 11, runs a self-test of its process security environment at start and reports tier 1 when it passes (no harness sessions run in it yet) |
--stop-grace | duration | 10m0s | how long a stopping node waits for the work it runs to end, after it stops taking new work, at most 1h; the runtime's own 30 s stop is inside it (or set OZ0_STOP_GRACE) |
Inherited flags
| Flag | Type | Default | Description |
|---|---|---|---|
--data-dir | string | ~/.local/share/orchestrator-zero-node | where the node keeps its identity, uv, Python, runtimes and state |
--log-level | string | info | log level: debug, info, warn or error |
See all oz0-node commands and the global flags.