Nodes Overview
A node in Miabi is a Docker host that runs your workloads. Out of the box, Miabi manages the local Docker Engine on the machine where the control plane runs — no extra setup required. As you grow, you can attach remote Docker hosts as additional nodes and let Miabi schedule applications, databases, and services across all of them.
Local vs remote nodes
| Local node | Remote node | |
|---|---|---|
| Where it runs | The control-plane host itself | A separate VPS, dedicated server, or homelab box |
| Setup | Automatic | Install the node agent with a join token |
| Connectivity | Direct to the local Docker socket | Outbound WebSocket tunnel from the node |
| Inbound ports | None | None — the agent dials out |
The local node is always present and is the default scheduling target. Remote nodes appear in the same list once their agent connects, and Miabi treats them as first-class scheduling targets thereafter.
How scheduling works
When you deploy an application, Miabi places its containers on an eligible node. Placement considers node availability, resource headroom, and any pinning or labels you've configured. Persistent volumes and databases are bound to the node where they live, so stateful workloads stay put unless you explicitly migrate them.
Because remote nodes connect over an outbound tunnel, a node behind NAT or a firewall works without port-forwarding. The control plane never needs to reach into the node.
Single-node default vs cluster mode
By design, the plain single-node experience stays trivial. With one or more nodes running standalone Docker, Miabi deploys plain containers and routes traffic to them — nothing to configure.
When you want orchestration across multiple hosts — encrypted overlay networking, service-based deployments, and rescheduling — you can opt into cluster mode, which Miabi builds on auto-detected Docker Swarm. Cluster mode is entirely optional; standalone nodes remain fully supported.
Managing nodes
Node management is a platform-admin responsibility (Owner or Admin at the platform level). See Platform Administration for who can add, remove, and configure nodes, and the Architecture page for how nodes fit into Miabi's overall design.