Cover image created through Copilot

In my previous How2 column Connecting My Trading Strategies To Interactive Brokers, I shared how to set up the Interactive Brokers API connection through the Trader Workstation (TWS) on the local machine. However, the enforced rules like daily auto restart and weekly log-out can be a hassle if you are away from your local machine for many days. In this article, we’ll leverage the power of docker to free you from managing your locally-run TWS attentively.

Previous readings

Recap how to connect to Interactive Brokers API service

To connect to the broker’s API service, IBKR APIs are connected to the API service through its proprietary software called Trader Workstation (TWS). The TWS software runs on the local machine and provides a secure connection to the IBKR API.

How does your API call reach the IBKR API service

The challenge faced

Even though we have set up the TWS connection on the local machine, there are enforced rules that prohibit us from leaving the TWS running for an extended period of time. The TWS software requires a daily auto-restart and a weekly log-out. Plus, logging back into the TWS or IB gateway requires two-factor authentication through your mobile device, which can be a hassle if you are away from the local machine for multiple days. If you are traveling or on vacation, you may not want to carry your laptop just to keep the TWS connection alive. Also, suppose the TWS application is down when you’re away. In that case, you won’t be able to monitor your trading strategies and adjust them whenever there’s an issue with your connection between your trading script and your TWS application running locally.

Potential solution

Therefore, we need a tool that can monitor the status of the application and automatically restart it if it goes down. This will free us from the burden of manually managing the TWS connection and allow us to focus on our trading strategies. In this context, Docker indeed seems to be the most appropriate technology to help us achieve our goals. Docker Hub, an open platform to store and share your Docker images, provides a wide range of pre-built Docker images that can be used to run the TWS software in a containerized environment. Here we’re going to explore a few potential options and compare the pros and cons of these pre-built Docker images.

Choices of Interactive Brokers Docker Images

1. IBEAM

IBEAM

IBEAM is a Docker image that provides a containerized version of the Trader Workstation (TWS) software, exposing the TWS Web API to call remotely. It has the following advantages compared to running TWS on your local machine:

Headless run of the Gateway.
No physical display is required.
No user interaction such as login or 2FA required

How to spin up an IBEAM container

1	docker run --env IBEAM_ACCOUNT=[tws_account]--env IBEAM_PASSWORD=[tws_password] --env IBEAM_PAGE_LOAD_TIMEOUT=120 -p 5000:5000 voyz/ibeam

It’s just that simple.

PS: Use 5001 port on your local machine if you’re using Mac devices.

How to test the IBEAM API

You can use the APIs used are available in TWS Web API Doc. For example:

curl -X GET "https://localhost:5001/v1/api/one/user" -k

curl -X GET "https://localhost:5001/v1/api/portfolio/accounts" -k

curl -X GET "https://localhost:5001/v1/api/trsrv/stocks?symbols=AAPL,WDC" -k

API call examples

Notes

One thing that you need to pay additional attention to is that, since you’re using the TWS Web API services, the APIs are asynchronous. This means that you’ll need to handle the asynchronous responses properly in your own trading scripts instead of utilizing the existing library like ib_insync. Also, you’ll need to handle the extra SSL certification validation when making API calls. For example, if you’re testing API calls, you’ll need to disable the SSL certification validation, as shown in the following screenshot.

PS: If you want to test it through Postman, you need to switch off the SSL certification exam

2. ib-gateway-docker

ib-gateway-docker

The principle of the ib-gateway-docker image is to use a GUI framework called X11 to simulate a virtual desktop environment and run the IB Gateway software inside a docker. In this docker image, IBC application are pre-installed to construct the pre-defined interactions between remote access and IB Gateway inside these docker images. This docker image is capable of:

Auto-login with username and password provided.
Keep the application alive
Support 2FA login
Support auto-restarted each day during the week, without the user having to re-authenticate
Remote access the IB Gateway inside the docker container

The benefit of using ib-gateway-docker compared to using IBEAM is that you can still use the existing async library like ib_insync in your trading script to communicate with IB Gateway. This saves the effort of reinventing the wheel from scratch.

3. ibkr-docker

I consider ibkr-docker to be the advanced version of the ib-gateway-docker. Both docker images use a similar approach to containerize the IBC application. In addition, ibkr-docker contains much more features and possibilities to be extended and explored. See the below table for the major differences in features:

-	ib-gateway-docker	ibkr-docker
Github Maintainer	UnusualAlpha	extrange
Based on	Alpine Linux	Alpine Linux
Purpose	Focused on running the IB Gateway Application	Designed for running both TWS and IB Gateway, with additional features like noVNC access
GUI	Minimal GUI (primarily for API access)	Fully featured TWS platform accessible via noVNC
Components	Includes IB Gateway, IBC, Xvfb, and optional X11vnc	Provides a fully containerized TWS/IB Gateway setup
Use Case	Ideal for automated trading and API access	Suitable for both manual trading (via TWS) and automated tasks (via IB Gateway)

4. Others

How to address the challenges we faced

To resolve the challenges we’re facing right now, I choose ibkr-docker over the other options because: 1. It provides a fully containerized TWS/IB Gateway setup with more features, 2. The maintainer still actively updates this Github repo, and 3. In the workflow that I’m adopting (see Connecting My Trading Strategies To Interactive Brokers), I barely need to change anything in my trading script but spin up a docker container instead. So, let’s get to it.

1. Spin up a default docker container

