ib-gateway-docker runs Interactive Brokers Gateway with nobody at the keyboard

A broker session that nobody has to log into

The project describes itself in one line. A docker image to run Interactive Brokers Gateway and TWS without any human interaction on a docker container.

That is the whole problem it solves, and it is a real one. IB Gateway and TWS are desktop applications with a login screen, and a login screen needs a keyboard and a human. A server has neither. So the image contains the pieces that let a container do what a person would do.

The list is explicit. IB Gateway comes in a stable and a latest channel, and Trader Workstation comes in stable and latest flavours from version 10.26.1h. IBC is included to control TWS and IB Gateway by simulating user input, which is the component that types the credentials and presses the buttons. Xvfb is an X11 virtual framebuffer that lets the application run without graphics hardware. x11vnc is a VNC server for interacting with the IB Gateway user interface, and the documentation marks it optional, for development and maintenance purposes.

For TWS there is an xrdp and xfce environment, built on top of the linuxserver rdesktop image. And socat is there to accept a TCP connection from outside the container and relay it to IB Gateway on localhost, because IB Gateway restricts connections to the container's 127.0.0.1 by default. That single line explains the existence of the whole networking arrangement, and it is also the first thing to understand about the security of the deployment.

socat, port mapping and what a broker session exposes

The socat entry deserves more attention than the other dependencies usually get, because it defines the attack surface of the container.

The description is that socat is a tool to accept a TCP connection from non-localhost and relay it to IB Gateway from localhost, because IB Gateway restricts connections to the container's 127.0.0.1 by default. So the container is a deliberate exception to a restriction the broker application enforces, and the port mapping is what makes that exception reachable.

The sample compose file maps the broker ports to the loopback interface only.

    ports:
      - "127.0.0.1:4001:4003"
      - "127.0.0.1:4002:4004"
      - "127.0.0.1:5900:5900"

Binding to 127.0.0.1 rather than to all interfaces is the difference between a broker session reachable from your own machine and one reachable from your network. The 5900 mapping is the VNC port, and the two port pairs cover the live and paper API sockets, which is why the image supports running both trading modes in parallel.

The other half of the answer is the optional SSH tunnel, which the documentation says provides secure connections for both IB Gateway and VNC. It is available from 10.19.2g-stable and 10.25.1o-latest or greater, and it is configured through its own group of environment variables, SSH_TUNNEL, SSH_OPTIONS, SSH_ALIVE_INTERVAL, SSH_ALIVE_COUNT, SSH_PASSPHRASE, SSH_REMOTE_PORT, SSH_USER_TUNNEL, SSH_RESTART and SSH_VNC_PORT.

Two channels, two applications, one set of tags

The tag table is how you pick an artefact, and it is worth reading carefully because the naming has two dimensions.

There are two images, ib-gateway and tws-rdesktop, and two channels within each, latest and stable. The stable channel carries IB Gateway 10.50.1f with IBC 3.24.2, and the latest channel carries 10.51.1c with the same IBC version. The Docker tags follow the same shape, so the stable image is tagged stable, 10.50 and 10.50.1f, and the latest image is tagged latest, 10.51 and 10.51.1c.

The documentation notes that IB Gateway and TWS share the same version numbers and tags, which is convenient, because it means the version of the broker software does not change when you switch between the two applications. The pair of minor tags, 10.51 or 10.50, is the one to use in a deployment, because it lets you take a patch release without changing your compose file.

The IBC version is pinned inside the image rather than being a tag of its own, so the image is a combination of a broker version and an automation version, and the release list shows those combinations arriving together, with ibgateway-latest at 10.51.1c on 2026-10-14, ibgateway-stable at 10.50.1f on 2026-10-06 and ibgateway-latest at 10.51.1b on 2026-09-30.

The last push to the repository was on 2026-10-14, and the licence is MIT.

Getting it running with compose and an env file

The documented way to run it is a compose file, and the repository ships two samples, one for ib-gateway and one for tws-rdesktop, which you can copy as a starting point.

name: algo-trader
services:
  ib-gateway:
    restart: always
    build:
      context: ./stable
    image: ghcr.io/gnzsnz/ib-gateway:stable
    environment:
      TWS_USERID: ${TWS_USERID}
      TWS_PASSWORD: ${TWS_PASSWORD}
      TRADING_MODE: ${TRADING_MODE:-paper}
      READ_ONLY_API: ${READ_ONLY_API:-}
      TIME_ZONE: ${TIME_ZONE:-Etc/UTC}

