Playbook for operator-action scenarios (CCP lockout, 2FA failure, JVM restart exhaustion, Gateway JVM crash): docs/DISCONNECT_RECOVERY.md.

Product selector (v0.2)

Dual-mode per-instance (v0.2.1)

Other

Docker integration

This tool is designed to drop into a gnzsnz/ib-gateway-docker image via a Dockerfile.template addition, replacing IBC. Install via the Makefile target (make install DESTDIR=...) that drops gateway-input-agent.jar and scripts/gateway_controller.py into the ibgateway user's home.

See docs/MIGRATION.md for swapping out IBC in a gnzsnz/ib-gateway-docker-style Dockerfile.

If you already have an IBC config.ini, the ibcconfigto_env.py one-shot tool converts it to the equivalent ibg-controller env vars (.env, docker run -e, or docker-compose format), warning on unsupported keys instead of silently dropping them. Full mapping table and cutover recipe: docs/FROM_IBC.md.

./ibcconfigto_env.py /path/to/your/IBC/config.ini > .env
or: ./ibcconfigto_env.py --format compose config.ini

Building

# Build the agent jar and stage the controller into dist/
make
Syntax-check the Python controller + validate the agent jar manifest
make test
Create a release tarball (dist/ibg-controller-0.6.2.tar.gz)
make release VERSION=0.6.2
Install directly into a running ibgateway home (for dev on host, or
as called by the Docker image's setup stage)
make install DESTDIR=/home/ibgateway

Build requires a JDK 17+ (javac + jar) and make. No Maven, no Gradle.

Installing from a release tarball (for consumers who don't build)

VER=0.6.2
curl -sSLO https://github.com/code-hustler-ft3d/ibg-controller/releases/download/v${VER}/ibg-controller-${VER}.tar.gz
tar -xzf ibg-controller-${VER}.tar.gz
cd ibg-controller-${VER}
DESTDIR=/home/ibgateway ./install.sh

The tarball layout is flat:

ibg-controller-0.6.2/ ├── gateway-input-agent.jar   ← installed to $DESTDIR/gateway-input-agent.jar ├── gatewaycontroller.py      ← installed to $DESTDIR/scripts/gatewaycontroller.py ├── ibcconfigto_env.py       ← one-shot IBC config.ini → env migration tool ├── install.sh ├── README.md, CHANGELOG.md, LICENSE, SECURITY.md └── docs/     ├── ADR-001-in-jvm-dialog-dispatcher.md     ├── ARCHITECTURE.md     ├── BOOTSTRAP.md     ├── DISCONNECT_RECOVERY.md     ├── FROM_IBC.md     ├── MIGRATION.md     ├── OBSERVABILITY.md     └── UPGRADING.md

Troubleshooting

IBKR auth lockouts and the controller's automatic backoff (v0.3.2+)

Important triage note (v0.5.12+): the CCP LOCKOUT DETECTED

warning name is misleading. Pre-v0.5.12 the most common cause was

an intra-JVM AtkWrapper deadlock that fired the

AuthTimeoutMonitor-CCP 20-second timer locally without IBKR ever

being reached. v0.5.12 disables the AT-SPI bridge in the JVM and

the deadlock is gone — so if you're seeing this on v0.5.12+, it's

much more likely a real broker-side lockout. Triage:

- launcher.log contains NSAUTHSTART for the affected mode →

real broker-side lockout, follow the backoff playbook below

and/or DISCONNECT_RECOVERY.md →

CCP lockout.

- No NSAUTHSTART and you're on a pre-v0.5.12 image → it was

the deadlock; upgrade.

- No NSAUTHSTART on v0.5.12+ → check

/tmp/jvmconsole${TRADINGMODE}.log after kill -3 <jvmpid>

for an AtkUtil.invokeInSwing parked thread (smoking gun for a

bridge regression — open an issue).

IBKR's auth server occasionally stops responding to fresh password logins for several minutes (and occasionally hours) after a burst of failed attempts from the same account. There are two visible failure modes:

• CCP silent timeout — Gateway logs a 20-second silent

• Stuck-connecting retry loop — Gateway's login dialog stays up

What the controller does automatically: as of v0.4.0, the controller detects both modes, applies an exponential backoff between retries (60s → 120s → 240s → 480s → 600s cap), and recovers by **re-driving Log In on the existing Gateway JVM** — never by killing and relaunching it. This matches IBC's LoginManager.initiateLogin pattern: IBKR's auth server treats each new JVM as a fresh handshake and keeps the CCP limiter armed, so the previous v0.2.2–v0.3.2 "backoff + dorestartin_place" design never let the lockout clear. You'll see these lines:

CCP LOCKOUT DETECTED — IBKR's auth server silently dropped the auth request
CCP backoff: waiting 60s before next auth attempt
Retrying auth in-JVM after CCP backoff (attempt 1/8)
In-JVM relogin attempt (no JVM restart — matches IBC's LoginManager.initiateLogin semantics)

or

Login dialog stuck in 'connecting to server' retry loop — IBKR auth server isn't accepting sessions right now. Applying CCP backoff before retry.
CCP backoff: waiting 120s before next auth attempt

The backoff counter is per-trading-mode (live and paper run as separate processes in dual mode, so they don't share state), and resets on genuine 2FA-success. Up to 8 in-JVM retries per controller lifetime; past that the controller exits and the container orchestrator's restart policy takes over. Just let it run — the controller will keep retrying with increasing delays until IBKR's rate limiter clears, often 5–60 minutes total.

If you're still stuck after an hour of patient backoff, double-check:

• You're sending the right username for the trading mode (the

• Your TWSSERVER / TWSSERVER_PAPER matches the regional

• If you have a previously working container's /home/ibgateway/Jts

If a clean retry from a known-good config still fails after the backoff has run its course, the issue is almost certainly account-side (wrong server, wrong userid, account locked), not the controller. Gateway's launcher.log at /home/ibgateway/Jts/launcher.log will confirm the CCP-Timeout case — you'll see the Authenticating → Timeout! pattern with nothing in between. The stuck-connecting case won't show in launcher.log; check the controller's own logs for the "stuck in 'connecting to server'" warning instead.

"Gateway PID unknown (agent never reported one) — cannot proceed without a JVM identity"

App discovery relies on the input agent reporting its JVM PID through the Unix socket. If you see this error, the agent itself failed to start. Check:

• The -javaagent:/home/ibgateway/gateway-input-agent.jar=...

• The agent socket exists and is writable:

• /tmp/jvmconsole${TRADING_MODE}.log — added in v0.5.12. Check

Pre-v0.5.12 deployments only: if you're still on a release that

used the AT-SPI desktop tree for app discovery and you see "IBKR

Gateway never appeared in AT-SPI desktop tree within 120s",

upgrade. v0.5.12+ doesn't use AT-SPI at all and v0.6.2 removed the

ATK install steps from the image; both error modes are gone.

"Existing session detected" dialog keeps appearing in a loop

The controller's EXISTINGSESSIONDETECTED_ACTION=primary clicks Continue Login, which tells IBKR to kick the other session. If something else keeps reconnecting as that account (another container, the mobile app, TWS on your desktop), you'll ping-pong forever. Shut down the other session first.

The controller logs "Gateway JVM PID (from agent): None"

The Java agent's GET_PID command returned nothing. This usually means the agent's Unix socket is the old IBC default path (check GATEWAYINPUTAGENT_SOCKET in the container's env) or the ProcessHandle API isn't available (you're running on JRE < 17). Verify the JRE is Zulu 17 or newer.

Post-login config: "Auto Log Off Time" label not found

Gateway's Lock and Exit panel shows either "Set Auto Log Off Time (HH:MM)" or "Set Auto Restart Time (HH:MM)" depending on account state. The controller tries the label matching the env var you set. If it can't find it, it warns which label Gateway is currently showing and suggests the other env var. Set both AUTOLOGOFFTIME and AUTORESTARTTIME if you want the controller to handle whichever Gateway is displaying.

Security

Full supply chain details (cosign verification, SBOM extraction, pinning to digests, vuln reporting): SECURITY.md. Quick version of the deployment hygiene below.

This is a narrow threat model — single-user container running a trading tool. But there are real things to get right.

If you're running with CONTROLLERCOMMANDSERVER_PORT set:

• Bind to loopback only via Docker: -p 127.0.0.1:7462:7462.

• Set CONTROLLERCOMMANDSERVERAUTHTOKEN to a random

• The controller logs a loud WARNING at startup if the command

Credentials:

• Pass them via docker run --env-file /path/to/.env, never on the

• Set your .env file to 600 on the host. Docker Engine only

• For additional safety, consider Docker secrets (_FILE env vars

Logs and sharing them:

• Window/dialog dumps (CONTROLLERDEBUG=1, the CONTROLLERTEST_MODE

• Gateway's own /home/ibgateway/Jts/launcher.log is NOT

Warm state and file inputs:

• GATEWAYWARMSTATE is trusted — only set it to a directory

• TWSSERVER / TWSSERVER_PAPER are validated as hostnames

What's NOT protected:

• The Java agent's Unix socket is reachable by any process in the

• The command server has no rate limiting.
• No TLS on the command server. Mitigated by recommending

License

MIT — see LICENSE. Builds on work from IBC, ibctl, and gnzsnz/ib-gateway-docker, all credited below.

Acknowledgements

• @rlktradewright for IBC. Most

• Lcstyle/ibctl for the Java-agent

• @gnzsnz for steering the tool's architecture in