Skip to main content

Creating and using text config files

Updated

Written for Synergy 3 (v3.7.2) and Synergy 1 (v1.21.4), checked 3 October 2026.

Most people never need a text config file: you can set up Synergy 1 and Synergy 3 entirely in the app. Write one when you need something the app's layout editor can't make, such as a screen wrap, or to run Synergy 1 from the command line: How can I run Synergy 1 from the command line?

Start from your current setup

  • Synergy 1: on the server, click the Export server configuration button (the save icon next to Configure Server) and save the file.
  • Synergy 3: turn on Config file at the bottom of the settings sidebar. The Text configuration file box shows the configuration made from your current layout, ready to edit.

Use your config file

Synergy 1

  1. On the server, click Configure Server.
  2. Go to the Config file tab.
  3. Tick Use a server config file.
  4. Click the folder button next to Config file path.
  5. Choose your file.
  6. Click OK. If Synergy 1 is running, it restarts with the file.

Synergy 3

On the primary computer (the one whose keyboard and mouse you share):

  1. At the bottom of the settings sidebar, turn on Config file. The Text configuration file page opens and the other settings are greyed out.
  2. Edit the configuration in the box, or click Browse for config file to load a .conf file. Revert undoes your edits.
  3. Check that This computer shows the name this computer has in the file.
  4. Turn on Primary (server). This computer's addresses appear under This computer's IPs.
  5. Click Save and start server.

On each other computer:

  1. Turn on Config file.
  2. Check that This computer shows the name this computer has in the file.
  3. Turn off Primary (server).
  4. Enter the primary computer's IP address in Server IP.
  5. Click Save and connect to server.

The page also has Command arguments, for extra options if you need them, and on Windows Run as system to allow UAC interaction; for that, see: How to make Synergy work with UAC prompts

If something on the page is wrong, a message explains what to fix before Synergy 3 saves.

Keep Config file turned on for as long as you want to use the file. To go back to the Screen layout, turn Config file off; your layout takes over again.

Reasons for creating your own config file

  • To run Synergy 1 from the command line, you need a text config file for the server.
  • If you need to access a feature that is not available in the app.
  • Gives you more control; the app cannot create advanced configuration such as non-reciprocal connections. An example of a non-reciprocal connection would be that if you go right from screen A you get to screen B, but if you then go left from screen B you get to screen C rather than back to screen A as you would in a reciprocal connection.
  • You can use a version control system
  • Easier to share configs with people
  • You can have multiple config files (for example if using a laptop in multiple places)

File format

The configuration file is a plain text file, and you can use any text editor to create it. The file is broken into sections and each section has the generic form:

section: name
    args
end

Note: comments start with # and continue to the end of the line.

Section names must be one of the following:

  • screens
  • aliases
  • links
  • options

See below for further explanation of each section type. Note that the configuration file is case-sensitive so "Section", "SECTION", and "section" are all different and only "section" is valid.

Screen names are the exception, they 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.

Screens

The "args" section is a list of screen names, one name per line, each followed by a colon.

