Skip to main content

Running from the command line

Updated

Written for Synergy 1 (v1.22.2 and v1.20.4) and Synergy 3 (v3.8.2 and v3.6.3), checked 13 October 2026.

Running Synergy 1 or Synergy 3 from the command line is useful in enterprise environments where you want to configure the software for an end user through files. It is for more advanced users.

How you run it depends on your version:

  • Newer versions, where the core reads its settings from a settings file:
    • Synergy 3 (v3.7 and later)
    • Synergy 1 (v1.21 and later)
  • Older versions, where every setting goes on the command line:
    • Synergy 3 (v3.6 and earlier)
    • Synergy 1 (v1.20 and earlier)

Requirements

  1. Synergy 1 or Synergy 3 installed on each computer: Start here: Install and configure
  2. Permission to run commands
  3. A text config file for the server: Creating and using text config files

Newer versions: a settings file

Write a settings file

The core (synergy-core) takes the mode on the command line and reads everything else from a settings file. Create a plain text file for each computer.

Server (replace the name and path with your own):

[core]
computerName=desk-pc

[server]
externalConfig=true
externalConfigFile=/path/to/synergy-server.conf

Client (replace the name and the server's IP address with your own):

[core]
computerName=laptop

[client]
remoteHost=192.168.1.10

Each computerName must match that computer's name in the server's config file. The connection uses port 24800 unless you add port= under [core] on both computers.

To use one network address, add interface= under [core] with that address. On the server, it's the only address the server listens on, so interface=127.0.0.1 accepts connections from the same computer only, such as through an SSH tunnel. On a client, it's the address the client connects from. Leave it out to use every address the computer has.

[core]
computerName=desk-pc
interface=192.168.1.10

It's the same setting as:

The simplest way to get every other setting right (encryption, logging) is to set the app up first, then copy its settings file to a folder of your own and edit the copy. The file, and the folder it's in:

  • Synergy 3: the settings file is synergy-core.conf. On the server, copy synergy.conf beside it too: that's the text config file Synergy 3 made from your layout, so point externalConfigFile at your copy. Synergy 3 rewrites both originals each time it starts the core. They're in this folder:

    Operating system Folder
    Windows C:\ProgramData\Synergy\config
    macOS ~/Library/Preferences/Synergy
    Linux ~/.config/Synergy

  • Synergy 1: the settings file is Synergy.conf. It's in this folder:

    Operating system Folder
    Windows %APPDATA%\Synergy
    macOS ~/Library/Synergy
    Linux ~/.config/Synergy

Stop the app's own core

Only one core can run at a time, so stop the one the app runs first:

  • Synergy 3: click the Synergy 3 icon in the system tray (the menu bar on macOS), then choose Pause. It stays paused until you choose Resume in the same menu, which hands sharing back to Synergy 3.
  • Synergy 1: quit the Synergy 1 app.

Run the core

Move (cd) into the installation directory:

Operating system Command
Windows 
cd "C:\Program Files\Synergy"
macOS 
cd /Applications/Synergy.app/Contents/MacOS/
Linux (Synergy 3) 
cd /opt/Synergy
Linux (Synergy 1) 
cd /usr/bin

Then run the core with the path to your settings file:

Mode Command
Server 
synergy-core server --settings [path to settings file]
Client 
synergy-core client --settings [path to settings file]

On macOS and Linux, start each command with ./ (./synergy-core). [path to settings file] is unique to your setup, and is entered without square brackets ([]).

Command line options

Run synergy-core --help to see them. They are:

synergy-core server|client [options]

-s, --settings <file>   use this settings file
--new-instance          skip the check for a running instance
-h, --help              display help
-v, --version           display version information

The newer core has no --address, --name or other option for a single setting: those go in the settings file, such as interface= and port=.

In Synergy 3, the Command arguments box on the External config page is saved but isn't passed to the core, so options typed there have no effect; use a settings file instead.

Older versions: every setting on the command line

Run the server and client with every setting on the command line. The programs are:

  • Synergy 3: synergy-core server and synergy-core client.
  • Synergy 1: synergy-server and synergy-client. Versions older than v1.17.1 call them synergys and synergyc.

Stop the app's own core

  • Synergy 3: click the Synergy 3 icon in the system tray (the menu bar on macOS), then choose Stop. Changing a setting in Synergy 3 starts its core again, so leave its settings alone while yours runs. To hand sharing back, stop your core and choose Start in the same menu.
  • Synergy 1: quit the Synergy 1 app.

Run the server or client

Move (cd) into the installation directory, the same as for newer versions: Run the core

Server:

  • Synergy 3: 
    synergy-core server -f --name [computer name] --config [path to config file]
  • Synergy 1: 
    synergy-server -f --name [computer name] --config [path to config file]

Client:

  • Synergy 3: 
    synergy-core client -f --name [computer name] [server IP address]
  • Synergy 1: 
    synergy-client -f --name [computer name] [server IP address]

On macOS and Linux, start each command with ./. Each [computer name] must match that computer's name in the server's config file. Enter each value without square brackets ([]).

-f keeps the server or client running in the terminal, where you can read its log. Leave it out to run it in the background.

The connection uses port 24800. To use another, add --address :[port] on the server, and put :[port] after the server's IP address on each client (192.168.1.10:24900).

Encrypt the connection with TLS

Connect each client from the app once first, so it trusts the server's certificate. Then add --enable-crypto on the server and on each client, plus:

  • Synergy 3:
    • Server: --tls-cert [path to certificate]. Synergy 3's own certificate is synergyCert.pem, in its settings folder: Write a settings file
    • Client: --profile-dir [folder], the folder holding the servers this computer trusts: C:\ProgramData\Synergy on Windows, and its settings folder on macOS and Linux.
  • Synergy 1: nothing more. The server uses the certificate the app created; to use another, add --tls-cert [path to certificate].

Command line options

Run the server or client with --help to see them all. The ones most setups use are:

-c, --config <file>      use this server config file (server only)
-n, --name <name>        use this name instead of the computer's name
-a, --address <address>  listen on this address and port (server), or
                         connect from this network interface (client)
-f, --no-daemon          run in the foreground
-d, --debug <level>      log level: FATAL, ERROR, WARNING, NOTE, INFO,
                         DEBUG, DEBUG1 or DEBUG2
-l, --log <file>         write the log to this file
--enable-crypto          encrypt the connection with TLS
--tls-cert <file>        use this TLS certificate
-h, --help               display help
--version                display version information

Control Synergy 1 or Synergy 3 from a script?

A script can write the settings file and the server's text config file, then run the core with them, as above. The config file can also bind hotkeys to actions such as switching to a computer: Creating and using text config files

Synergy 1 and Synergy 3 have no API for controlling a session while it runs. If you'd like one, tell us: Contacting our support team

Related to

Related articles