A node is a machine you deploy and manage from ORC8R. Each node has a set amount of CPU, memory, and disk, runs an operating system, and can have apps installed on it. This page explains the states a node moves through, what the agent is, and the everyday actions you can take.
Where to find your nodes
Click Nodes in the top navigation. This is your main dashboard. Nodes are grouped into cards called pools (see Pools), and each card lists the individual nodes inside it along with a colored status dot and a state label.
You can narrow the list down using the controls at the top of the page:
- Filter by Project... shows only nodes from a chosen project.
- Search pool or node name... finds a node or pool by name.
- The Pools and Nodes dropdowns filter by status (for example, show only online nodes).
What a node's state means
A node moves through several states from the moment you request it to the moment it is gone. The colored dot next to each node and the small label tell you where it is. Hover over the dot to see a short description.
| State you see | What it means |
|---|---|
| baking | The node is preparing a reusable pool image (see Pools). |
| starting | The node has been created and is booting up, waiting for its agent to connect. |
| online | The node is up and reachable. This is the healthy, running state. |
| offline | The node is not currently reachable. |
| upgrading | The node's agent is restarting onto a new version. The node comes back online by itself. |
| terminating | The node is being shut down and removed. |
| destroying | The node's underlying machine is being deleted. |
| destroy-blocked | Deleting the machine failed and ORC8R is retrying. |
| ended | The node has been fully removed. |
You do not need to memorise these. In everyday use you mostly care about three: a node is online when it is ready, offline if something is wrong, and moves through terminating and ended when you remove it.
A node building a reusable pool image is the one exception: it shows what the build is doing rather than what the machine is doing, because the two do not match. It reads baking while the machine is provisioned and booted, installing while its agent installs the apps the image is to carry (or offline if that agent drops mid-install), snapshotting while it hands its disk over (the machine shuts down here — nothing is wrong, and the node is not being removed), and publishing while the finished image is stored for the pool. A builder that genuinely fails or is removed reads terminating like any other node.
Operators also see a special zone pool listing the ORC8R server members themselves. Their dot works the same way — green while the member serves the cluster, red when it is unreachable — but server members are not managed machines: they cannot be terminated from this page.
What the agent is
The agent is a small program ORC8R installs on every node; it connects the machine back to ORC8R so the node can report its status and receive apps. When a node shows starting, it is waiting for its agent to connect; once the agent is up the node becomes online.
The node's page names the agent's version and platform under its title, for example Agent 0.5.1 · linux/x86_64, followed by the upgrade under way or the last one that finished.
Agent upgrades
When an ORC8R server starts serving a newer agent release, the zone's agents upgrade themselves. Each node is given its turn at some point within the rollout window, so a large zone does not restart all at once. On its turn the agent downloads the new version and checks that it runs, then waits until it may go ahead. It then stops the apps that run under it (service apps keep running), switches to the new version and restarts in place. While it restarts the node reads upgrading, and the page says how far it has got: upgrading to 0.5.2: staged, stopping-apps, restarting, reconnected. If the new version fails to start or reconnect, the agent goes back to the version it had. Each step and the outcome also appear in the node's log.
The first node of each platform goes alone, and the others follow once it succeeds. At most one node per pool restarts at a time.
Operators set the rollout on the zone's Agents tab:
- Automatic upgrades: when off, upgrades already under way finish and no new ones start.
- Rollout window (seconds): the span new orders are spread over after a release appears.
- Upgrades at once: how many agents in the zone may restart for an upgrade at the same time.
- Hold a platform after this many failures: see below.
- Reconnect deadline (seconds): how long a restarting agent has to come back before the server stops waiting for it.
A blank field uses the default the form names. The tab also shows the release this server serves for each platform, the zone's current release, how many online nodes run each agent version, and the upgrades in flight. If the server showing the tab serves an older release than the zone's, the tab says the rollout is paused: the rollout runs only while the server leading the zone serves the zone's release.
When upgrades to one release keep failing on one platform, the rollout holds that platform: no new upgrade starts there. A hold happens once the failures reach the threshold and are no fewer than the successes. A download that fails, or an agent that does not reconnect in time, does not count towards it. Held platforms are listed on the Agents tab with a Resume button, which lets the rollout try the platform again with its counts back at zero.
An operator can upgrade one node straight away with Upgrade agent now on the node's page, beside its agent version. It shows when the node is online, has reported its version, and the zone's release is newer and has an archive for the node's platform. It skips the window, the zone-wide limit, the first-node wait and any hold, but the agent still checks it has the room and the tools for the upgrade, and it is refused while another node in the same pool is restarting for an upgrade. The page returns to the node's log, where the upgrade is narrated. The same action is POST /api/nodes/{node}/agent-upgrade. Both need the upgrade_agents permission, which only owners of the system organization hold.
Creating nodes
You do not create nodes one at a time. Instead you make a request that defines a pool, and ORC8R creates the nodes for you. To start, click New Request on the Nodes page (or Request first node if you have none yet). The full walkthrough is in the Quickstart, and pools are explained in Pools.
Everyday actions
Open a node's details
Click a node's name to open its detail view. Where your ORC8R prices nodes, the header shows what this node costs per hour; open it to see the rates behind that number — one line per thing charged for, and the dates the price changed if it ever did. A node with no price shows none, which means it is not priced rather than that it is free.
There are four tabs:
- Logs shows the node's recent activity. This is the first place to look if a node is not behaving as expected. The zone's operators (members of the system organization, who hold the
read_node_debug_logspermission) also get a Debug toggle that adds the detailed lines — addresses, ports and raw errors — which everyone else does not see. - Terminal opens a command-line session to the node directly in your browser. Use it for troubleshooting only. Any changes you make by hand are lost if the node is rebuilt, so do not rely on it for permanent configuration.
- Restore points lists the App data copies this node captured — the points it left behind, which stay listed here after the node has ended, each with a download link and a Pull control that shows the
orc pullcommand for it. See Restore points. - Audit lists the history of events for that node.
Terminate or rebuild a node
Each node row has an action in its Actions column:
- For most pools, this rebuilds the node: ORC8R replaces it with a fresh one so the pool keeps the size you asked for.
- For self-hosted or one-off pools, this terminates the node: it is shut down and removed for good.
Terminating is only available once a node has reached a stable state (online, offline, or terminating).
Either way, the node's apps are stopped before it is destroyed. Each app gets its own wind-down: a chance to finish work in flight and release anything it registered elsewhere, then a signal, then a short grace period before it is killed. The node shows as terminating while that runs, and asking again changes nothing — the request is already in hand. A separate force action is there for a node that will not wind down: it stops waiting on the apps and destroys the node right away.
Connect a self-hosted node
If a pool accepts your own machines (a self-hosted pool), its card shows a Connect button. Clicking it gives you a one-time install command to run on the machine you want to add. See Providers for how self-hosted pools work.
Remove the agent from a Windows node
On a node that is part of a project network, the Windows agent owns the machine's firewall and its internal DNS: every inbound port is closed except the ones the project uses, Remote Desktop included, and the rules stay in force when the agent stops. So take the agent off a Windows machine with its uninstaller, not by deleting files. In an elevated PowerShell, run the installer script with -Uninstall. It stops the service, removes the agent's firewall rules and DNS settings, and then removes the service.
If the service is already gone, or the uninstaller reports an error, stop the service and run the agent's recovery command yourself. It removes the same firewall rules and DNS settings:
Stop-Service orc-agent
& "C:\Program Files\orc-agent\orc-agent\orc-agent.exe" --mesh-uninstall --data-dir "C:\ProgramData\orc-agent"
The command prints what it removed, and exits with an error if the firewall rules could not be removed. If the agent binary is gone and the machine is still closed, use the fallback: disable the service and restart the machine. Then install the agent again and run the recovery command.
Set-Service orc-agent -StartupType Disabled
Restart-Computer
You can reach a sealed machine through your cloud provider's console, which does not go through the network.
Export your node list
Click Export on the Nodes page to download a nodes.csv file of the nodes currently shown, including any filters you have applied. This is handy for reporting or sharing a snapshot.
Related pages
- Pools — how nodes are grouped and scaled.
- Projects — the workspace your pools live in.
- Quickstart — request your first node step by step.