IBController User Guide
Please note that there are significant changes to the setup procedure for this release of IBController, compared with release 2.14.n.
Make sure you read the information in the Scope of this User Guide section.
IBController can be used to start TWS running the demo account. However there are many ways in which the demo account differs from a live or a paper trading account, which may occasionally cause some inconvenience. In particular when you login to the demo account you are actually allocated a random account number, and when you log out this account may then be allocated to another user. Next time you log in to the demo account, you are unlikely to be allocated the same account as before, and even if you are given the same one, any settings you made last time round will have changed. IBController makes no attempt to avoid these situations: they are simply an inevitable by-product of using the demo system, which is not intended for any serious usage.
Note that in the remainder of this document, 'Unix' is used to refer to all Unix-derived operating systems, including Linux and OS X.
Overview of IBController
IBController enables Interactive Brokers' Trader Workstation (TWS) and Gateway to be run in 'hands-free' mode, so that a user need not be present. This makes possible the deployment of unattended automated trading systems.
IBController loads TWS or the Gateway and then 'listens' for various events (such as the display of dialogs) that would normally require user intervention. It can then automatically take appropriate action on the user's behalf. For example, as well as automating the TWS and Gateway login by filling the login dialog with your credentials, it can also deal with TWS's autologoff dialog so that it can keep TWS running continuously.
Here are some of the things IBController does for you:
starts TWS or the Gateway
logs you into TWS or Gateway
clicks the YES button if the "Accept incoming connection?" dialog is displayed
clicks the Close button if the Tip of the Day dialog appears
dismisses the dialog that warns of a new TWS version upon startup
responds to TWS's 'Exit Session Setting' to prevent autologoff, enabling TWS to be kept running indefinitely
shuts down TWS tidily at a specified day of the week and time.
IBController also responds to certain commands sent to it by another program, for example to tell TWS/Gateway to shut itself down cleanly.
Scope of this User Guide
This User Guide is intended to help you get started with IBController. It applies to IBController releases 3.2.0 and later. Note that these releases only apply to versions of TWS from TWS 952 onwards: for earlier versions of TWS you should use IBController release 2.14.0.
IBController release 3.2.0 and later has new script files (ie
These files are very different from those in release 2.14.0 and earlier, and also
substantially different from those in releases 3.0.0 and 3.0.1. So if you are
updating an existing IBController installation, make sure that you extract the
new ones from the .zip file (including the ones in the Scripts subfolder) rather
than trying to modify the old ones.
Note that the script files provided in IBController release 3.2.0 and later will not work with TWS 950 and earlier.
Also, while it is technically possible to amend the script files from earlier versions of IBController to work with TWS 952 onwards, you are strongly advised not to do this, because the new scripts do more than the previous versions. Note that priority support will not be provided for 'home-grown' scripts: having said that, we are a friendly lot so we will help if you have problems with your own scripts, but not with the same sense of urgency.
This User Guide has been produced using the Markdown editor and PDF export tool at https://stackedit.io/editor.
Here is a summary of the steps you need to perform to get IBController up and running properly.
Install the offline version of Interactive Brokers Trader Workstation (see Interactive Brokers Trader Workstation in the Prerequisites section), and make sure that it uses the English language setting. Please note that you MUST download the OFFLINE version of TWS, not the self- updating version: IBController DOES NOT WORK with the self- updating version of TWS.
Download the IBController distribution ZIP file (see the Where to get IBController section).
Install IBController (see the Installing IBController section). Please note that if you already have an existing IBController installation, it's wise to rename its folder before installing the new version in case you need to revert to it later.
Create an encrypted folder called
IBControllerin your personal filestore (see Protecting the Password in the Password Security section).
Copy the configuration file (called
IBController.ini) from the
IBController installation folder to the encrypted folder created in step 5.
Check that the correct major version number for TWS is set in the shell script files in the IBController installation folder: these files are
IBControllerGatewayStart.shon Unix. To find the TWS major version number, first run TWS or the Gateway manually using the IB-provided icon, then click
Help > About Trader Workstationor
Help > About IB Gateway. In the displayed information you'll see a line similar to this:
Build 954.2a, Oct 30, 2015 4:07:54 PM
Here the major version number is 954. Ignore the rest of the version number. Now open the script files with a text editor and ensure that the TWS_MAJOR_VRSN variable is set correctly.
At this stage, everything is set up to run IBController with its default settings, which will start TWS and log it into the IB demo user. It is worthwhile doing this just to check that everything works before customising it to suit your needs. To do this, run the relevant shell script (
IBControllerStart.shon Unix) from the IBController installation folder. If everything is satisfactory, shut down IBController by closing TWS in the usual way.
Note that when you start IBController, information about the startup process is logged to a file to aid diagnosing any faults that may occurr. You will be notified of the log file name during the startup sequence.
Edit the configuration file (
IBController.ini) in the encrypted
IBControllerfolder using a text editor such as Notepad. See Configuring IBController for further information.
If you did not install TWS and IBController in their default locations, and store the configuration file in the recommended location, you will have to edit the shell scripts in the IBController installation folder accordingly. They contain comments that will help you do this correctly.
If you intend to run API programs to connect with TWS, you will need to manually edit the API settings in TWS's Global Configuration Dialog.
This section details the other software that is needed to run IBController.
Note that some Unix distributions may provide packages that can automatically install and configure everything needed to run IBController, for example the Arch Linux ib-controller package. This subject is beyond the scope of this document, and you should refer to the relevant package documentation for guidance.
Both IBController and TWS/Gateway are Java programs, and therefore the Java Runtime needs to be accessible, but you don't have to do anything to ensure this.
TWS version 950 and earlier required Java to be explicitly installed on the computer. However starting with TWS 952, the TWS installers for Windows and Linux include a hidden version of Java which Interactive Brokers have used for developing and testing TWS. This version also runs IBController perfectly, and the IBController scripts ensure that it is used.
This means that it is not necessary to ensure that Java is installed on your computer. It doesn't matter if it is already installed, but the IBController scripts won't use it. However the scripts do make provision for declaring specifically which Java installation is to be used in exceptional situations where necessary.
If you had previously installed Java for use with earlier versions of IBController and TWS, but do not need it for any other programs, then you might want to consider uninstalling it once you have finished setting up IBController.
Note for OS X users: the installer for the OS X version of TWS does not currently include the Java Runtime, so you will have to ensure that Java is installed.
Interactive Brokers Trader Workstation
Before running IBController, you will need to download and install the offline version of Trader Workstation from the Interactive Brokers website.
The location of the TWS dowloads page on IB's website varies from time to time,
and from country to country. At the time of writing, on IB's US website (linked
above) you need to click the
Trading menu near the top of the page, then
TWS Software: currently a valid direct link is Tws Software.
IB provides two modes of operation for TWS:
an online, or self-updating TWS that automatically receives updates as IB enhances it and fixes bugs. IBController does not work with the self- updating TWS, so do not install the self-updating version for use with IBController
an offline or standalone TWS that, after download and installation, never changes (until you download and install another version): you must download and install this offline version for use with IBController.
Note that the TWS installation includes the code for both TWS and the Gateway: there is no need to do another download for the Gateway.
However, there are Gateway-specific downloads on IB's website. They contain the same code as the TWS downloads, but they install in a different place. You can install one of these, as well as or instead of the TWS installer. You can find these via the LOGIN dropdown in the title bar of IB's website.
When you run the script to load TWS, it will use the TWS installation if there is one, and if not it will use the Gateway installation if there is one. Similarly when you run the script to load the Gateway, it will use the Gateway installation if there is one, and if not it will use the TWS installation if there is one. (Needless to say, if neither a TWS download nor a Gateway download has been installed, the scripts will fail!)
It is safest to use the 'stable' offline version of TWS rather than the 'latest' version for live trading: the latter is more likely to have bugs.
IBController needs TWS to operate in English so that it can recognise the various dialogues that it interacts with. You can set TWS's language by starting it manually (ie without using IBController) and selecting the language on the initial login dialog. TWS will remember this language setting when you subsequently start it using IBController.
Note that you do not need an IB account to try out IBController, as you can
use the IB demo account (username
Where to get IBController
IBController is officially distributed as a ZIP file containing the compiled program and some additional files, detailed below.
The ZIP file for the latest version should be downloaded from Github. Earlier versions can also be downloaded from the same place if need be.
The distribution ZIP file contains:
- License text
- Compiled JAR (named similar to
- Sample configuration file (named similar to
- Sample TWS launch script for Windows (named similar to
- Sample Gateway launch script for Windows (named similar to
- Sample TWS launch script for Unix (named similar to
- Sample Gateway launch script for Unix (named similar to
- Sample TWS launch script for OS X (named similar to
- Sample Gateway launch script for OS X (named similar to
- Sample Windows Task Scheduler file (named similar to
Start TWS Live (daily).xml)
- A Scripts sub-folder containing sub-scripts used by the top-level scripts mentioned above
- A text file called
versioncontaining the IBController version number
Source code and build scripts are not included in the distribution ZIPs, as they are freely available from the IBController project page on Github.
Installing IBController is just a matter of extracting the contents of the downloaded ZIP file to wherever you want to install it. You will make things easiest for yourself if you use the locations described in 'Default Paths' below, because that will minimise customising the configuration file and the shell scripts.
If you already have a previous IBController installation, it's wise to rename its
folder (eg to
IBController.old) so that you can easily refer back to any
customisations you did for that version.
create the folder where you want to install IBController, if it doesn't already exist. As noted above (see Default Paths) this is normally
C:\IBControllerbut it can be anywhere you like
locate the downloaded ZIP file using File Explorer (Windows Explorer on Windows 7 and earlier). Windows treats ZIP files like an ordinary folder, so you can see its contents the same way as any other folder
select all the files and folders and drag them into your installation folder
- unpack the ZIP file using a command similar to this:
sudo unzip ~/Downloads/IBController-3.3.0.zip -d \ /opt/IBController
- now make sure all the script files are executable:
cd /opt/IBController sudo chmod o+x *.sh */*.sh
Several sample files ship in each IBController release. The sample files (and these
instructions) assume the default paths shown in the table below (where
<username> represents your operating system user name, not your IB login id).
If you store any of these items in other locations, you will need to edit these sample files to reflect this.
|Windows||IB TWS program files||
|IBController program files||
|Unix||IB TWS program files||
|IBController program files||
|MacOSX||IB TWS program files||
|IBController program files||
Note that installing IBController and/or TWS from a Unix package manager may not use these paths. Consult your Linux package instructions for file locations.
To login to TWS or IB Gateway, IBController needs to know your Interactive Brokers username and password. You should very carefully secure your IB account username and password to prevent unauthorised use by third parties. This section gives you guidance on how to achieve this.
The username and password are given to IBController in one of two ways:
via the configuration
.inifile: this is the preferred method because the configuration file can be protected by the operating system
via the command line parameters when IBController is started: this method is strongly deprecated because command line information associated with a process is easily available outside the process (for example via Task Manager on Windows)
Protecting the Configuration File
To protect this sensitive information, the configuration file needs to be stored in a location where it will not be accessible to other users of the computer. The simplest way to achieve this is to store it within your personal filestore:
on Windows this is your
Documentsfolder (which is normally actually located at
C:\Users\<username>\Documents). Note that this folder may also be addressed using environment variables like this:
on Unix it is the
You are advised to place the file in its own
IBController folder within this location.
You should also consider encrypting the folder containing the configuration file. This will prevent another user with administrator privileges gaining access to the contents: even if they (ab)use their administrator privileges to give themselves access to the file, its contents will not be decrypted because they are not the user that encrypted it.
To encrypt the folder on Windows:
right click the folder and select
Advancedbutton on the
set the checkbox labelled
Encrypt contents to secure data
finally, click the
OKbuttons to apply the changes.
Encrypting a folder on Unix is more involved, and you should refer to the documentation for your distribution.
Encrypting the Password
When the password is included in the configuration file, IBController allows it to be in an encrypted form so that casual observers cannot see the actual password, for example while you are editing the configuration file.
Note however that the encryption is very simple and easily reversed by anyone who knows the encryption technique, so it does not remove the need to store the configuration file securely. It can also cause problems if your password has certain characters in certain positions (due to a deficiency in the encryption algorithm): therefore it is advisable not to use the password encryption facility, provided you make sure your IBController configuration file is stored in a safe place and you don't leave it open in an editor while the computer is unattended or overlooked.
To encrypt your password, run the following command from the IBController directory:
java -cp IBController.jar ibcontroller.IBController encrypt <your-password>
The program output will include your encrypted password, which can then be
included in your IBController configuration
You should also clear your shell history if you entered the above command. In most
cases this is achieved by pressing ALT+F7 (Windows users) or typing
(Linux users), although you should check it worked by pressing the up arrow afterwards.
IBController must be supplied with a configuration file. A specimen file called IBController.ini is included in the distribution ZIP. You will need to edit this file to include your IB username and password, and to ensure that IBController behaves in the way that best suits your needs.
You should copy the supplied file from the IBController installation folder into the secure location described above before editing it, so that you have a clean copy to revert to if need be.
IBController.ini file contains detailed comments on the
meaning of each configuration property. Many of these have sensible defaults,
or are only needed in special situations, so to help you get started quickly, here
is a list of the settings that you are most likely to need to change:
|IbLoginID||You must set this to your IB username|
|PasswordEncrypted||You must set this to
|Password||You must set this to your IB password (possibly encrypted)|
|TradingMode||For TWS 955 and later, you must set this to
|IbDir||You only need to set this if you want TWS to store its settings in a different folder from the one it's installed in|
|AcceptIncomingConnectionAction||It is safest to set this to
|IbAutoClosedown||Set this to
|ClosedownAt||Set this if you want to keep TWS running all week|
There are two ways that IBController can locate your edited
the simplest way is to tell it where to find the file in the command that starts IBController. In this way, you can give the configuration file any name you like. This is the recommended approach, and the supplied scripts follow this approach. If you want change the filename from IBController.ini, or if you store it somewhere other than the default location, you'll have to edit the start script to declare it's new name and location.
if you do not specify a configuration file name, IBController will expect to find a file named
IBController.<username>.iniin the current working directory. In this case,
<username>is your username on your computer (not your IB account username). This method is deprecated, because it is likely to result in the
.inifile being in an insecure location.
The normal way to start IBController is by use of a shell script. These can be
identified by the
.bat (Windows) or
.sh (Unix) extensions. Scripts
to start TWS and Gateway are included in the distribution ZIP, and due to their
complexity you are strongly advised to use them, rather than try to create your own.
Windows users can execute a shell script in a number of ways, including:
- Double-click the filename in Windows Explorer
- Create a shortcut to it on your Start menu, desktop or taskbar
- Create a scheduled task to run it automatically at the required times (see below for more information about using scheduled tasks)
If you used the default locations to install IBController and TWS, and to store your IBController.ini file, you should not need to edit the shell scripts. If you do need to change them, they are commented to help you.
Scheduled Tasks (Windows)
On Windows you can start IBController automatically using a Scheduled Task to run IBControllerStart.bat or IBControllerGatewayStart.bat.
If you do this, you must make sure that the machine is already logged on before the scheduled task runs. Otherwise the task will still run, but you won't be able to see and interact with TWS, even if you subsequently log on.
Remember also to change the task settings to prevent Windows automatically ending it after a certain time.
Also you can use the
IbAutoClosedown=no setting in the IBController
configuration file to disable TWS's autologoff feature, and the
setting to specify when IBController will shut down TWS.
In this way you can start IBController automatically on Sunday evening or Monday morning, keep it running all week and then close down tidily on Friday evening or Saturday morning.
The Windows Task Scheduler has many powerful features, and some of these can be used to provide even better control. For example, you can run the task periodically (say every 10 minutes) during the week so that if TWS crashes, it will automatically be restarted. If you also set up your computer to log on automatically when it starts, this will ensure TWS is restarted after a power outage. (Information about how to make your computer log on automatically is easily available on the internet: but make sure you understand the security implications of autologon to Windows).
IMPORTANT Note that Microsoft have made changes to the Task Scheduler for Windows 10. Because of this, it is advisable to set up your Scheduled Task differently on Windows 10: see the next section Running under Task Scheduler on Windows 10.
**IMPORTANT Make sure you use the /INLINE argument to IBControllerStart.bat or IBControllerGatewayStart.bat when starting IBController from Task Scheduler. Otherwise IBController will start and run correctly, but Task Scheduler will not be aware of it: in particular Task Scheduler will not show the task as running. This prevents correct operation of Task Scheduler features such as killing the task after a specified elapsed time.
A sample scheduled task is included in the IBController distribution ZIP,
Start TWS Live (daily).xml. You can import this into your Task
Scheduler if you are running Windows 7, Windows 8 or Windows 8.1 (see below
for further information about running on Windows 10). After importing it, you will
need to enable it and change the user account it runs under. This task starts TWS
daily at 05:55, and assumes that TWS is set to auto-logoff at 05:52, so the
IBController configuration file must include
Running under Task Scheduler on Windows 10
Microsoft have made significant changes to the Task Scheduler in Windows 10. Although the management user interface is pretty much the same as in earlier Windows versions, there are important changes in some of the 'under the hood' operation.
The net effect of these changes is that it is no longer a good idea to start IBController under Task Scheduler by running a command file. It will only work correctly if the command given to Task Scheduler directly runs IBController.
To set this up, first run IBController manually (using IBControllerStart.bat
or IBControllerGatewayStart.bat), and open the log file in Notepad or any other
text editor: if using Notepad, make sure that 'Word Wrap' on the Format menu is
not checked). Now create your scheduled task (it's easiest to import the sample
included in the IBController download zip file), and open the start action editor.
Find the line in the log file that reads: 'Starting IBController with this
command:', then select and copy the first part of the following line (up to but
-cp), and paste it into the
Program/script: field of the action
editor. Then select and copy the remainder of the line in the log file (starting
-cp), and paste it into the
Add arguments (optional): field of the action
editor. You can now run this scheduled task in the normal way.
Note that running IBController via from Task Scheduler via a direct command in
this way means that there is no permanent IBController log file. Any output
from IBController appears in the window that Java creates to host the Java
console output, but there is no way to capture this to a file (note that normal
>> cannot be used in a command in a scheduled
task). If you've made sure that your IBController installation operates
correctly before setting up your scheduled task, this should not be too much
of a problem.
Multiple IBController Instances
You may want to run more than one instance of TWS or the Gateway on the same computer, perhaps simultaneously. Here are some reasons you might want to do this:
you want to run both your live and paper-trading IB accounts. This is especially true if you want to get market data from both accounts, as IB will only allow this if both TWS instances are on the same computer (unless you don't try to run them at the same time)
you have multiple logins for your live IB account, and want to run TWS for both, perhaps at the same time
you trade on behalf of others, perhaps your family, friends or clients, who each have their own accounts, but you want to run TWS instances for all these accounts on one powerful computer
you want to trade in different regions at different times
you want to test a new version of TWS in your paper trading account at the same time as using your live account in a previous version
When TWS runs, it stores a large number of settings in a folder structure (these settings may also be stored in IB's servers, but this is not a useful option if you want to use multiple TWS instances). By default, TWS stores this settings folder structure in the TWS installation folder. For each username, it creates a separate folder structure. Note however that there are some files that TWS creates while running that are not separated by username in this way, and only one instance of TWS can access them at a time. So you can run multiple TWS instances with no problem provided each instance is logged in to a different username, AND you don't try to run them at the same time.
However, by using the
IbDir setting in the IBController configuration file,
you can tell TWS to store its settings whereever you like. So to have multiple
IBController instances operating simultaneously, you need to create a separate
configuration file for each instance with a different setting for
that you do not need to copy the TWS .jar files themselves - you can load TWS
from the same installation folder for each instance.
Because you now have different configuration files, you also need different scripts to run each instance (or you could have a single script and pass the configuration file details as a parameter). And you need to ensure that the different instances don't try to write their log files to the same folder (because otherwise they might try to log to the same file, and one instance would fail).
As a concrete example, let's take the first scenario described above: you want to run both your live and paper trading accounts. So:
install TWS into the default location (
create two new folders
C:\JtsPaperto store the settings
create two IBController configuration files called
set the IbDir option in them to point to the relevant folder, ie
IbDir=C:\\JtsPaper, and set the
IbPasswordto the live or paper account values as appropriate
create two start scripts (by copying
set IBC_INI=...line in each script file to refer to the relevant configuration file
set LOG_PATH=...line n each script file the refer to different folders, for example
now you can run the new scripts, and each will start a separate instance of TWS connected to a different account, with its settings stored in separate folders.
Using different TWS versions simultaneously
To use more than one version of TWS (for example for testing a new version with your paper-trading account while also using a previous version for your live account), you just need to install the required versions in the normal way. Version 952 and later of TWS have installers that automatically place the relevant files in separate folders named according to the version number.
Then follow the advice in the previous section and ensure that each script
file has the correct value for the
If you need assistance with running IBController, or have any queries or suggestions for improvement, you should join the IBController User Group at:
If you're convinced you've found a bug in IBController, please report it via either the IBController User Group or the GitHub Issue Tracker at:
Please provide as much evidence as you can, especially the versions of IBController and TWS/Gateway you're using and a full description of the incorrect behaviour you're seeing.