IBeam and the automated IBKR Gateway login nobody wants to do twice

The Gateway session that has to be renewed by hand

The Interactive Brokers Client Portal Web API Gateway will not stay logged in on its own. It asks for credentials on a regular basis, and on a server with no display and no human at the keyboard that request has to be answered by software. IBeam exists to answer it.

The project describes itself as an authentication and maintenance tool for that Gateway, and the feature list is blunt about what it buys. It facilitates a continuous headless run of the Gateway, needs no physical display because a virtual display buffer is used instead, and requires no interaction from the user because credentials are injected automatically into the authentication page. It also supports TLS certificates of your own, is containerised with Docker as a plug and play image although it also runs standalone, and carries a warning in the same list: "Not so secure". The project's own words for the trade-off are that you will need to store the credentials somewhere, and that is a risk.

The audience is therefore narrow and specific: people running algorithmic trading infrastructure against the IBKR web API on a VPS or a container host. The repository topics name the field, listing algo-trading, gateway, ibkr-api and ibkr-credentials among others. There is no home page and no marketing site. The whole product is the tool, and the package on PyPI is named ibeam.

Tickle, Selenium, virtual display, then form fill

The startup sequence is documented step by step, and it explains what the project actually does at runtime.

First, IBeam copies inputs from the Inputs Directory into the Gateway root folder, if an input is provided. Then it ensures the Gateway is running by calling the tickle endpoint, and if the Gateway is not up it starts the Gateway in a new shell. Next comes the part that matters: it ensures the Gateway has an active session that is authenticated, again by calling the tickle endpoint. If that check fails, IBeam creates a new Chrome Driver instance using selenium, starts a virtual display using pyvirtualdisplay, accesses the Gateway authentication website, inputs the username and password and submits the form, waits for the login confirmation, and quits the website. It then verifies once more that the Gateway is running and authenticated.

After that comes the maintenance phase, which attempts to keep the Gateway alive and authenticated and repeats the login whenever it finds no active session or a session that is not authenticated.

Two implementation details are worth noting. The credential entry is a browser automation of an HTML form, not an API call, which is why a Chrome driver and a virtual display are required at all. And the design is poll based: the tickle endpoint is consulted repeatedly, and login happens reactively when the answer says the session is gone.

Docker is the path the project recommends

The quick start offers two installs. The recommended one is the published image:

docker pull voyz/ibeam

Standalone installation goes through pip:

pip install ibeam

For a quick check, the container can be started with the credentials passed as environment variables and the API port published:

docker run --env IBEAM_ACCOUNT=your_account123 --env IBEAM_PASSWORD=your_password123 -p 5000:5000 voyz/ibeam

The longer form is a compose file. The README asks for a compose.yaml with these contents:

services:
  ibeam:
    image: voyz/ibeam
    container_name: ibeam
    env_file:
      - env.list
    ports:
      - 5000:5000
      - 5001:5001
    network_mode: bridge # Required due to clientportal.gw IP whitelist
    restart: 'no' # Prevents IBEAM_MAX_FAILED_AUTH from being exceeded

Two comments in that file carry real operational meaning. The bridge network mode is required because of the clientportal.gw IP whitelist, so the container needs a stable IP that the Gateway can be told about. The restart policy is deliberately off, because an automatic restart would keep tripping the failed authentication limit.

The repository's own compose.yaml differs slightly from the README example in one way that matters for exposure: it binds both ports to the loopback interface.

services:
  ibeam:
    image: voyz/ibeam
    container_name: ibeam
    env_file:
      - env.list
    ports:
      - 127.0.0.1:5000:5000
      - 127.0.0.1:5001:5001
    network_mode: bridge # Required due to clientportal.gw IP restrictions
    restart: 'no' # Prevents IBEAM_MAX_FAILED_AUTH from being exceeded

Credentials then live in an env.list file next to it, and the stack is started with docker compose up -d. Once the container runs, the README suggests confirming the Gateway is up by calling the auth status endpoint:

curl -X GET "https://localhost:5000/v1/api/iserver/auth/status" -k

The -k flag matters, since it skips certificate verification against a self-signed Gateway certificate.

Standalone mode needs Java and Chromium on the host

Running outside Docker moves the dependency burden to your machine. The standalone start command is:

python ibeam_starter.py

