- Step 1: Installing Synergy
- Step 2: Collecting the Screen Name of each Computer
- Step 3: Setting up the Server
- Step 4: Setting up the Clients
- Step 5: Testing Synergy
- Step 6: Auto-launching a Synergy server or Synergy clients
- Step 7: Tips and Tricks
(W) = Windows instructions
(M) = Macintosh OS X instructions
(U) = Unix-like system (*nix) instructions
To participate in this How-To you will need at least two computers, each with their own monitor (or a laptop with a
screen), one keyboard, one mouse, and a local network connection between the computers. You will eventually need to
know the name of each machine. In some cases the IP address associated with a machine will be required. If you are
planning on running these applications on Mac OS X you may need to use a text editor such as BBEdit (or the free
TextWrangler) if you are not familiar with a command line text editor such as vi.
Synergy works on and between most operating systems; it works with various flavors of Windows, Macintosh OS X.2 and
higher, and unix-like operating systems with X installed. In this How-To we will concentrate on installations that
include Windows XP and Macintosh OS X with a brief smattering of generic *nix tips.
The usual caveats against your computer not functioning after following any of these instructions apply: use at your
own risk. These instructions are provided as a friendly How-To and are not necessarily endorsed by the Synergy
Step 1: Installing Synergy
First, download the synergy package and install it on each machine. The newest version of all the downloads can be
found on Synergy's
sourceforge page. Under the "Binaries" heading the Windows download is an .exe file and the Mac build is an
OSX.PPC.tar.gz file. If you are installing Synergys on a unix-like system from source, choose your compression flavor
of choice (we prefer .gz on linux/bsd) under the "Sources" heading and download the package to compile Synergy
(W) The Windows installation is trivial. Double-click on the SynergyInstaller-1.x.x.exe program. Leave "Start Menu
Shortcuts" selected. Choose and install location (default C:\Program Files\ is just fine). When it's done click
"Close". Launch Synergy (either from C:\Program Files\Synergy or from the Windows start menu). Synergy is now installed
on your machine. Read on for configuration instructions further down.
(M) For Macintosh OS X (X.2 and higher reportedly works, but we've only tested Synergy on X.3/X.4), double click on
the synergy-1.x.x-x.OSX.PPC.tar.gz file to uncompress it. Open the resulting synergy-x.x.x folder. On your computer
create a new folder in your home directory called bin. The home directory is otherwise known as ~/ or more specifically
on mac os x /Users/yourname/ where "yourname" is your login name. Copy the "synergyc" and "synergys" binary files to
the new folder /Users/yourname/bin/. Copy the "synergy.conf" file to your home directory (~/ or /Users/yourname/).
Launch the Mac OS X Terminal application (/Applications/Utilities/Terminal). Type:
(where "yourname" is your login name. Note that there are no spaces in the PATH command.)
If you would like to be able to run Synergy on Mac OS X from this directory we've created without having to retype
the path command every time you launch the terminal, you will have to edit a hidden file. Here is how you can do this
without learning to use the unix command line. Obtain a text editor of some sort (we use BBEdit, but substitute the
text editor of your choice —TextWrangler is the free version of BBEdit for OS X). In BBEdit choose File > Open
Hidden... and open the .bash profile located in your home directory (/Users/yourname/.bashprofile). If it does
not exist, simply click cancel and File > New > Text Document. If the file already exists or if the file is
blank, simply add at the bottom: PATH=$PATH:/Users/yourname/bin/ (where "yourname" is your login name. Once again, note
the lack of spaces.) Now go to File > Save As and choose .bash_profile in your home directory. Important! Before
saving click on "Options" and select "(generic text file)" "None" and "Unix" then click "OK". Click "Save" and then
"Replace" and then "Use ." to save over the original file.
If you are feeling a bit adventurous in OS X and/or have experience with unix commands, add the path line above to
~/.bash_profile using your favorite text editor inside the terminal. We usually add a path to /usr/bin/ and
/usr/local/bin/ while we're at it.
Now if all the stars are aligned, when you launch your OS X terminal and type:
then hit Tab, your shell should auto-complete the word "synergy" at which point it is up to you to choose synergys or
synergyc and OS X will run it.
(U) For Unix-like operating systems (Linux, BSD, et al) after downloading the sources to your directory of choice and
unpacking them, dance the standard *nix three-step:
On FreeBSD5.4 you may simply download and install the port: cd /usr/ports/sysutils/synergy/ make install clean
We chose to save our compiled copies of Synergy in /usr/local/bin/ on our linux based systems; by default on
FreeBSD5.4 they are placed in /usr/X11R6/bin/.
Next comes the fun part, we promise!
Step 2: Collecting the Screen Name of each Computer
Now comes the crucial decision: which computer will be the "server" and which computer(s) will be the "client"(s)?
The easiest way to decide is to pick the computer with your favorite keyboard and mouse attached. If you have a choice
of where to plug your favorite keyboard and mouse, set the computer with the most uptime as the "server" (read: the
computer that is left running the most and isn't mobile).
To prepare for "Step 2: Setting up the Server", you need to collect the "Screen Name" of each client.
(W) On Windows clients this name can be changed at will within the Synergy application interface and does
not necessarily have to be the computer's name. Launch the Synergy application and click on "Advanced..." and enter your
"Screen Name" and click "OK". The example shown below has the "Screen Name" set to "myservername".
(M) On Macintosh this name is most easily found by navigating to System Preferences > Sharing. Find the "Computer
Name". This name plus ".local" on the end is your Synergy "Screen Name". For example the Mac OS X machine with the name
"mycutecomputername" would have a Synergy "Screen Name" of "mycutecomputername.local".
(U) On Unix-like systems the Screen Name is the pre-defined screen name of the computer and is located in your
internet configuration file.
Step 3: Setting up the Server
Once you have chosen which computer will become the server, you must create a Synergy configuration file on that
computer. This configuration file contains the name of the server, the names of each client, and the side of the screen
where the mouse will exit and enter for each computer.
(W) If the Synergy "server" computer is running a flavor of Windows, the configuration file is part of the graphical
user interface included with the download you have already installed. Launch the Synergy application and choose the
"Server" radio button. If you haven't already done so, choose a name for the server computer itself by clicking on
"Advanced...", entering your "Screen Name" and clicking "OK". Then, under the "Screens:" text-box, click on "Add". In
this example we add the computer named "mycutecomputername.local".
In most cases you only have to fill in "Screen Name:" with the exact screen name of each client and the
server that will be sharing the keyboard and mouse. Note that you MUST enter the name of the server in the "Add Screen"
dialog box even though you have just named it in the "Advanced..." section.
Now the names of your clients and the name of your server should appear in the "Screens:" text-box. Select the first
one of the list by clicking on it and decide how it should react with the other computers as far as placement. For
example, we have "1. mycutecomputername.local" selected and have decided that when we move the mouse to the left side
of "mycutecomputername.local"'s screen, it should end up on "myservername". Thus, we choose "myservername" in the
"Left" drop-down menu:
We must also tell Synergy that when we move the mouse out the right side of "myservername" it should end up on
"mycomputername.local". We now have a central "edge" between two monitors defined: myservername on the left, and
mycutecomputername.local on the right.
A simple way to understand the configuration Left/Right/Above/Below is to keep this in mind: When you exit to the
_ of "Screens:", you go to the name in the drop-down menu. Another lovely thing with Synergy is that
you can actually have a wrap-around screen defined: in the example above we could define the layout of "Left:" and
"Right:" to both be set to "myservername" for "1. mycutecomputernamelocal" as well as vice versa. This means that when
I exit "mycutecomputername.local" to the Left OR to the Right, I always end up on "myservername". This can be either
useful or annoying depending on your work style. Personally I like having monitor boundaries where the mouse can not
escape because I set those corners as hot corners for my screen savers with required passwords.
Note: The clients in any of the server set-up situations can be of any type of operating system. Mac and Windows and
Unix-like systems mix in a lovely cocktail of single keyboard/mouse goodness.
(M) Now we will demonstrate how to set up a Mac OS X computer as the server. In BBEdit do File > Open Hidden and
open /Users/yourname/synergy.conf or /Users/yourname/.synergy.conf if you have already edited this file with this
How-To. Now type your server/client configuration as follows:
left = myservername
right = mycutecomputername.local
This example assumes you have two computers with two monitors. The monitor on the left belongs to "myservername" and
the monitor on the right belongs to "mycutecomputername.local". When you move the mouse to the right edge of
"myservername" it enters on the left edge of "mycutecomputername.local". Replace "mycutecomputername.local" and
"myservername" with the "Screen Name" of each computer. Note that you have to include the server computer as well in
the list. Now in BBEdit go to File > Save As... and save the file as .synergy.conf in /Users/yourname/ (your home
directory). Important! Before saving click on "Options" and select "(generic text file)" "None" and "Unix" then click
"OK". Click "Save" and then "Replace" and then "Use ." to save over the original file.
Another example of a configuration file is a situation where we have two monitors next to each other on a shelf and
below the left hand monitor we have a laptop:
left = leftcomputer.local
right = rightcomputer
down = laptop
up = leftcomputer.local
Note that the computer monitor on the left in the example above belongs to a Mac OS X machine because it has a name
that ends in ".local". Also note that any of these computers can be a server, simply save the .synergy.conf file on the
server computer's home directory.
Step 4: Setting up the Clients
(W) To set up a Windows client machine, launch the Synergy application and choose the "Client" radio button. First
name the client if you have not already done so by clicking on "Advanced...", entering your "Screen Name" and clicking
"OK". Next enter the IP address of the Synergy server machine and click "Start". For example if the Synergy server
machine has an IP address of 192.168.1.3 your Synergy window would look like this:
A dialog box will pop up: "Synergy was successfully started. Use the task manager or tray icon to terminate it."
Click "OK" in this box. Minimize the synergy status window. When you want to quit synergy on this client, close the
synergy status window or alternatively log your user out of Windows.
(M/U) To set up a client on a Macintosh or a Unix-like system, you don't have to do anything special besides
installing (see Step 1). To launch a client see Step 5.
Step 5: Testing Synergy
Launch the Synergy server:
(W)For Windows based servers simply start the Synergy application. (M/U)For Mac OS X and *nix computers start a
terminal and type: synergys then press the return/enter key. Synergys runs in the background by default. If you get the
error: command not found, go back to the installation instructions in Step 1.
Next launch the Synergy clients:
(W)On Windows this is once again achieved by launching the Synergy application.
(M/U)Mac OS X or *nix based clients are launched by opening a terminal and typing:
where the network address is the IP address of your Synergy server. For example, if your Synergy server has an IP
address of 192.168.1.3 you would type this in the terminal to launch the client:
and press the return/enter key.
Your mouse should now be able to travel across your monitors/screens. If it does, congratulations! For
trouble-shooting help see Step 7.
Step 6: Auto-launching a Synergy server or Synergy clients
You may end up adoring Synergy. This usually means you don't want to have to launch the server and then each of the
clients every time you log-in, reboot, or move a computer. In this section we'll show you how to auto-launch on Windows
and Mac OS X. A brief coverage for unix-like systems is at the end of this section.
(W)For Windows launch the Synergy program. Click on the "Automatic Startup: Configure..." button. By default Synergys
is set up to auto-launch when your user name logs in. If this is the case the last sentence of this window will read:
"Synergy is configured to start automatically when you log in." If you would like to manually launch Synergy instead,
click on "When you Log In: Uninstall" and then "Close". This method works for both Synergy servers and Synergy
(M)The way to auto-launch for Mac OS X is slightly convoluted. We will try to be as clear as possible. Keep in mind
this example is to auto-launch a Synergy server. For the client auto-launch example see the next part of this section.
There are two main steps to configure Synergy to auto-launch on Mac OS X. The first is to add the Terminal application
to your Login Items. Go to System Preferences > Accounts > Login Items. Click on the "+" symbol and choose
Applications > Utilities > Terminal and click on "Add". Now "Terminal" should have been added to the list of
Applications in Login Items. Check the "Hide" checkbox to the left of the Terminal icon in the list to hide the
auto-launched terminal and quit your System Preferences. (NOTE: Login Items may have a different name in OS X.3/X.2 but
should work similarly.)
Secondly we will set up the Terminal to auto-launch synergys (Synergy server). Launch the Terminal (Applications
> Utilities > Terminal) and open a new window (File > New Shell). Next go to File > Save As and name the
file launchsynergy after navigating to the following directory: /Users/yourname/Library/Application Support/Terminal/
Check the "Open this file when Terminal starts up" checkbox. (*) Choose the "Execute this command (specify
complete path)" radio button and enter the path:
Then delete the leading "b". (We have to add and then delete a leading letter because when you start with a leading
slash OS X.4 forces us to change the "Where" save-to path instead of the "Execute this command" path. This is a bug.)
Check the "Execute command in a shell" checkbox (if you do not check this, no application will be launched, this is
another bug in OS X) and then click "Save":
To verify that everything works, quit the Terminal application then relaunch it. You should see something like:
Last login: Mon Aug 8 18:57:29 on ttyp1
Welcome to Darwin!
mycutecomputername:~ yourname$ /Users/yourname/bin/synergys
This means that synergys has been launched and is running in the background. You can verify this by typing in the
and hitting the return/enter key. You should see synergys listed near the top of the "Command" column. To quit "top"
type the letter "q". To make synergys stop at any time after launching, in a terminal type:
and hit the enter/return key or log-out of your user name or shutdown the computer.
To auto-launch synergyc (Synergy client) on Mac OS X follow the instructions above until the star (***) then:
Choose the "Execute this command (specify complete path)" radio button and enter the path:
Then delete the leading "b" and instead of 192.168.1.2 use the IP address of your Synergy server. Check the "Execute
command in a shell" checkbox and then click "Save":
To verify that the synergyc is working, quit the Terminal then relaunch it. You should see something like:
Last login: Mon Aug 8 18:57:29 on ttyp1
Welcome to Darwin!
mycutecomputername:~ yourname$ /Users/yourname/bin/synergyc 192.168.1.2
This means that synergyc has been launched and is running in the background. You can verify this by typing in the
terminal: top and hitting the return/enter key. You should see synergyc listed near the top of the "Command" column. To
quit "top" type the letter "q". To make synergyc stop at any time after launching, in a terminal type: killall synergyc
and hit the enter/return key or log-out of your user name or shutdown the computer.
(U)The auto-launch for unix-like systems can be achieved in many ways. The simplest way is to include "synergys" or
"synergyc " in the script that launches your window manager and auto-launches other
applications. For example, on FreeBSD5.4, our fluxbox window manager is launched by the config file
/usr/X11R6/lib/X11/xinit/xinitrc the end of which is:
# start some programs
synergyc 192.168.1.2 &
aterm -geometry 93x21+5+5
# this script launches the synergy client when the x window session is launched
Step 7: Tips and Tricks
Static IP addresses are your friends. Try to get a fixed IP address assigned to each machine. This is practically
necessary for auto-launching clients and servers.
If you have a screen "edge" you have defined that doesn't seem to allow the mouse to "pass through" it, make sure
you have accurately defined the IP address of the server when you launched the client. Next make sure your "Screen
Names" in the server set up are all correctly spelled. Thirdly make sure you can ping the server from the client and
the client from the server. If not, perhaps you have a network cable unplugged or have misconfigured your network
If you have a screen "edge" that behaves backwards or differently than the way you thought it would, simply replace
Left with Right or Above with Below in the configuration file (see Step 3).
Synergy may create vulnerabilities on your computer. If you are concerned about this read the
Synergy Network Security Guide on Synergy's homepage.
It is handy to keep the extra old keyboards and mice on hand when having trouble auto-launching (see Step 6) and
when initially setting up Synergy. Some operating systems may not appreciate having only a USB keyboard plugged in when
booting in certain modes and may actually require a PS2 keyboard plugged in to boot. An easy trick if you are ready to
ditch your keyboard on a finicky computer is to plug one of those cheap green PS2 male to USB A female adapters in the
PS2 port in the computer to trick it into thinking there is a keyboard plugged in. These little adapters often come
free with most USB keyboards to allow backward compatibility with older machines and to free up USB ports. Ask your
friends, they may have an extra one of these adapters laying around.
Another note about extra keyboards: If you have an operating system that requires you to log in, you will need a
keyboard physically attached to the computer to type your name and password. The instructions for auto-launching (Step
6) are only to auto-launch on a per-user basis. If you would like to launch a Synergy client or Synergy server when the
computer boots, please see the Autostart Guide on
If you have a keyboard that behaves weirdly with respect to capslock/numlock/ctrl/alt, etc. see the "A screen can
have the following options:" section here. These
settings can also be set in the graphical Windows Synergy application window under the "Add" dialog under "Options" and
Enjoy your glorious multi-monitor multi-platform single-keyboard+mouse party!