Encrypted device connections
Follow identity checks, pairing and encrypted communication between devices.
In this topic
Secure Channel protects the inner requests exchanged by supported Mellow peers. Pairing establishes the expected host identity; the channel verifies that identity, creates session keys, and carries requests and responses in encrypted frames. Access-grant checks still occur inside that connection.
Use this page to understand a device connection or diagnose a protocol error. It is not necessary to manually create sessions during normal Mac or Mobile pairing.
Know which connection is protected
Peer traffic from supported Mellow clients uses the channel over either a local network or a relay route. A Cloud workspace OAuth connection, a model provider API, and an ordinary HTTPS client are separate transports with their own authentication and privacy boundaries.
Do not infer that every request made by Mellow is end-to-end encrypted merely because one paired-device route is. When a host calls a remote model or tool service, that service receives the request needed to perform its work.
What the protocol checks
| Layer | Purpose |
|---|---|
| Pinned agent identity | Verify that the responding host is the expected peer |
| Ephemeral key exchange | Establish fresh session key material |
| Authenticated encryption | Detect changes to encrypted requests and replies |
| Request sequence | Reject an already-consumed envelope |
| Authenticated stream finish | Distinguish a completed response from a cut connection |
| Inner request authorization | Enforce access-key scope, expiry, revocation, and route restrictions |
Mellow's implementation uses X25519 for ephemeral agreement, HKDF-SHA256 for key derivation, identity signatures for the handshake, and ChaCha20-Poly1305 for authenticated encryption. Keep both endpoints current so their protocol implementations remain compatible.
Session and request flow
- The client starts a session through
POST /secure/session, identifying the target agent and sending fresh handshake material. - The host returns its session material and a signed transcript.
- The client verifies the signature against the expected agent identity.
- Each request is encoded inside
POST /secure/callwith the session identifier and sequence number. - The host decrypts the inner method, path, authorization, and body, then applies normal request gates.
- Encrypted response frames return to the client, ending with an authenticated finish frame.
The public relay carries the outer frames. Traffic timing, approximate size, and routing metadata are still visible to intermediaries. The channel also cannot protect content after an authorized endpoint decrypts it or prevent a permitted tool from sending information to its own service.
Retry without repeating an action
A session can expire or disappear when the host restarts. Establish a new session when required. Do not resend an already-consumed encrypted envelope: its sequence is deliberately rejected.
If a connection fails after an operation may have committed, inspect the operation or conversation status before issuing a new task. Replay protection on envelopes is not a promise that two separately authorized requests can never perform the same action twice.
Error reference
| Response | Interpretation | Recovery |
|---|---|---|
426 secure_channel_required | Remote execution attempted without the required channel | Update the client or use the peer protocol |
401 secure_session_unknown | The host no longer recognizes the session | Establish a fresh session |
409 secure_replay | That sequence was already consumed | Do not retry the same envelope |
400 secure_malformed | Invalid encrypted-request structure | Correct the client request |
An identity mismatch is different from session expiry. Verify the host before re-pairing instead of accepting an unexpected identity automatically.
Local clients and stored data
Same-machine clients can use permitted loopback routes under the local server's policy. Relay-origin traffic is not treated as trusted local traffic simply because it arrives at a loopback socket on the host.
Secure Channel protects transit between peers. Storage settings govern local databases and backups. Identity and grants govern who may request work. All three layers matter independently.
Continue exploring · Models, voice and mediaChoosing and managing models →Install compatible models, select a conversation model and diagnose loading or memory issues.