The container image shows what that involves. The Dockerfile starts from python:3.11-slim-bookworm and installs default-jre, dbus-x11, several X font packages, xorg, xvfb, gtk2-engines-pixbuf, nano, curl, iputils-ping, chromium and chromium-driver. That is a large set of packages for what looks like a single process, and every one of them exists to make browser automation of a login page work headlessly.

The image also sets a specific set of environment variables that tell the tool where things live, including JAVA_HOME, IBEAM_GATEWAY_DIR pointing at /srv/clientportal.gw, IBEAM_CHROME_DRIVER_PATH pointing at /usr/bin/chromedriver, and OUTPUTS_DIR pointing at /srv/outputs. The clientportal.gw directory is copied into the image from a copy_cache folder, and the Python package is copied into /srv/ibeam. A basic non-root user is created and given ownership of the source, outputs and gateway directories.

The Python dependencies are modest and pinned: selenium 4.12, cryptography 40.0, pyvirtualdisplay 3.0, apscheduler 3.10, psutil 5.9, requests 2.31, pillow 9.5 and pyotp 2.9. The presence of pyotp and the cryptography library lines up with the two factor authentication support and the TLS certificate support listed as features, while apscheduler and psutil back the maintenance loop. The project roadmap shows TLS certificates and two factor authentication already struck through as done, with removing the need to install Java still open.

Credentials on disk are the price of unattended login

The security section is unusually candid, and it is the part every adopter has to read. The Gateway requires credentials to be provided on a regular basis, and the only way to avoid entering them manually each time is to store them somewhere, which the project calls a security risk in itself.

By default IBeam expects the credentials to be available as environment variables during runtime. Whether it runs in a container or directly on a host, an unwanted user may gain access to them. The project says plainly that if your setup is exposed to the risk of someone unauthorised reading the credentials, you may want to look for other solutions, or use the Gateway standalone and authenticate manually each time. That last option is the honest fallback: without unattended login, you give up the headless automation that is the entire point of IBeam.

Two narrower options are proposed. The first is a locked Docker Swarm instance, installing credentials with Docker Secrets and telling IBeam to read them from the container in-memory /run filesystem. The project is careful to say what this does and does not buy: the credentials are encrypted at rest, but they are still accessible in plaintext through the running container, so an exploit for the port 5000 API or a compromised host could still expose the secret.

The second is GCP Secret Manager, where a Service Account credential is used to read secrets, with IBeam querying Google's metadata server for the Service Account access token. The project notes that this applies to Compute Engine, Kubernetes, Cloud Run and Cloud Functions, since all of them run with a Service Account available.

It is not a TWS automation tool, and it is still beta

Two boundaries decide whether IBeam fits your setup.

The first is scope. The README states that IBeam is not designed to automate logging into TWS or IB Gateway, also known as TWS Gateway, and points to IBC for that. It also mentions Docker image projects that bundle TWS or Gateway together with IBC. So if your trading stack runs the desktop TWS application, IBeam is the wrong tool by its own account. It also names an alternative for a different need: if you want a Python client for the IBKR Web API rather than a session keeper, IBind is suggested. The difference in approach is precise, IBeam maintains an authenticated Gateway session with no human present, while a client library leaves session handling to the caller.

The second boundary is maturity. The README opens by saying the library is currently being beta-tested and invites issues for anything broken. The package metadata agrees, classifying the distribution as Development Status :: 4 - Beta. Releases are frequent but numbered pre-1.0: v0.5.11 on 2026-04-09, v0.5.12 on 2026-04-21 and v0.5.13 on 2026-09-20, with the last push on 2026-09-20. The repository is not archived.

The licence is Apache-2.0, which carries the usual obligations around notices and patent grants, and it covers the IBeam code only. The Interactive Brokers Gateway it drives is a separate product with its own terms, and the Gateway's own licensing and account requirements apply regardless of how the login happens.

Editorial conclusion

Adopt IBeam if you run the Interactive Brokers Client Portal Gateway on a machine with no display and need its session to stay authenticated without a human logging in. Do not adopt it to automate TWS or IB Gateway, because the project says that is out of scope and points elsewhere. Before deploying, read the security section and decide how your Gateway credentials will be stored, then confirm that the ports 5000 and 5001 in compose.yaml are reachable only from where you intend to run them.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. Releases
5. Voyz/ibeam on GitHub