How can I connect to the IB Gateway with ib_async running in a docker container?

[dekaidekai]

Hello thanks for the awesome tool!

I am running my ib_async python code in a docker container and trying to connect it to my IB Gateway app, but I am having some trouble and feel like I'm missing something in the setup.

Does anyone have any guidance on how to connect to the IB Gateway through ib_async code that is running in a docker container?

I am facing this issue when trying to connect to the IB Gateway app which is directly running on my host machine (Mac OS) or even when it's in another docker container using ib-gateway and connecting through the docker network. To try to simplify my issue though, below I'll explain the issue only when running IB Gateway app on my host machine.

Any help would be much appreciated, thank you!

Issue

(see below for my minimal reproducible set up)

It seems that my from inside the docker container it can find the IB Gateway port 4002 open using nc command. The function ib_async.connect will also connect successfully to the IB Gateway socket. However, if I'm not mistaken, after this I am thinking that ib_async will hang and never receive any data from the socket and therefore not complete the API connection and timeout at the await asyncio.wait_for(self.apiStart, timeout) part.

basic.py logs

Waiting for IB Gateway API on host.docker.internal:4002 ...
IB Gateway is up on host.docker.internal:4002...
Booting python app...

2025-09-17 22:25:04,724 asyncio DEBUG Using selector: EpollSelector
2025-09-17 22:25:04,724 ib_async.client INFO Connecting to host.docker.internal:4002 with clientId 1...
2025-09-17 22:25:04,729 ib_async.client INFO Connected
2025-09-17 22:25:34,764 ib_async.client INFO Disconnecting
2025-09-17 22:25:34,765 ib_async.client ERROR API connection failed: TimeoutError()
2025-09-17 22:25:34,765 ib_async.client INFO Disconnected.
...
File "/usr/local/lib/python3.11/asyncio/base_events.py", line 654, in run_until_complete
return future.result()
^^^^^^^^^^^^^^^
File "/usr/local/lib/python3.11/site-packages/ib_async/ib.py", line 2043, in connectAsync
await self.client.connectAsync(host, port, clientId, timeout)
File "/usr/local/lib/python3.11/site-packages/ib_async/client.py", line 228, in connectAsync
await asyncio.wait_for(self.apiStart, timeout)
File "/usr/local/lib/python3.11/asyncio/tasks.py", line 502, in wait_for
raise exceptions.TimeoutError() from exc
TimeoutError

However if I run the python code outside of the docker container and directly on my host machine, then the initial connection and API connection in ib_async quickly succeeds, and everything works as expected.

Minimal reproducible set up

• using Mac OS Docker Desktop to run python container
• using IB Gateway 10.39 directly on Mac

docker-compose.yml

services:
  basic:
    container_name: basic
    image: basic
    restart: unless-stopped
    network_mode: host
    environment:
      IB_HOST: host.docker.internal
      IB_PORT: 4002

Dockerfile for basic

FROM python:3.11

USER root

RUN apt-get update && \
    apt-get install -y --no-install-recommends netcat-traditional iputils-ping

# Environment: no .pyc files, unbuffered logs, and no pip cache
ENV PYTHONDONTWRITEBYTECODE=1 \
    PYTHONUNBUFFERED=1 \
    PIP_NO_CACHE_DIR=1

##### Install python code
# copy local code to the container image.
RUN mkdir -p /home/basic
ENV APP_HOME=/home/basic
WORKDIR $APP_HOME
COPY basic.py ./src/basic.py

# install dependencies
RUN pip install ib_async

COPY ./entrypoint.sh /home/entrypoint.sh

##### Run
ENTRYPOINT ["/home/entrypoint.sh"]

entrypoint.sh

#!/bin/bash
set -euo pipefail

: "${IB_HOST:?IB_HOST must be set}"
: "${IB_PORT:?IB_PORT must be set}"

echo "Waiting for IB Gateway API on ${IB_HOST}:${IB_PORT} ..."
for i in $(seq 1 120); do
  if nc -z -w1 "$IB_HOST" "$IB_PORT" 2>/dev/null; then
    echo "IB Gateway is up on ${IB_HOST}:${IB_PORT}..."
    ##### start python #####
    echo "Booting python app..."
    exec python /home/basic/src/basic.py
  fi
  sleep 1
done

echo "ERROR: IB Gateway at ${IB_HOST}:${IB_PORT} is not open after 120s" >&2
exit 1

basic.py

import os
import logging
import time
from ib_async import IB, util


if __name__ == "__main__":
        ib = IB()
        util.logToConsole(level=logging.DEBUG)
        ib.connect(host=os.environ['IB_HOST'],
                   port=os.environ['IB_PORT'],
                   clientId=1,
                   timeout=30)
        print(ib.accountSummary())

        while True:
            time.sleep(10)

IB Gateway settings

• Read-Only API: OFF
• Socket port: 4002
• Master client ID:
• Allow connections from localhost only: OFF
  • Trusted IPs:

[gnzsnz]

the key question here is what is your ib-gateway instance IP, and if it's listening to 127.0.0.1 like it does by default. with the extra twist that from within your docker container 127.0.0.1 is not going to help.

If you run ib-gateway and your code in docker, the put them in a docker compose service

services:
  basic:
    ... your things here
    networks: 
      - algo
  gateway:
    ...
    networks: 
      - algo

networks:
    algo:
      name: algo

then from your code

...
# hostname == service name
# port 4004 for paper in https://github.com/gnzsnz/ib-gateway-docker?tab=readme-ov-file#ports
ib = ib_async.IB().connect("gateway",4004,10) 
...