# Download the ibkr-docker image with the proper tag/version
docker pull ghcr.io/extrange/ibkr:10.19.2h

# Spin up the container
docker run -d -p "127.0.0.1:6080:6080" -p "127.0.0.1:8888:8888" \
-e USERNAME={username} -e PASSWORD={password} \
ghcr.io/extrange/ibkr:10.19.2h

This command will spin up a default docker container and expose two external ports: 6080 is used for accessing the GUI via noVNC, and 8888 is used for the TWS/IB Gateway API calls.

2. Ensure the software restarts properly

To ensure the TWS/IB Gateway software restarts properly, you need to set the environment variable autoRestartTime. It is an IBC setting that instructs IBC to handle the restart of the TWS/IB Gateway Application. I would recommend you check out the config.ini file. As stated in the section of Environment Variables the variables inside config.ini can be accessed by putting prefix IBC_ in front of it. Therefore, the command to spin up the container would be:

docker run -d -p "127.0.0.1:6080:6080" -p "127.0.0.1:8888:8888" \
-e USERNAME={username} -e PASSWORD={password} \
-e IBC_AutoRestartTime="03:00 AM" \
ghcr.io/extrange/ibkr:10.19.2h

2.1. Wait… It didn’t restart as the time I instructed to.

I asked this question to myself while I was waiting for the application to restart. I was very confused. I double-checked the setting in TWS through noVNC and it was correctly set to the restart time that I wanted it to. Then something struck me: I saw the time on the top right corner of TWS is still in the UTC timezone, not the local timezone that I expected. Therefore, one more environment variable needs to be added.

docker run -d -p "127.0.0.1:6080:6080" -p "127.0.0.1:8888:8888" \
-e USERNAME={username} -e PASSWORD={password} \
-e IBC_AutoRestartTime="03:00 AM" \
-e TZ="US/Eastern" \
ghcr.io/extrange/ibkr:10.19.2h

3. Tackle the 2FA failure

There are two more environment variables to be added to tell the application to handle the 2FA login failure.

In some circumstances, even though you acknowledge the alert, login doesn’t complete successfully. IBC can deal with this situation automatically by shutting down and restarting by setting the TWOFA_TIMEOUT_ACTION="restart".

If you use the IBKR Mobile app for two-factor authentication, and you fail to complete the process before the time limit imposed by IBKR, ReloginAfterSecondFactorAuthenticationTimeout tells IBC whether to automatically restart the login sequence, giving you another opportunity to complete two-factor authentication.

docker run -d -p "127.0.0.1:6080:6080" -p "127.0.0.1:8888:8888" \
-e USERNAME={username} -e PASSWORD={password} \
-e IBC_AutoRestartTime="03:00 AM" -e IBC_TWOFA_TIMEOUT_ACTION='restart' \
-e IBC_ReloginAfterSecondFactorAuthenticationTimeout='yes' \
-e TZ="US/Eastern" \
ghcr.io/extrange/ibkr:10.19.2h

4. Handle the weekly restart

This may be the most crucial step to free us from the predicament of periodically checking our desktop/laptop to ensure the TWS/IB Gateway software is running. There are two ways of doing this.

4.1. Using the existing docker command to restart the container every week

We can use the docker restart command to restart the container. By doing this, we need to:

Name the docker container using the --name parameter when running the initial docker run command.
Use the docker restart [docker_name] command to restart the container and complete the following 2FA in time.
Set up a cron job on your laptop to run the second step every week at a specific time.

The above solution seems plausible, but it still requires an additional tool to schedule the restart task. To make this process fully automated, I prefer to use the tools that we’re already using. Also, I noticed a few things while experimenting various parameters of the ibkr-docker. Assigning the environment variable ClosedownAt would not only shutdown the TWS/IB Gateway Application, but also terminate the docker container. In the meantime, docker has the capability to keep the container alive when the container was shuted down unexpectedly. With these two characteristics discovered, I’ve formulated the following approach:

Use ClosedownAt parameter to force shutting down the TWS application and the docker container
Use docker parameter --restart unless-stopped to instruct docker container to restart once the container is not up.

docker run -d -p "127.0.0.1:6080:6080" -p "127.0.0.1:8888:8888" \
-e USERNAME={username} -e PASSWORD={password} \
-e IBC_AutoRestartTime="03:17 AM" -e IBC_TWOFA_TIMEOUT_ACTION='restart' \
-e IBC_ReloginAfterSecondFactorAuthenticationTimeout='yes' -e IBC_ClosedownAt='Monday 03:00'\
-e TZ="US/Eastern" \
--restart unless-stopped \
ghcr.io/extrange/ibkr:10.19.2h

With the command above, the ClosedownAt will shutdown the container. Then the --restart will notice the container is shuted down and restart the container again.

Voilà! We tackled all the challenges listed! Now we can go on to vacation without worrying about the TWS application stopping or login session expiring.

Conclusion

In this article, we have talked about the different challenges encountered when running IBKR TWS/IB Gateway in a local environment. Then we introduced a few popular docker images available in the Docker hub and explained the pros and cons. Finally, we came to the conclusion that with the proper configuration and automation tools, the container now will handle restarting itself and re-establishing the login session automatically every week.

See you next time.

If you enjoy reading this and my other articles, come check out my Medium page to read more about Quantitative Trading Strategy.

Michael's blog

【How 2】Breaking Free! Use Docker to Create Hands-Off Interactive Broker TWS Managing Experience

Eliminating the Burden of Daily Auto Restarts and Weekly Log-Outs