Link Client & API Integration
Relevant source files
The following files were used as context for generating this wiki page:
The Link Client & API Integration system manages the secure connection between a Muse gadget and the Muse backend infrastructure. This system enables gadgets to register with the Muse platform, receive and execute remote commands, and stream data such as user messages or voice notes. It functions across both Linux and ESP32 platforms, providing a unified protocol for communication.
Gadgets utilize this integration to establish encrypted Noise sessions via WebSockets, allowing the Muse app to control the device and move files. The integration handles identity management, token rotation, and communication with specific Virtual Machines (VMs) assigned to a user.
Sources: linux/README.md:21-24, linux/AGENTS.md:27-38
Connection Architecture
The connection process follows a specific lifecycle starting from identity verification to establishing a persistent secure tunnel. Gadgets connect to the backend using the WebSocket protocol, specifically upgrading to a Noise XX handshake for end-to-end encryption.
Connection Sequence
The following diagram illustrates the sequence of establishing a secure session with the Muse VM.
Key Connection Components
| Component | Responsibility |
|---|---|
link_client.py | Manages the Noise session, handshake, and /link-control channel. |
muse_api.py | Handles RESTful interactions like fetch_vms and token refreshing. |
identity.py | Manages persistent node IDs (e.g., homelink-xxxxxx) and BLE names. |
/v1/noise | The endpoint for initial Noise upgrade. |
/link-control | The primary channel for command invocation (link.invoke). |
Sources: linux/AGENTS.md:27-38, linux/AGENTS.md:109-110
Communication Protocols
The integration supports several distinct communication pathways for control and data streaming.
Control Channel (/link-control)
Once a Noise session is established, the gadget opens a POST /link-control request and leaves the body open. This bi-directional channel carries JSON messages prefixed with a little-endian u32 length.
- link.register: Sent by the device to identify itself (platform: "linux", device_family: "homehub").
- link.invoke: Sent by Muse to trigger a command on the device.
- link.result: Sent by the device to return command output.
- link.unpaired: Indicates the Muse has removed the device.
Sources: linux/AGENTS.md:116-121
User Message Streaming (/chat/stream)
Messages sent from the device to the user interface (e.g., status updates or sensor alerts) travel via separate POST /chat/stream requests.
- Modality: Typically "text".
- Size Limit: The VM accepts a maximum of 256 KB per message.
- Session ID: Used to target specific side chats.
Sources: linux/AGENTS.md:122-127
API Integration Details
The gadget interacts with the Muse API for authentication and resource discovery.
Identity and Authentication
Identity is persistent and stored locally (e.g., /var/lib/musegadget/identity.json on Linux). Authentication involves:
- SDK Token: A unique token retrieved from
gadgets.muse.aiused during initial pairing. - Bearer Tokens: Short-lived tokens retrieved via the API to authorize WebSocket connections.
- Token Rotation: The system automatically refreshes tokens to maintain connectivity.
Sources: linux/AGENTS.md:36-38, linux/AGENTS.md:92-93, linux/README.md:37-38
REST Endpoints
| Endpoint | Method | Purpose |
|---|---|---|
/v1/fetch_vms | GET | Retrieves details of available VMs and connection hosts. |
/hatch/refresh | POST | Rotates or refreshes device authentication tokens. |
Sources: linux/AGENTS.md:35-37, linux/AGENTS.md:105-108
Platform Specifics (ESP32 vs. Linux)
While the protocols are shared, the implementation details vary between the ESP32 firmware and the Linux SDK.
ESP32 Link Operations
On the ESP32, Muse runs inside "Home Link." The firmware provides a set of operations for the UI to interact with the Link layer.
Key operations available to the ESP32 UI include:
req_open: Opens a request on Link's session for boards without enough RAM for their own.hatch_vm: Fills VM details and retrieves heap-allocated tokens.wifi_status: Reports current connection state.
Sources: esp32/components/muse/muse_link.h:55-66
Linux Implementation
The Linux SDK uses a Python package (musegadget) that handles reconnection loops and token rotation within a systemd service. It leverages websockets and cryptography libraries to manage the Noise protocol.
Sources: linux/AGENTS.md:27-38, linux/pyproject.toml:27-28
Conclusion
The Link Client and API Integration provides the critical bridge between physical gadgets and the cloud backend. By standardizing on Noise XX encrypted sessions and specific JSON-based control protocols, the SDK ensures that gadgets remain secure and responsive to user commands while maintaining a persistent presence in the Muse ecosystem.