Synergy Configuration File Format

The synergy server requires configuration. It will try certain pathnames to load the configuration file if you don't specify a path using the --config command line option. synergys --help reports those pathnames.

The configuration file is a plain text file. Use any text editor to create the configuration file. The file is broken into sections and each section has the form: section: name args end Comments are introduced by # and continue to the end of the line. name must be one of the following:

See below for further explanation of each section type. The configuration file is case-sensitive so Section, SECTION, and section are all different and only the last is valid. Screen names are the exception; screen names are case-insensitive.

The file is parsed top to bottom and names cannot be used before they've been defined in the screens or aliases sections. So the links and aliases must appear after the screens and links cannot refer to aliases unless the aliases appear before the links.


args is a list of screen names, one name per line, each followed by a colon. Names are arbitrary strings but they must be unique. The hostname of each computer is recommended. (This is the computer's network name on win32 and the name reported by the program hostname on Unix and OS X. Note that OS X may append .local to the name you gave your computer; e.g. somehost.local.) There must be a screen name for the server and each client. Each screen can specify a number of options. Options have the form name = value and are listed one per line after the screen name.

Example: section: screens moe: larry: halfDuplexCapsLock = true halfDuplexNumLock = true curly: meta = alt end This declares three screens named moe, larry, and curly. Screen larry has half-duplex Caps Lock and Num Lock keys (see below) and screen curly converts the meta modifier key to the alt modifier key.

A screen can have the following options:


args is a list of screen names just like in the screens section except each screen is followed by a list of aliases, one per line, not followed by a colon. An alias is a screen name and must be unique. During screen name lookup each alias is equivalent to the screen name it aliases. So a client can connect using its canonical screen name or any of its aliases.

Example: section: aliases larry: curly: shemp end Screen larry is also known as and can connect as either name. Screen curly is also known as shemp (hey, it's just an example).


args is a list of screen names just like in the screens section except each screen is followed by a list of links, one per line. Each link has the form {left|right|up|down}[<range>] = name[<range>]. A link indicates which screen is adjacent in the given direction.

Each side of a link can specify a range which defines a portion of an edge. A range on the direction is the portion of edge you can leave from while a range on the screen is the portion of edge you'll enter into. Ranges are optional and default to the entire edge. All ranges on a particular direction of a particular screen must not overlap.

A <range> is written as (<start>,<end>). Both start and end are percentages in the range 0 to 100, inclusive. The start must be less than the end. 0 is the left or top of an edge and 100 is the right or bottom.

Example: section: links moe: right = larry up(50,100) = curly(0,50) larry: left = moe up(0,50) = curly(50,100) curly: down(0,50) = moe down(50,100) = larry(0,50) end This indicates that screen larry is to the right of screen moe (so moving the cursor off the right edge of moe would make it appear at the left edge of larry), the left half of curly is above the right half of moe, moe is to the left of larry (edges are not necessarily symmetric so you have to provide both directions), the right half of curly is above the left half of larry, all of moe is below the left half of curly, and the left half of larry is below the right half of curly.

Note that links do not have to be symmetrical; for instance, here the edge between moe and curly maps to different ranges depending on if you're going up or down. In fact links don't have to be bidirectional. You can configure the right of moe to go to larry without a link from the left of larry to moe. It's possible to configure a screen with no outgoing links; the cursor will get stuck on that screen unless you have a hot key configured to switch off of that screen.


args is a list of lines of the form name = value. These set the global options.

Example: section: options heartbeat = 5000 switchDelay = 500 end

You can use the following options:

You can use both the switchDelay and switchDoubleTap options at the same time. Synergy will switch when either requirement is satisfied.

Actions are two lists of individual actions separated by commas. The two lists are separated by a semicolon. Either list can be empty and if the second list is empty then the semicolon is optional. The first list lists actions to take when the condition becomes true (e.g. the hot key or mouse button is pressed) and the second lists actions to take when the condition becomes false (e.g. the hot key or button is released). The condition becoming true is called activation and becoming false is called deactivation. Allowed individual actions are:


Valid key names are:

Additionally, a name of the form \uXXXX where XXXX is a hexadecimal number is interpreted as a unicode character code. Key and modifier names are case-insensitive. Keys that don't exist on the keyboard or in the default keyboard layout will not work.