Recommended IBKR Setup

The basic connection in Connecting IBKR is enough to start trading. This page covers the setups experienced users graduate to — so you can keep an eye on your account from your phone while VolNinja trades, run paper and live at the same time, and leave the connection running unattended.

Everything here is optional. Pick the option that matches how you want to run — or jump straight to the setup we recommend, which combines them.

The one-session limit

You log in to IBKR through one app — IB Gateway or TWS — and that app holds your session. VolNinja never logs in itself; it connects to that already-running Gateway or TWS over IBKR's API (which is why you only ever gave VolNinja ports, never your IBKR password).

The catch is that Interactive Brokers allows only one active session per login, and whichever app logs in last wins. So if the Gateway that VolNinja relies on is signed in, and you then open the IBKR mobile app or another TWS with the same credentials, IBKR kicks the first session off — the Gateway disconnects, and VolNinja loses its connection with it.

There are two ways around this, and the options below combine them:

• Give yourself a second login (a second username), so the Gateway VolNinja uses holds one login and you use the other.
• Take advantage of the fact that your paper and live accounts already have separate logins — so one app can hold paper while another holds live.

Option 1 — Add a second IBKR username

If VolNinja connects to a TWS running on your own machine, you can already watch and adjust in that same TWS window — no extra login needed. A second username matters when you want to monitor or trade from a separate device at the same time: the IBKR mobile app on your phone, or TWS on another computer, while the Gateway or TWS that VolNinja connects to stays connected.

You create an additional username under your existing IBKR account, giving you two independent logins that can both be signed in at once — one for the Gateway or TWS that VolNinja connects to, one for you.

Create the second username in the IBKR Client Portal:

1. Log in to Client Portal and open Settings → Users & Access Rights (under Account Settings).
2. Add a new user, give it a username and password, and grant it the permissions it needs — trading and market data at minimum.
3. Complete IBKR's confirmation steps. The new user is usually active within a day.

Then log the Gateway or TWS that VolNinja connects to into one username (see Connecting IBKR), and use the other username on TWS or the mobile app.

Option 2 — Run IB Gateway in Docker (paper + live together)

For a hands-off, always-on connection — ideal on a VPS — the community ib-gateway-docker image runs IB Gateway headless, logs itself in, restarts on a schedule, and can hold both a paper and a live connection at the same time. VolNinja then connects to both on the standard ports.

You will need Docker installed (the same Docker Desktop VolNinja uses) and your IBKR credentials.

Create a docker-compose.yml:

services:
  ib-gateway:
    restart: always
    image: ghcr.io/gnzsnz/ib-gateway:stable
    environment:
      TWS_USERID: ${TWS_USERID}
      TWS_PASSWORD: ${TWS_PASSWORD}
      TWS_USERID_PAPER: ${TWS_USERID_PAPER}
      TWS_PASSWORD_PAPER: ${TWS_PASSWORD_PAPER}
      TRADING_MODE: both
      READ_ONLY_API: no
      BYPASS_WARNING: yes
      VNC_SERVER_PASSWORD: ${VNC_SERVER_PASSWORD}
      AUTO_RESTART_TIME: 11:59 PM
    ports:
      - "127.0.0.1:4001:4003"   # live  → the port VolNinja uses for live
      - "127.0.0.1:4002:4004"   # paper → the port VolNinja uses for paper
      - "127.0.0.1:5900:5900"   # VNC, to view the gateway if you need to

And a .env beside it with your credentials:

TWS_USERID=your_live_username
TWS_PASSWORD=your_live_password
TWS_USERID_PAPER=your_paper_username
TWS_PASSWORD_PAPER=your_paper_password
VNC_SERVER_PASSWORD=choose_a_password

Start it with docker compose up -d. A live login needs two-factor approval — approve it in the IBKR Mobile app when prompted. Once it is up, it exposes port 4001 for live and port 4002 for paper — exactly the ports VolNinja expects — so VolNinja connects to it just like a desktop Gateway.

A few things worth knowing:

• BYPASS_WARNING: yes turns off IBKR's order-precaution pop-ups for API orders — the same protection you would otherwise enable by hand (see Connecting IBKR). Leave it on so VolNinja's orders aren't silently rejected.
• AUTO_RESTART_TIME restarts the gateway daily so it stays logged in without a full re-login (which would prompt two-factor again).
• both mode is only available on recent gateway versions. If the paper side won't connect, make sure you are on the :stable (or :latest) image and that both sets of credentials are correct.
• If you also want to watch your live account on your phone while this runs, pair this with Option 1 — the gateway holds your live login, so your phone needs the second username.

Option 3 — Run Gateway and TWS side by side

VolNinja can hold a live connection and a paper connection at the same time — but a single Gateway or TWS is logged into just one account, so it can only serve one of them. To trade both at once without Docker, run two apps: one logged into your paper account and the other into your live account. VolNinja connects to both, giving it a live and a paper connection together. Because paper and live are separate logins, the two apps don't collide.

For example, run IB Gateway on your live account and Trader Workstation on your paper account — or the reverse. In each app, enable the API and set its socket port to what VolNinja expects for that mode: live on 4001 (Gateway) or 7496 (TWS), paper on 4002 (Gateway) or 7497 (TWS) — the steps are in Connecting IBKR.

If you want two live sessions — VolNinja trading live and you watching live — combine this with Option 1's second username, since a single live login can't be in two places at once.

The setup we recommend

For an always-on setup where VolNinja trades around the clock and you can still look in whenever you like, combine the options above. This is the setup we run ourselves:

1. Two usernames. Create a second username on your IBKR account (Option 1).
2. A Docker gateway on the first username, both modes. Run the Docker gateway (Option 2) signed into your first username — its live and paper sides together with TRADING_MODE: both. VolNinja gets a live and a paper connection at once, and the gateway keeps itself logged in and restarts on schedule.
3. You, on the second username. Sign in to TWS or the IBKR mobile app with your second username whenever you want to watch or adjust. Because it's a different login, it never disturbs the gateway VolNinja depends on.

The result: VolNinja trades paper and live continuously through the Docker gateway, while you can watch over its shoulder from your phone any time without knocking it offline.

Which should I choose?

• Just getting started, trading one mode — a single IB Gateway is plenty.
• Paper and live at the same time, one computer — run two apps, one on each account (Option 3), or the Docker gateway below.
• Always-on or on a VPS — run the gateway in Docker (Option 2) so it logs itself in, holds paper and live together, and survives restarts.
• Want to watch your live account on your phone while VolNinja trades it — add a second username (Option 1).

Next steps

• Connecting IBKR — the base connection steps these setups build on.
• Paper vs live — how VolNinja picks which account is active.