Names are arbitrary strings but they must be unique, and can't contain spaces. Use the name each computer has in Synergy 1 or Synergy 3, which is usually the computer's name; on macOS it may end in .local (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.

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.

Screen options

A screen can have the following options:

halfDuplexCapsLock = {true|false}

This computer has a Caps Lock key that doesn't report a press and a release event when the user presses it but instead reports a press event when it's turned on and a release event when it's turned off. If Caps Lock acts strangely on all screens then you may need to set this option to true on the server screen. If it acts strangely on one screen then that screen may need the option set to true.

halfDuplexNumLock = {true|false}

This is identical to halfDuplexCapsLock except it applies to the Num Lock key.

halfDuplexScrollLock = {true|false}

This is identical to halfDuplexCapsLock except it applies to the Scroll Lock key. Note that, by default, Scroll Lock keeps the cursor on the current screen. That is, when Scroll Lock is toggled on, the cursor is locked to the screen that it's currently on. You can use that to prevent accidental switching. You can also configure other hot keys to do that; see lockCursorToScreen.

switchCorners = <corners>

See more information about switchCorners under Options (detailed below).

switchCornerSize = N

See more information about switchCorners under Options (detailed below).

xtestIsXineramaUnaware = {true|false}

This option works around a bug in the XTest extension when used in combination with Xinerama. It affects older X11 clients only. Not all versions of the XTest extension are aware of the Xinerama extension. As a result, they do not move the mouse correctly when using multiple Xinerama screens. This option is currently true by default. If you know your XTest extension is Xinerama aware then set this option to false.

preserveFocus = {true|false}

If set to true, windows on this screen keep their focus when you switch to another screen, instead of losing it. It takes effect on Linux computers running X11.

shift = {shift|ctrl|alt|altgr|meta|super|none}
ctrl = {shift|ctrl|alt|altgr|meta|super|none}
alt = {shift|ctrl|alt|altgr|meta|super|none}
altgr = {shift|ctrl|alt|altgr|meta|super|none}
meta = {shift|ctrl|alt|altgr|meta|super|none}
super = {shift|ctrl|alt|altgr|meta|super|none}

Map a modifier key pressed on the server's keyboard to a different modifier on this client. This option only has an effect on a client screen; it's accepted and ignored on the server screen. For instance, you can map the Shift key to Shift (the default), Ctrl, Alt, AltGr, Meta, Super, or nothing. Normally, you wouldn't remap Shift or Ctrl. You might, however, have an X11 server with Meta bound to the Alt keys. To use this server effectively with a Windows client, which doesn't use Meta but uses Alt extensively, you'll want the Windows client to map Meta to Alt (using meta = alt).

Aliases

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:
        larry.stooges.com
    curly:
        shemp
end

Screen larry is also known as larry.stooges.com and can connect as either name. Screen curly is also known as shemp.

Links

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.

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.

Editing links helps with layouts that aren't symmetrical. For examples, see: Multiple monitor and custom monitor positioning support

Options

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

section: options
    heartbeat = 5000
    switchDelay = 500
end

List of options

heartbeat = N

The server will expect each client to send a message no less than every N milliseconds. If no message arrives from a client within 3N milliseconds the server forces that client to disconnect. If the server fails to detect clients disconnecting while the server is sleeping or vice versa, try using this option.

switchCorners = <corners>

The cursor won't switch screens when it reaches the edge of the screen if it's in a listed corner. The size of all corners is given by the switchCornerSize option. Corners are specified by a list using the following names:

none: no corners
top-left: the top left corner
top-right: the top right corner
bottom-left: the bottom left corner
bottom-right: the bottom right corner
left: top and bottom left corners
right: top and bottom right corners
top: left and right top corners
bottom: left and right bottom corners
all: all corners

The first name in the list is one of the above names and defines the initial set of corners. Subsequent names are prefixed with + or - to add the corner to or remove the corner from the set, respectively. For example: all -left +top-left starts with all corners, removes the left corners (top and bottom) then adds the top-left back in, resulting in the top-left, bottom-left and bottom-right corners.

switchCornerSize = N

Sets the size of all corners in pixels. The cursor must be within N pixels of the corner to be considered to be in the corner.

switchDelay = N

The cursor won't switch screens when it reaches the edge of a screen unless it stays on the edge for N milliseconds. This helps prevent unintentional switching when working near the edge of a screen.

switchDoubleTap = N

The cursor won't switch screens when it reaches the edge of a screen unless it's moved away from the edge and then back to the edge within N milliseconds. With the option you have to quickly tap the edge twice to switch. This helps prevent unintentional switching when working near the edge of a screen.

switchNeedsShift = {true|false}
switchNeedsControl = {true|false}
switchNeedsAlt = {true|false}

If set to true, the cursor only switches screens at an edge while you hold down Shift, Ctrl or Alt respectively.

relativeMouseMoves = {true|false}

If set to true then secondary screens move the mouse using relative rather than absolute mouse moves when and only when the cursor is locked to the screen (by Scroll Lock or a configured hot key). This is intended to make games work better. If set to false or not set then all mouse moves are absolute.

defaultLockToScreenState = {true|false}

If set to true, the cursor starts out locked to the server's screen when the server starts.

disableLockToScreen = {true|false}

If set to true, the cursor can't be locked to a screen, so Scroll Lock and lock hotkeys have no effect.

clipboardSharing = {true|false}

If set to true then clipboard sharing will be enabled and the clipboardSharingSize setting will be used. If set to false, then clipboard sharing will be disabled and the clipboardSharingSize setting will be ignored.

clipboardSharingSize = N

The server will send a maximum of N kilobytes of clipboard data to another computer when the mouse transitions to that computer.

win32KeepForeground = {true|false}

If set to false (the default), a Windows server takes the foreground focus when you switch to a client (putting all other windows in the background), so other apps can't interfere with reading your keyboard and mouse. If set to true, it leaves the current foreground window in the foreground. For when to change this, see: My game is minimized when I leave the screen

keystroke(key) = actions

Binds the modifier and key combination key to the given actions. key is an optional list of modifiers (shift, control, alt, altgr, meta or super) optionally followed by a character or a key name, all separated by + (plus signs). You must have either modifiers or a character/key name or both. See below for valid key names and actions. Keyboard hot keys are handled while the cursor is on the primary screen and secondary screens. Separate actions can be assigned to press and release.

mousebutton(button) = actions

Binds the modifier and mouse button combination button to the given actions. button is an optional list of modifiers (shift, control, alt, altgr, meta or super) followed by a button number. The primary button (the left button for right handed users) is button 1, the middle button is 2, etc. Actions can be found below.

Additional notes:

Mouse button actions are not handled while the cursor is on the primary screen. You cannot use these to perform an action while on the primary screen. Separate actions can be assigned to press and release.

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

Actions (for keystroke and mousebutton)

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:

keystroke(key[,screens])
keyDown(key[,screens])
keyUp(key[,screens])

Synthesizes the modifiers and key given in key which has the same form as described in the keystroke option. If given, screens lists the screen or screens to direct the event to, regardless of the active screen. If not given then the event is directed to the active screen only. keyDown synthesizes a key press and keyUp synthesizes a key release. keystroke synthesizes a key press on activation and a release on deactivation and is equivalent to a keyDown on activation and keyUp on deactivation. screens is either * (asterisk) to indicate all screens or a : (colon) separated list of screen names. (Note that the screen name must have already been encountered in the configuration file so you'll probably want to put actions at the bottom of the file.)

mousebutton(button)
mouseDown(button)
mouseUp(button)

Synthesizes the modifiers and mouse button given in button which has the same form as described in the mousebutton option. mouseDown synthesizes a mouse press and mouseUp synthesizes a mouse release. mousebutton synthesizes a mouse press on activation and a release on deactivation and is equivalent to a mouseDown on activation and mouseUp on deactivation.

lockCursorToScreen(mode)

Locks the cursor to or unlocks the cursor from the active screen. mode can be off to unlock the cursor, on to lock the cursor, or toggle to toggle the current state. The default is toggle. If the configuration has no lockCursorToScreen action and Scroll Lock is not used as a hot key then Scroll Lock toggles cursor locking. For more on locking, see: How to lock the cursor to a computer?

switchToScreen(screen)

Jump to screen with name or alias screen.

switchInDirection(dir)

Switch to the screen in the direction dir, which may be one of left, right, up or down.

switchToNextScreen

Switch to the next screen in the configuration.

keyboardBroadcast(mode[,screens])

Turns sending your typing to several screens at once on, off or toggles it (mode is on, off or toggle; the default is toggle). screens is a : (colon) separated list of screen names; if it's left out, typing goes to all screens.

restartServer

Restarts the server.

Key names

Key names are helpful to assign keys that might not necessarily be on your keyboard, or when you've customized a key.

Valid key names are:

AltGr Alt_L Alt_R AppMail AppMedia AppUser1 AppUser2 AudioDown AudioMute AudioNext
AudioPlay AudioPrev AudioStop AudioUp BackSpace Begin Break Cancel CapsLock Clear
Control_L Control_R Delete Down Eject End Escape Execute F1 to F35 Find Help Henkan
Home Hyper_L Hyper_R Insert KP_0 to KP_9 KP_Add KP_Begin KP_Decimal KP_Delete
KP_Divide KP_Down KP_End KP_Enter KP_Equal KP_F1 KP_F2 KP_F3 KP_F4 KP_Home KP_Insert
KP_Left KP_Multiply KP_PageDown KP_PageUp KP_Right KP_Separator KP_Space KP_Subtract
KP_Tab KP_Up Left LeftTab Linefeed Menu Meta_L Meta_R NumLock PageDown PageUp Pause
Print Redo Return Right ScrollLock Select ShiftLock Shift_L Shift_R Sleep Super_L
Super_R SysReq Tab Undo Up WWWBack WWWFavorites WWWForward WWWHome WWWRefresh
WWWSearch WWWStop Zenkaku Space Exclaim DoubleQuote Number Dollar Percent Ampersand
Apostrophe ParenthesisL ParenthesisR Asterisk Plus Comma Minus Period Slash Colon
Semicolon Less Equal Greater Question At BracketL Backslash BracketR Circumflex
Underscore Grave BraceL Bar BraceR Tilde

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.

Example text config file

# sample configuration file
#
# comments begin with the # character and continue to the end of
# line. comments may appear anywhere the syntax permits.
# +-------+ +--------+ +---------+
# |Laptop | |Desktop1| |iMac     |
# |       | |        | |         |
# +-------+ +--------+ +---------+

section: screens
    # three hosts named: Laptop, Desktop1, and iMac
    # These are the nice names of the hosts to make it easy to write the config file
    # The aliases section below contain the "actual" names of the hosts (their hostnames)
    Laptop:
    Desktop1:
    iMac:
end

section: links
    # iMac is to the right of Desktop1
    # Laptop is to the left of Desktop1
    Desktop1:
        right(0,100) = iMac # the numbers in parentheses indicate the percentage of the screen's edge to be considered active for switching
        left = Laptop

    # Desktop1 is to the right of Laptop
    Laptop:
        right = Desktop1

    # Desktop1 is to the left of iMac
    iMac:
        left = Desktop1
end

section: aliases
    # The "real" name of iMac is John-Smiths-iMac-3.local.
    # If we wanted we could remove this alias and instead use John-Smiths-iMac-3.local everywhere iMac is above.
    # Hopefully it should be easy to see why using an alias is nicer
    iMac:
        John-Smiths-iMac-3.local
end

Additional options

Focus preservation

To let windows on a Linux (X11) client keep focus when you switch away from it, add preserveFocus to that client in the screens section:

section: screens
    client1:
        preserveFocus = true # Don't drop focus when switching screens
end

Cursor wrapping

The text config allows screens to be wrapped around. For example, with two machines (a server and a client), the mouse can go off the right of the server onto the left side of the client, then off the right side of the client back onto the left side of server. This config also uses Ctrl+Super+(left arrow/right arrow) to switch between machines on keypress.

section: screens
    syn-serv:
    syn-cli:
end

section: links
    syn-serv:
        left = syn-cli # "wrapping" arrangement
        right = syn-cli # "normal" arrangement
    syn-cli:
        left = syn-serv # "normal"
        right = syn-serv # "wrapping"
end

section: options
    keystroke(control+super+right) = switchInDirection(right) # Switch screens on keypress
    keystroke(control+super+left) = switchInDirection(left)
end

For the full steps, see: Creating a screen wrapping configuration

Tips

Synergy 1 and Synergy 3 both build a text config file like this behind the scenes from the layout you make in the app.

Related to

Related articles