Skip to content

Remote nodes

By default a run executes on the machine you started it on. A remote node is another machine — a VM you control — that accepts runs over the node-agent protocol. Your laptop stays the control plane; the node does the work.

mini-ork run code-fix ./kickoff.md --placement remote --env staging

Topology

flowchart LR
    L[laptop<br/>mini-ork CLI<br/>state.db + run dirs] -->|HTTP + bearer token| N[node agent<br/>VM]
    N --> W[workspace]
    W --> R[recipe DAG]
    R -->|events, artifacts| L

The laptop always owns the database, the run directory and the verdict. The node owns execution: it receives a dispatch, runs the node, and returns output and artifacts.

This direction is deliberate. mini-ork is a laptop-first control plane, not a distributed scheduler: there is no central server to stand up, and losing a node loses at most the work in flight on it.

Two ways to address a node

Put named nodes in config/nodes.yaml:

default_node: staging
nodes:
  staging:
    url: https://node-staging.internal:7091
    token_env: MO_NODE_TOKEN_STAGING
    max_sessions: 2
  heavy:
    url: https://node-heavy.internal:7091
    token_env: MO_NODE_TOKEN_HEAVY
    max_sessions: 1
Field Meaning
url Base URL of the node agent
token_env Name of the environment variable holding the bearer token
max_sessions Concurrent sessions the node accepts before new dispatches are refused
default_node The profile used when --env names no node

Then select one by profile name:

mini-ork run code-fix ./kickoff.md --placement remote --env staging

The token itself is read from the environment — nodes.yaml never contains it. That keeps the registry safe to commit.

One-off node

For a single node you do not want to register:

MO_NODE_URL=https://node.internal:7091 \
MO_NODE_TOKEN=… \
mini-ork run code-fix ./kickoff.md --placement remote --env adhoc

MO_NODE_URL / MO_NODE_TOKEN are the direct override. Prefer the registry for anything you will do twice.

Placement is explicit

Variable Values Default
MO_PLACEMENT local, remote local
MO_NODE_ENV a node profile name —

--placement and --env map onto those two variables. --placement remote requires --env: there is no implicit "some node". This is deliberate — picking a node is a decision about whose machine gets code and whose credentials are used, and a default would make that decision silently.

A run's placement is recorded with the run, so the board shows where each run executed.

Engine bundle upload

The node needs a working mini-ork checkout. When the engine tree you are running from differs from what the node has, the control plane uploads the engine bundle before the first dispatch.

Variable Default Effect
MO_REMOTE_ALLOW_DIRTY_ENGINE unset (off) 1 allows uploading an engine tree with uncommitted changes

Leave it unset in normal use: uploading a dirty engine makes the run's behaviour depend on your working tree, which is exactly the sort of ambiguity the verdict system exists to remove. Set it only while developing the engine itself.

What runs remotely, and what does not

Component Location
Planner, implementer, reviewer, reflector models Node (dispatched by the agent)
Workspace and git operations for the run Node
Verification gates Node
state.db, run directory, verdict Laptop
Board, IDE, automations Laptop
Secrets (provider keys) Passed per dispatch; see below

Secrets on a node

The node must be able to reach the provider lanes the run uses. Two patterns:

  1. Node-local environment — the agent on the node reads provider keys from its own environment. Simple, and the right default for a VM you own.
  2. Vault-backed delivery — the control plane resolves named secrets from the vault and passes them with the dispatch. Use this when you do not want keys sitting in the node's shell profile.

Either way, do not put keys in nodes.yaml, in a kickoff, or in a command line you will paste into a shell history. See Vault and Security model.

Health and capacity

  • A node advertises max_sessions; a dispatch that would exceed it is refused rather than queued indefinitely.
  • Node reachability is checked before a run starts. An unreachable node fails early, not after a partial plan.
  • If a node dies mid-run, the run fails at the node boundary. Recovery is mini-ork board retry once the node is back — the laptop still holds every completed node's output.

Building a node

A node is a machine with the mini-ork engine installed and the node agent exposed over HTTP(S):

  1. Install mini-ork the normal way (install.sh or from source).
  2. Give the agent a bearer token and bind it to a private interface or a TLS endpoint — never a public plaintext port.
  3. Point config/nodes.yaml at it with token_env naming the token variable.
  4. Verify with a small in-place run before scheduling anything heavier.

For provisioning nodes on demand rather than keeping VMs around, see Cloud sandboxes.