Thanks for your interest in contributing to Deskflow! We welcome all kinds of contributions — bug reports, feature suggestions, documentation improvements, and code.
Use the keyboard, mouse, or trackpad of one computer to control nearby computers,
and work seamlessly between them.
Check out our [Building] guide
or our general [Contributing] section
Deskflow acts as a software KVM (without video) that allows you to:
- Share keyboard and mouse input across multiple computers
- Synchronize clipboard content between machines
- Work seamlessly across different operating systems (Windows, macOS, Linux, BSD)
## More info
Deskflow software consists of a **server** (primary computer) that shares its input devices and **clients** (secondary computers) that receive and execute the input commands over a TCP network connection.
### Architecture Overview
Deskflow is built with a modular, cross-platform architecture:
│ Server App │◄──────────────────────►│ Client App │
│ │ (Port 24800) │ (Windows) │
│ ┌─────────────┐ │ │ ┌─────────────┐ │
│ │ Screen │ │ │ │ Screen │ │
│ │ Platform │ │ │ │ Platform │ │
│ │ Layer │ │ │ │ Layer │ │
│ └─────────────┘ │ │ └─────────────┘ │
└─────────────────┘ └─────────────────┘
┌───────┐ ┌───────┐
│ Keyb. │ │ Mouse │
└───────┘ └───────┘
┌─────────────────┐
│ Client App │
│ (macOS) │
│ ┌─────────────┐ │
│ │ Screen │ │
│ │ Platform │ │
│ │ Layer │ │
│ └─────────────┘ │
└─────────────────┘
┌─────────────────┐
│ Client App │
│ (Custom) │
│ ┌─────────────┐ │
│ │ Screen │ │
│ │ Platform │ │
│ │ Layer │ │
│ └─────────────┘ │
└─────────────────┘
```
### More info
For more info, see our [Wiki](https://github.com/deskflow/deskflow/wiki).
[Contributing]:contributing.md
[Building]:build.md
Check out our [Building guide](build.md) or our general @ref contributing_guide "Contributing section". We also have a detailed [Protocol Reference](protocol_reference.md).
This document provides a comprehensive reference for the Deskflow network protocol. It is the primary source of information for developers implementing Deskflow clients or extending the protocol.
## Protocol Overview
The Deskflow protocol enables keyboard and mouse sharing between multiple computers over a TCP network connection. The protocol uses two distinct sets of terminology to describe the roles of the computers involved:
- **Network Role (Client/Server)**: This describes the connection architecture.
- **Server**: The machine that listens for incoming TCP connections.
- **Client**: The machine that initiates the TCP connection to the server.
- **Input Control Role (Primary/Secondary)**: This describes the flow of keyboard and mouse events.
- **Primary**: The computer whose keyboard and mouse are currently being used to control other computers.
- **Secondary**: A computer that is being controlled by the Primary's keyboard and mouse.
In a typical setup, the Primary computer (the one whose keyboard and mouse are shared) also acts as the Server. However, the protocol is flexible and allows these roles to be separate. For example, a Primary machine can act as a Client to connect to a Secondary machine that is configured as a Server. This can be useful for navigating restrictive network environments like firewalls.
Throughout the documentation, message direction is often described using the Primary/Secondary roles to clarify the input control flow, while Client/Server roles are used when discussing the underlying network connection.
The protocol operates over a standard TCP connection on port 24800. In protocol versions 1.4 and later, TLS encryption is supported for secure communications.
## Protocol State Machine
The client's connection lifecycle is defined by five primary states:
```
┌──────────────────┐
│ START │
└────────┬─────────┘
│
▼
┌────────┴─────────┐
│ DISCONNECTED │
│ (Initial & │◄───────────────────┐
│ Final State) │ │
└────────┬─────────┘ │
│ │
▼ │
┌──────────────────┐ │
│ CONNECTING │ TCP Failure │
│ (TCP handshake) ├───────────────────►┤
└────────┬─────────┘ │
│ │
TCP Success │ │
│ │
▼ │
┌──────────────────┐ │
│ HANDSHAKE │ Version Mismatch │
│ (Hello/HelloBk) ├───────────────────►┤
└────────┬─────────┘ │
│ │
OK │ │
│ │
▼ │
┌──────────────────┐ │
│ CONNECTED │ CCLOSE (close) │
┌───►│ (Authenticated ├───────────────────►┤
│ │ but inactive) │ │
│ └────────┬─────────┘ │
│ │ │
COUT │ CINN │ │
(Leave) │ (Enter)│ │
│ ▼ │
│ ┌──────────────────┐ │
│ │ ACTIVE │ CCLOSE (close) │
└────┤ (Receiving all ├───────────────────►┘
│ input events) ├◄─────┐
└────────┬─────────┘ │
│ │
▼ │
┌──────────────────┐ │
│ PROCESS EVENT ├──────┘
└──────────────────┘
```
### State Descriptions
1.**Disconnected**: Initial and final state. No connection to @ref Server.
2.**Connecting**: @ref TCPSocket connection attempt in progress.
- Initiating @ref TCPSocket connection.
- On successful TCP connection, moves to the `Handshake` state.
- If TCP connection fails (timeout, RST packet), returns to `Disconnected`.
3.**Handshake**: Protocol version negotiation and authentication.
-@ref Server sends @ref kMsgHello with protocol version information.
-@ref Client responds with @ref kMsgHelloBack including version and screen name.
-@ref Server validates the client's message.
- Success transitions to `Connected`, failure sends @ref kMsgEIncompatible error.
4.**Connected**: Authenticated but not receiving input events.
-@ref Client must respond to @ref kMsgCKeepAlive messages from the @ref Server.
- Receiving @ref kMsgCEnter message transitions to `Active`.
5.**Active**: Receiving and processing input events from @ref Server.
- Receiving @ref kMsgCLeave message transitions back to `Connected`.
- Receiving @ref kMsgCClose message transitions to `Disconnected`.
## Message Categories
The protocol organizes messages into logical categories:
This table lists all protocol messages in alphabetical order. For a typical sequence of messages, see the [Typical Control Flow](#typical-control-flow) section.
| Message | Constant | Category | Direction | Purpose | Constraints | Protocol Version |
| [**DCLP**](@ref kMsgDClipboard) | @ref kMsgDClipboard | Data | Both | Clipboard data | [MsgSize](#constraint-protocol-max-message-length) | 1.0+ |
| [**DDRG**](@ref kMsgDDragInfo) | @ref kMsgDDragInfo | Data | Server→Client | Drag file info | [MsgSize](#constraint-protocol-max-message-length), [ListSize](#constraint-max-list) | 1.5+ |
| [**DFTR**](@ref kMsgDFileTransfer) | @ref kMsgDFileTransfer | Data | Both | File transfer data | [MsgSize](#constraint-protocol-max-message-length) | 1.5+ |
| [**DINF**](@ref kMsgDInfo) | @ref kMsgDInfo | Data | Client→Server | Screen information | [MsgSize](#constraint-protocol-max-message-length) | 1.0+ |
| [**DKDL**](@ref kMsgDKeyDownLang) | @ref kMsgDKeyDownLang | Data | Server→Client | Key down with language | [MsgSize](#constraint-protocol-max-message-length), [KeyMap](#constraint-keymap) | 1.8+ |
| [**DKDN**](@ref kMsgDKeyDown) | @ref kMsgDKeyDown | Data | Server→Client | Key down | [MsgSize](#constraint-protocol-max-message-length), [KeyMap](#constraint-keymap) | 1.1+ |
| [**DKDN**](@ref kMsgDKeyDown1_0) | @ref kMsgDKeyDown1_0 | Data | Server→Client | Key down (legacy) | [MsgSize](#constraint-protocol-max-message-length), [KeyMap](#constraint-keymap) | 1.0 |
Maximum size of the initial Connection Handshake message
Defined in Protocol Limits
<aid="constraint-tls"></a>
### TLS Handshake and Security (Protocol v1.4+)
When encryption is enabled, the protocol follows this sequence:
1. Standard TCP connection established
2. TLS handshake performed over TCP socket
3. Protocol handshake begins only after TLS session is established
- **Implementation Details**:
- The client initiates a standard TCP connection, then the @ref SecureSocket::handleTCPConnected method is called, which begins the TLS handshake
- **Certificate Validation**:
- Client implementations **must** validate the server's certificate
- The reference implementation checks that the public key is RSA or DSA and that the key length is at least 2048 bits
### Key Code and Modifier Mapping
A modifier (modifier mask) represents the state of modifier keys (like Shift, Control, Alt, and Command) on a keyboard. It is a binary code (like 0000 0110) where each bit corresponds to a specific modifier key.
**Key-Up/Key-Down Strategy:**
-<aid="constraint-keymap"></a>Client must use the @ref KeyButton (physical key) to track pressed keys, as the @ref KeyID (virtual key) can change based on modifier state
- This strategy is described in the documentation for @ref kMsgDKeyDown
**Modifier Remapping:**
- The server can command clients to remap modifier keys via the @ref kMsgDSetOptions message
- The client processes the @ref kMsgDSetOptions message and updates the modifier translation table accordingly
## Timing and Synchronization
<aid="constraint-keep-alive"></a>
### Keep-Alive Mechanism (Protocol v1.3+)
**Server-Side Behavior:**
- The server sends kMsgCKeepAlive messages every 3.0 seconds (defined by @ref kKeepAliveRate)
- This timer is implemented in @ref ClientProxy1_3::addHeartbeatTimer in the @ref ClientProxy1_3 class
**Client-Side Behavior:**
- Upon receiving a kMsgCKeepAlive message, the client must immediately send a kMsgCKeepAlive message back
- The client maintains a timeout that is reset each time any message is received
- If no message is received for 9.0 seconds (3 ×@ref kKeepAliveRate), client must disconnect
- This is handled by the @ref ServerProxy::handleKeepAliveAlarm method
<aid="constraint-screen-entry-sync"></a>
### Synchronization on Screen Entry
- The @ref kMsgCEnter (Enter Screen) message includes the current modifier state
- Client must synchronize their local modifier state with this mask
<aid="constraint-handshake-timeout"></a>
### Handshake Timeout
- Server allows **30 seconds** for handshake completion
- If client fails to send valid @ref kMsgHelloBack within this time, connection is closed
- When a new client connects, the server creates a temporary @ref ClientProxyUnknown to handle the version handshake
- A one-shot timer is started for 30 seconds
- If the client fails to respond in time, the @ref protocol_errors function is triggered, the connection is logged as unresponsive, and the socket is closed
## Version Compatibility
| Version | Release Date | Project | Features | Compatibility |
@ -23,6 +23,8 @@ using namespace deskflow::string;
namespacedeskflow::server{
// Protocol options used in configuration files (lowercase).
// Note that @ref kSynergyProtocolName / @ref kBarrierProtocolName use capitalized names.
constautokSynergyProtocolOption="synergy";
constautokBarrierProtocolOption="barrier";
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
laz-001