The credentials come from a .env file in the root directory, and the repository provides a .env-dist file to use as the starting point.

TWS_USERID=myTwsAccountName
TWS_PASSWORD=myTwsPassword
TRADING_MODE=paper
READ_ONLY_API=no
VNC_SERVER_PASSWORD=myVncPassword
TWOFA_TIMEOUT_ACTION=restart

Two things in that list decide how much trouble you will have. TRADING_MODE defaults to paper, so a fresh configuration does not touch a real account, and READ_ONLY_API is the switch that decides whether the session may place orders at all.

The environment block is long, and most of it exists because IB Gateway's login is not a simple form. The repository also has a Dockerfile.template and a Dockerfile.tws.template, an image-files/ directory, a latest/ and a stable/ directory holding the build contexts, and an update.sh script, so the image is built from the same sources the published ones are.

The two-factor variables are the real configuration

Most of the environment variables exist because the login is a multi-step dialog with a two-factor prompt, and IBC has to decide what to do at each step without a person there.

TWOFA_TIMEOUT_ACTION is the important one. The sample env file sets it to restart, while the compose file default is exit. That difference decides whether a session that sits idle past the two-factor window is restarted or the container shuts down, and it is the setting you will need to think about hardest, because a server in a data centre is not somewhere you can walk over and press a key on a phone.

TWOFA_DEVICE names the device for the two-factor prompt. TWOFA_EXIT_INTERVAL defaults to 60 and controls how often the container exits while waiting, and RELOGIN_AFTER_TWOFA_TIMEOUT defaults to no, which means the session is not automatically logged back in after a timeout. Existing session handling has its own variable, EXISTING_SESSION_DETECTED_ACTION, whose default is primary, which is about what happens if the broker reports a session that is already connected from elsewhere.

There is also a bypass for the warning dialog, BYPASS_WARNING, and a pair of trading permissions, READ_ONLY_API and ALLOW_BLIND_TRADING, which defaults to no. ALLOW_BLIND_TRADING is the one to look at carefully. It governs whether the session may submit orders without a confirmation, and a container that logs in unattended is exactly the case where that flag changes the risk profile of a mistake.

Other variables handle the operational side: AUTO_RESTART_TIME and AUTO_LOGOFF_TIME schedule a daily restart and logoff, TWS_COLD_RESTART is a cold restart option, SAVE_TWS_SETTINGS persists the TWS configuration, and TWS_MASTER_CLIENT_ID sets the client id that the master session uses.

Credentials, secrets and the options that arrived over time

How the password reaches the container has changed over the life of the project, and the current answer has two forms.

The plain form is TWS_USERID and TWS_PASSWORD in the environment, or the paper equivalents TWS_USERID_PAPER and TWS_PASSWORD_PAPER. The file form is TWS_PASSWORD_FILE and TWS_PASSWORD_PAPER_FILE, which is the secrets support that the feature list dates to the latest 10.29.1e and the stable 10.19.2m or greater. The compose file in the repository lists both, and the sample env file comments out the file variants with a pointer to the credentials section.

The file form is the one to prefer in a real deployment. A password in a.env file is a password in a file that gets committed by accident, printed in a support ticket, or shipped to a CI log, and the existence of a file-based alternative inside the same image suggests the author has hit that problem.

The version notes in the feature list also show the range of platforms the image targets. aarch64 support, for Raspberry Pi and the M1, M2 and M3 machines, arrived in 10.37.1l and 10.39.1e, which is what makes running a broker session on a small ARM board possible at all.

The other additions are the ones that make the image composable with other tools. Custom scripts can run during the start-up process through START_SCRIPTS, X_SCRIPTS and IBC_SCRIPTS, and the documentation says it works well together with the Jupyter Quant docker image, which is the natural pairing for an analyst who wants the session and the notebook on the same host.

Editorial conclusion

Adopt ib-gateway-docker when you need an Interactive Brokers session running on a server or a small ARM board, and you are willing to manage the credential and two-factor story yourself. Do not adopt it if you cannot supply a broker password through the environment or a secret file, and do not treat a paper session as a rehearsal for live, because the same container runs both. Verify first which tag you pull, latest or stable, and the IBC version it ships with, that your broker port mapping matches the client IDs your strategy uses, and what your TWOFA_TIMEOUT_ACTION should be before the session expires in your absence.

Frequently asked questions

Official sources

1. gnzsnz/ib-gateway-docker on GitHub
2. License: MIT
3. Project website
4. README
5. Releases