Cloud Management
Deploy and manage cloud-hosted nodes from the control plane.
Overview
Cloud Management is ControlBird's cloud-based control plane, reached at app.controlbird.io. It is where you sign up, and provision, monitor, and manage your cloud-hosted ControlBird Nodes through their full lifecycle: from creation through start/stop and deletion. Every long-running task is tracked so the UI can show real-time progress.
Use Cloud Management when you want ControlBird hosted for you rather than running it on your own hardware. ControlBird Cloud is free for personal use, and every node is the same full ControlBird as the self-hosted Community edition. Every node is reached at its own address, <subdomain>.controlbird.io. Cloud nodes do not peer with one another or synchronize data between themselves: each one is an independent instance with its own copy of your configuration and data.
Prefer a guided tutorial?
New to this? Follow the Deploy a Node walkthrough for a step-by-step tour, then come back here for the full reference.
Key Concepts
| Concept | What it does |
|---|---|
| Node | A single running ControlBird instance that you own, with its own permanent URL. It shows its lifecycle status, the ControlBird release it runs, and its CPU and memory usage. Each user can own up to three nodes; an administrator can raise the limit. |
| Node Operation | A long-running task (create, delete, start, stop, factory restore) with a status and progress percentage that the UI shows for live updates. |
Node lifecycle
A node moves through a well-defined set of statuses shown in the control plane. Creation begins in provisioning and moves to running once the node comes online.
Common Patterns
- Name nodes by purpose or location. Pick a node name for its job (Production, Staging) or its place (Home, Office). Nodes are managed independently; they are not networked together.
- Check a node's status and usage. Each node's page shows its status, the ControlBird release it runs, and the CPU and memory each of its services uses, refreshed every minute. The dashboard shows each node's totals. A new node becomes running once it has been placed and comes online; its usage reads "measuring" until the first sample arrives.
- Track operations for progress. Start, stop, delete, and factory-restore actions run in the background. The control plane shows their status and progress rather than blocking on an immediate result.
- Platform updates are applied for you. Every cloud node runs the current ControlBird release; there is no per-node version to pick or upgrade.
Tunnel client extension
A tunnel lets a cloud node reach a service on your local network, such as an MQTT broker or an audio server, without opening a port on your router. The local side opens an outbound HTTPS connection to the cloud node, and the service appears there on a local port that only that node can use.
When a ControlBird node already runs on your site, install the Tunnel Client extension on it instead of running the standalone tunnel container:
- On the cloud node, open the API Keys window and create a key with tunnel access that lists the port the service will use there.
- On the local node, install Tunnel Client from the extension marketplace.
- In Explorer, create a Tunnel Connection in the Tunnels folder under Integrations. Enter the cloud node's address, the key, the port to publish, and the local service's host and port.
The connection opens on its own and its status shows Connected. Editing a setting reconnects it with the new values, and turning Enabled off closes it. When the cloud node refuses the key or the port, the status shows Refused with the reason, and the tunnel keeps retrying. Only Owner and Administrator can create and change tunnels.
Troubleshooting & Limitations
Three nodes per account
Each user can own up to three nodes. Creating another returns a "node limit reached" error until you delete one or an administrator raises your limit. Nodes do not share a network with one another; each node is independent.
Tunnel keys belong to one node
A key for the tunnel adapter is created in the node's own API Keys window. It works only on the node that issued it and only for the ports it lists, so a key for one node cannot reach another. Disable or delete a key in that window to revoke it.
- Subdomains are globally unique. A node's subdomain is unique across all users, and is assigned once at creation: renaming a node later does not change it.
- Node names are case-insensitive in DNS. Names are lowercased and sanitized to alphanumeric plus hyphens (1-63 characters, no leading or trailing hyphens), so
My-Nodeandmy-nodecollide. - Eventual consistency on operations. An operation can be marked succeeded while the node status briefly lags behind, so keep watching until both agree.
- Deletion is gradual. A node first moves to a deleting state, then is removed in the background and marked deleted.
- Short-lived sessions. Sign-in sessions expire, so you re-authenticate per session. Each node also keeps its own sign-in state.