cloud-path

CloudPath is a self-hosted IoT control platform that can run locally or be deployed to the public internet. Its goal is to create a general-purpose control plane for "device access, status monitoring, and remote control," rather than being a dedicated upper-computer for a specific development board. Open-sourced under the MIT license, the project consists of three main parts: the single-binary central service cloudpath-server, the cloudpath-edge gateway running on each computer or site, and the cloudpath command-line tool for the plugin Registry control plane. Technically, the backend is written in Go and the frontend in React. WebUI build artifacts are embedded into the server, and the database uses SQLite in WAL mode, allowing cross-compilation to Linux or arm64 without CGO. Authority Division The central service is the sole authority for desired states, tenants, and auditing, handling RBAC, tokens, rate limiting, retention periods, the desired state of plugin directories and running instances, as well as operation dispatch and receipt settlement. The gateway is the sole authority for the observed state, saving a snapshot of the last successfully applied state and handling device supervision, backoff restarts, and offline event buffering. It continues to operate after network disconnection and only applies the final snapshot upon reconnection without replaying intermediate side effects. Device identity is determined by a triplet of tenant, gateway, and device; the online transmission key is a combination of edge_id and device_id. Under an account session, the real-time link from gateway to server to browser uses WebSockets, while REST handles historical queries and management operations. Plugin System The project distinguishes three types of plugins: Drivers run by default on the gateway side, responsible for device discovery, connection, protocol parsing, capability mapping, and device actions; Applications run on the central service side, responsible for business objects, bindings, rules, tasks, and domain APIs; Connectors are planned to run on either the gateway or central service for notifications and data egress via MQTT, Webhooks, etc., and are currently in the target state. The core does not write code for any specific hardware; a new device is simply a Driver plugin. Reference drivers like stcb and several application plugins are released in independent repositories, providing Go plugin templates, example applications, and E2E test scaffolding from binary to host. Before installation, plugins are validated for Manifest, compatibility range, Release assets, and digests, with versions, digests, and sources recorded in a lock file. Quick Start After installing Go, Node, pnpm, and optionally task, use task setup to pull dependencies and task build to generate two binaries. The server listens on 127.0.0.1:8080 by default and provides a /healthz health check. Without hardware, the built-in demo adapter can be used to verify device online status, operation execution, and disconnection reconnection. For real serial devices, install and enable the corresponding Driver plugin, then enable plugin_host in the local edge.yaml and fill in the serial port and adapter. After the first administrator account is installed, the service immediately enters account mode, requiring credentials for everything except health checks, static resources, and authentication interfaces. Management Console After logging in, users can access the overview, device list and details, operation records (events), applications and plugins with instance details, gateway list and details, and settings. Administrators have additional pages for members, permissions, and access tokens. The operation panel on the device details page generates buttons based on the whitelist declared by the adapter; commands can also be dispatched directly via API to query event streams and gateway online status. Operation states are pending, sent, ok, failed, and timeout. Operations without receipts for a long time are marked as timed out by a background cleanup task; events and final-state operations are retained for 30 days by default. Security Design The README divides the exposure surface into three levels: L0 standalone, L1 intranet or reverse proxy, and L2 public internet, warning against putting L0 configurations directly on the public internet. There are two credential modes: shared service tokens for compatibility, and account mode providing session cookie login, three-level roles (admin, operator, viewer), and tenant tokens prefixed with cp_. The scope is a subset of read, write, admin, and edge; plain text is returned only once during creation, while only SHA-256 and short prefixes are stored in the database. Secrets appear in server configurations and audits as handles in the form of secret://name; plain text is parsed locally by the provider on the target gateway. Plugins must explicitly declare permissions in the manifest, and the server neither saves nor forwards plain text. Additionally, there are operation whitelists, parameter length and character limits, request body limits, WebSocket read limits, SPA path traversal protection, operation and login rate limiting, and a set of security response headers. Deployment and Multi-Gateway Access The official guide provides public internet deployment steps that do not rely on containers: first, perform architecture assertions on build artifacts (the release matrix includes Linux arm64), then run the service using systemd units with a dedicated non-root account, place secrets in 0600 environment files, and finally use nginx as a reverse proxy to provide HTTPS and WSS, with separate upgrade headers and longer read timeouts configured for WebSockets. It is noted that authentication is handled by the product itself, and the reverse proxy layer remains open. Container and Compose formats are also available, but the host architecture must match the image. Connecting multiple computers to one server is a common use case: administrators create tenant tokens with edge scope for each computer and provide the WSS endpoint, token, and agreed edge_id to the user. Users download the corresponding binary for their platform from Releases, verify it via checksums, fill in the local configuration file, and run it. The gateway features exponential backoff reconnection, and offline events enter a bounded buffer to be replayed upon reconnection. Devices, events, operations, and instances across different tenants are invisible to each other, and the disconnection of one gateway does not affect others. Testing and Release Testing covers Go unit tests, race detection, frontend frozen installation and type checking, plugin template workflows, and aggregated gate commands. Releases are triggered by version tags, performing a six-platform matrix build and generating a unified checksums file. The repository also provides script gates for public boundary auditing, Markdown link checking, and workflow structure checking. Current Boundaries The README clearly distinguishes between the current state and the target state: Connector and notification runtimes, MQTT and Modbus access, remote OTA, time-series aggregation, central key management, distributed quotas, and multi-server setups are not yet implemented. Tenant token sessions only exist for REST, not for real-time browser channels. E2E testing for a single external driver driving multiple real boards, covering hot-plugging and operation receipts, is also incomplete; therefore, multi-board links are not considered verified until protocol and real-board evidence are completed. The project's stated principle is "unimplemented capabilities are not written as current status."