How to connect from anywhere?

The ButConnect Situation

The most basic scenario for using ButConnect is a person (the “client”) in need of computer support, while another person (the “agent”) might provide that support but is not close to the first one and therefore cannot help directly.

 ... but connect anyway!

In that situation, both the client and the agent could launch ButConnect in the corresponding way — in client and agent mode.
After the client has communicated the credentials to the agent, the agent can access the client's computer and thus help remotely.

Launching ButConnect

Currently, ButConnect has a text based user interface to be started on the console:

... and then select the mode of operation and follow the instructions that appear on your screen.

However, if you don't want to specify any command line arguments, you can just launch it in its interactive mode with a double‑click — you will be prompted for any necessary information.
(Note: It might be necessary to create a ‘starter’ on Linux, macOS or other systems in order to launch ButConnect by clicking.)

All modes can be controlled interactively, from the command line or by using environment variables.

Interactive Mode

If you just launch the ButConnect executable without any command line argument, it will run interactively and the user will be prompted for any necessary information. Please follow the instructions that appear on your screen.

Select the Mode of Operation

You can cycle forward (or backward) through the list of available modes, config files or pre-configured connections by pressing (Shift–)[Tab] and select the appropriate item by pressing the [Return] key.

In this basic scenario, the client simply presses [Return] to confirm the already preset client mode and then communicates the on-screen credentials to the agent, who in turn presses [A] followed by [Return] to switch over to agent mode and then enters those credentials.

These information can also be specified on the command line. Equally, most of the settings can be placed in a configuration file or stored in environment variables.

A pre-configured connection can be selected either in interactive mode when prompted for a mode by typing ‘cf’ or ‘cn’ and then entering the name of the appropriate configuration file and/or section or by specifying it on the command line.

Besides connecting to hosts via a ButConnect server, a direct mode is also available for connecting to hosts on remote networks via an SSH server.

We have also started a more in-depth documentation page and a short guidance for unattended access.

Command Line

ButConnect can also be controlled from the command line:


Usage: ButConnect.exe [--mode[=value]] [--option[=value] [...]]

Without any argument, 'ButConnect' will run fully interactive.

You have to choose the mode of operation first:

Simply press [Enter] for default client mode (VNC) or type ... 

... 'c' for default client mode (VNC)

... 'ca' for 'chat to agent' mode (client)

... 'd' for download mode (client)

... 'r' for remote mode (client)

... 't' for target mode (client)

... 'la' for 'let access' mode (client)

... 'a' for default agent mode (VNC)

... 'ac' for 'accept to chat' mode (agent)

... 'u' for upload mode (agent)

... 'l' for local mode (agent)

... 's' for source mode (agent)

... 'ga' for 'get access' mode (agent)

... 'px' for proxy mode (agent)

and then press [Enter].

If you specify command line arguments, you will be prompted for any missing but essential parameter: 



Client Modes:

 -c[=<user>]            --client[=<user>]

 -ca[=<user>]           --chatagent[=<user>]

 -d[=<file>]            --download[=<file>]

 -r[=<loop>]            --remote[=<loop>]

 -t[=<destination>]     --target[=<destination>]

 -la[=<remotehost>]     --letaccess[=<remotehost>]



 Options for Client Mode:

 -p[=<port>]            --port[=<port>]

 -b[=<broker>]          --broker[=<broker>]

                        --server[=<server>]

 -i[=<identity>]        --identity[=<identity>]

                        --user[=<user>]

                        --link[=<link>]

                        --code[=<code>]

                        --loop[=<loop>]

                        --file[=<file>]

 -dest[=<destination>]  --destination[=<destination>]

 -lp[=<localport>]      --localport[=<localport>]

 -rh[=<remotehost>]     --remotehost[=<remotehost>]

 -rp[=<remoteport>]     --remoteport[=<remoteport>]

                        --start[=<program>]

                        --param[=<parameters>]



Agent Modes:

 -a[=<user>]            --agent[=<user>]

 -ac[=<user>]           --acceptchat[=<user>]

 -u[=<file>]            --upload[=<file>]

 -l[=<hook>]            --local[=<hook>]

 -s[=<origination>]     --source[=<origination>]

 -ga[=<remotehost>]     --getaccess[=<remotehost>]

 -px[=<proxyport>]      --proxy[=<proxyport>]



 Options for Agent Mode:

 -p[=<port>]            --port[=<port>]

 -b[=<broker>]          --broker[=<broker>]

                        --server[=<server>]

 -i[=<identity>]        --identity[=<identity>]

                        --user[=<user>]

                        --link[=<link>]

                        --code[=<code>]

                        --hook[=<hook>]

                        --file[=<file>]

 -orig[=<origination>]  --origination[=<origination>]

 -lh[=<localhost>]      --localhost[=<localhost>]

 -lp[=<localport>]      --localport[=<localport>]

 -rh[=<remotehost>]     --remotehost[=<remotehost>]

 -rp[=<remoteport>]     --remoteport[=<remoteport>]

 -ph[=<proxyhost>]      --proxyhost[=<proxyhost>]

 -pp[=<proxyport>]      --proxyport[=<proxyport>]

                        --start[=<program>]

                        --param[=<parameters>]



General Options:

 -h                     --help

                        --manual

 -v                     --version

                        --license

 -au[=(0|1)]            --autoupdate[=(no|yes)]

                        --update

 -lf[=<filename>]       --logfile[=<filename>]

 -ll[=(0-7)]            --loglevel[=(off-all)]

 -m[=<mode>]            --mode[=<mode>]

 -w[=<delay>]           --wait[=<delay>]

                        --limit[=<limit>]

 -x[=<delay>]           --exit[=<delay>]

                        --delay[=<delay>]

 -all                   --advanced

 -conf                  --configure

 -confall               --configureall

 -cf[=<filename>]       --configfile[=<filename>]

 -cn[=<section>]        --configname[=<section>]

                        --arp

 -ipv4                  --ipv4address

 -mac                   --macaddress

 -wol                   --wakeonlan

Environment Variables

The operation of ButConnect can also be controlled with environment variables.

The names of the environment variables are the names of the parameters themselves as asked for in ‘configure’ mode, but prefixed with ‘BUTCONNECT_’.

Non-essential or optional parameters (those that are asked for in ‘configall’ mode, but not in plain ‘config’ mode, for instance) need to be requested to be recognized.
(You do so by naming the regarding parameter on the command line without specifying a value, e.g. ‘ButConnect.exe --start’.)

By using the ‘BUTCONNECT_PASSPHRASE’ environment variable, the passphrase for the identity file (aka ‘ssh private key file’) can be passed on to ButConnect.

Also, the ‘BUTCONNECT_PARAM’ environment variable could contain a password if that's supported by the program to be launched with ‘BUTCONNECT_START’.