Every combination is different. the key is that ib-gateway and TWS listen on 127.0.0.1 so you need your code to be able to access 127.0.0.1, you can't do that within docker. the docker image that you pointed uses netcat to forward the port to an external IP, you either use that IP, or the service name like in the example above.

[dekaidekai]

@gnzsnz Thank you for your reply!

I tried to replicate your example by putting everything in the docker network and use IB Gateway in the docker container ib-gateway and connect through it with the service name.
However it seems like I am experiencing the same issue. It finds the ib-gateway:4004 socket is open and connects, but seems to again hang and timeout on the API connection check. I wrote what my setup is below when the issue occurs.

logs:

Waiting for IB Gateway API on ib-gateway container ib-gateway:4004 ...
IB Gateway is up on ib-gateway:4004...
Booting python app...
2025-09-19 00:35:46,312 asyncio DEBUG Using selector: EpollSelector
2025-09-19 00:35:46,312 ib_async.client INFO Connecting to ib-gateway:4004 with clientId 10...
2025-09-19 00:35:46,317 ib_async.client INFO Connected
2025-09-19 00:36:16,347 ib_async.client INFO Disconnecting
2025-09-19 00:36:16,348 ib_async.client ERROR API connection failed: TimeoutError()
2025-09-19 00:36:16,348 ib_async.client INFO Disconnected.
Traceback (most recent call last):
...
File "/usr/local/lib/python3.11/site-packages/ib_async/ib.py", line 2043, in connectAsync
await self.client.connectAsync(host, port, clientId, timeout)
File "/usr/local/lib/python3.11/site-packages/ib_async/client.py", line 228, in connectAsync
await asyncio.wait_for(self.apiStart, timeout)
File "/usr/local/lib/python3.11/asyncio/tasks.py", line 502, in wait_for
raise exceptions.TimeoutError() from exc

However, if I run my python code not from within my basic docker container, but instead directly on the host machine (for ex. on VSCode), ensure the python code points to 127.0.0.1:4002, and I expose the running ib-gateway container's ports with the code below :

(docker-compose.yml)    
    - "127.0.0.1:4001:4003"  # live (optional)
    - "127.0.0.1:4002:4004"  # paper (optional)
    - "127.0.0.1:5900:5900"

It all works and immediately API connection check succeeds. For some reason it's when my python code runs in the docker container that causes this issue.

2025-09-18 20:59:36,215 asyncio DEBUG Using selector: KqueueSelector
2025-09-18 20:59:36,216 ib_async.client INFO Connecting to 127.0.0.1:4002 with clientId 10...
2025-09-18 20:59:36,217 ib_async.client INFO Connected
2025-09-18 20:59:36,241 ib_async.client DEBUG <<< 178,20250919 00:59:35 UTC
2025-09-18 20:59:36,241 ib_async.client DEBUG >>> 71,2,10,
2025-09-18 20:59:36,241 ib_async.client INFO Logged on to server version 178
...

Would you possibly have any other ideas on what could be wrong in my set up and why running it in a docker container breaks it?
Thanks again 🙇

set up with issue

docker-compose.yml

networks:
  algo:
    name: algo

services:
  basic:
    container_name: basic
    image: basic
    restart: unless-stopped
    networks:
      - algo
    environment:
      IB_HOST: ib-gateway
      IB_PORT: 4004

  ib-gateway:
    container_name: ib-gateway
    image: gnzsnz/ib-gateway:stable
    restart: unless-stopped
    networks:
      - algo
    build:
      context: ./stable
      tags:
        - "ghcr.io/gnzsnz/ib-gateway:stable"
    environment:
      TWS_USERID: ${IB_USERNAME}
      TWS_PASSWORD: ${IB_PASSWORD}
      TRADING_MODE: "paper"
      READ_ONLY_API: "no"
      TWS_ACCEPT_INCOMING: "accept"
      JAVA_HEAP_SIZE: 2000

basic.py

import os
import logging
import time
from ib_async import IB, util


if __name__ == "__main__":
        ib = IB()
        util.logToConsole(level=logging.DEBUG)
        ib.connect(host=os.environ['IB_HOST'],
                   port=os.environ['IB_PORT'],
                   clientId=10,
                   timeout=30)
        print(ib.accountSummary())

        while True:
            time.sleep(10)

[dekaidekai]

@gnzsnz Nevermind I think I found the issue 😅

In my python docker container I had a bash script entrypoint that runs a check through nc command to first check for 120s if the ib-gateway endpoint and port are open and available before I start the python app (code below).

Using this command to check if the port is open, and then quickly after running the python app to connect to that port with ib_async.connect caused these connection issues. I believe because somehow the nc process was still using the connection.

The fix was to add some time between the nc command and the python app running to allow the nc connection to close fully before the python one can properly connect, or remove this nc check altogether.

for i in $(seq 1 120); do
   if nc -z -w1 "$IB_HOST" "$IB_PORT" 2>/dev/null; then
    sleep 10 # ensure netcat connection to ib-gateway finishes before starting python <-----------------
    echo "IB Gateway is up on ${IB_HOST}:${IB_PORT}..."

    echo "Booting python app..."
    exec python ...
  fi

Sorry for the bother, and thanks for all the help! 🙏

[gnzsnz]

your code is probably causing troubles. https://ib-api-reloaded.github.io/ib_async/api.html#module-ib_async.ib please follow "The One Rule"

this is creating problems

          while True:
            time.sleep(10)