• Interactive Brokers in Docker
  • Features
  • Getting Started
    • Using docker run
    • Using docker compose (recommended)
    • Environment Variables
      • AWS Secrets Manager Integration
  • Docker Images
  • FAQ
    • How do I save TWS settings locally?
    • Cannot connect to API when using TWS
    • Error: library initialization failed - unable to allocate file descriptor table - out of memory/root/ibc/scripts/ibcstart.sh
    • Which tag to use, latest or stable?
    • What is the difference between IB Gateway and Trader Workstation (TWS)?
    • Do I need to download TWS separately?
    • What ports does TWS/IB Gateway use internally?
    • How do I configure the default login to paper/live trading?
  • Repository Architecture

Trader Workstation

IB Gateway

• Fully containerized TWS/IB Gateway, no external dependencies
• TWS API access automatically configured and forwarded
• Viewable in a browser (via noVNC)
• Auto-restart, auto-login TWS/IB Gateway automatically via IBC Alpha

docker run -d \
  -p "127.0.0.1:6080:6080" \
  -p "127.0.0.1:8888:8888" \
  --ulimit nofile=10000 \
  -e USERNAME=your_username \
  -e PASSWORD=your_password \
  ghcr.io/junnus-algo/ibkr:latest

Create a .env file:

USERNAME=<your IBKR username>
# wrap password in single quotes if $, /, or \ are present
PASSWORD='<your IBKR password>'

compose.yml:

---
services:
  ibkr:
    image: ghcr.io/junnus-algo/ibkr # latest, stable, 10.21, 10.21.1p etc
    ports:
      - "127.0.0.1:6080:6080" # noVNC browser access
      - "127.0.0.1:8888:8888" # API access
    ulimits:
      nofile: 10000 # See FAQ
    environment:
      USERNAME: ${USERNAME}
      PASSWORD: ${PASSWORD}
      # TWOFA_TIMEOUT_ACTION: restart
      # GATEWAY_OR_TWS: tws
      #
      # Variables prefixed with IBC_ override IBCAlpha`s config.ini:
      # IBC_TradingMode: live
      # IBC_ReadOnlyApi: yes
      # ...
      # See below for more details

Important: Boolean-like values (e.g. yes/no) must be wrapped in single quotes to prevent them from being interpreted as True/False by th YAML parser.

View at localhost:6080.

TWS API is accessible at port 8888.

Variables prefixed with IBC_ will override settings in IBCAlpha's config.ini, e.g.:

• IBC_TradingMode (default: live)
• IBC_ExistingSessionDetectedAction (default: manual)
• IBC_ReadOnlyApi (default: keep existing)
• etc.

See possible values here.

The container supports retrieving credentials from AWS Secrets Manager as an alternative to environment variables: Option 1: Provide IBKR credentials as environment variables directly in docker-compose.yml

environment:
  USERNAME: ib-username
  PASSWORD: ib-password

Option 2: Provide AWS Secrets Manager secret ID, region, access key, and secret key in docker-compose.yml

environment:
  AWS_SECRET_ID: your-secret-id
  AWS_REGION: your-aws-region
  AWS_ACCESS_KEY_ID: your-access-key
  AWS_SECRET_ACCESS_KEY: your-secret-key

The container will automatically:

• Install AWS CLI if missing
• Retrieve and parse the secret
• Prioritize AWS credentials over direct environment variables

See available tags and versions here.

If you want to save TWS settings locally (e.g. to persist settings across container runs), set TWS_SETTINGS_PATH to say, /settings. Then, add a bind mount on your local filesystem, such as in the following compose.yml:

#...
  environment:
    TWS_SETTINGS_PATH: /settings
    #...
  volumes:
    - ./settings:/settings:rw

Now, TWS will load settings from your local filesystem for each container run.

You will need to manually enable Enable ActiveX and Socket Clients (see this issue).

Ensure that you have the appropriate ulimit nofile set: either --ulimit nofile=10000 (docker run) or ulimits: nofile: 10000 (docker compose).

stable is generally preferred as there are less bugs.

TWS is a fully featured trading platform with many features.

IB Gateway has a minimal GUI and is used for API access to the trading platform, for example with automated trading. It also uses less resources.

See here for more differences.

Both the IB Gateway and TWS installation scripts include both IB Gateway and TWS, so downloading either is fine.

TWS uses 7496 (live) and 7497 (paper), while IB gateway uses 4001 (live) and 4002 (paper).

There is no need to change the port for this image, as it automatically forwards the correct port (based on trading mode and TWS/IB Gateway) to 8888.

Set the environment variable IBC_TradingMode to paper or live.

• New versions of IB Gateway are checked for daily, and fetched if available, as a release (detect-releases.yml).
• A PR with the updated Dockerfile (obtained by running build.sh <latest/stable> <version>) is automatically created
• I test the updated configuration (both IB Gateway/TWS)
• I then manually merge the PR, and tag the resulting commit with git tag docker-<version>-<latest/stable>
• Pushing the tag triggers a docker build action (publish.yml, based on the docker- prefix), which reads the version and release channel (latest/stable) from the tag, and then fetches the repo at the tag's commit, builds from the appropriate folder (latest/stable), tags and pushes the image to ghcr.io/extrange/ibkr.