Drop-in replacement for IBC — automates IB Gateway/TWS login, 2FA, session management, and configuration.
IBC is being deprecated September 2026. ibctl provides the same automation using a Rust supervisor + Java agent architecture that directly inspects Swing UI components (no xdotool, no pixel coordinates, no screen scraping).
ibctl (Rust binary) ibctl-agent.jar (Java agent)
┌─────────────────┐ ┌──────────────────────────┐
│ Process │ UDS │ Runs inside Gateway JVM │
│ supervisor ─┼─HTTP+──┼─ Swing component walking │
│ State machine │ JSON │ Click/type/read fields │
│ TCP cmd server │ │ Menu & tree navigation │
│ Config (TOML+env)│ │ Window event monitoring │
└─────────────────┘ └──────────────────────────┘
The Java agent is injected via -javaagent: into the Gateway JVM. It walks Swing component trees to find buttons, text fields, checkboxes, and menus — the same approach IBC uses internally. Every action is verified through the actual UI state, not blind input injection.
git clone https://github.com/lcstyle/ibctl
cd ibctl
docker build -t ibctl .Create a docker-compose.yml:
services:
ibctl:
image: ibctl
environment:
- TWS_USERID=your_username
- TWS_PASSWORD=your_password
- TRADING_MODE=paper # live | paper | both
- VNC_SERVER_PASSWORD=secret # optional, for remote viewing
ports:
- "4001:4001" # live API
- "4002:4002" # paper API
- "7462:7462" # command server (IBC-compatible)
- "5900:5900" # VNC (optional)docker compose up -dFor live accounts with 2FA:
environment:
- TWS_USERID=your_username
- TWS_PASSWORD=your_password
- TRADING_MODE=live
- TWOFA_DEVICE=IB Key # or "Mobile Authenticator app"
- TWOFA_TIMEOUT_ACTION=restart # restart login on 2FA timeout
- TWOFA_EXIT_INTERVAL=120 # seconds to wait for mobile approval
- RELOGIN_AFTER_TWOFA_TIMEOUT=yes # keep retrying until approvedFor dual mode (live + paper simultaneously):
environment:
- TRADING_MODE=both
- TWS_USERID=live_user
- TWS_PASSWORD=live_pass
- TWS_USERID_PAPER=paper_user
- TWS_PASSWORD_PAPER=paper_pass
- TWOFA_DEVICE=IB Key| Variable | Description | Default |
|---|---|---|
TWS_USERID |
IB account username | required |
TWS_PASSWORD |
IB account password | required |
TRADING_MODE |
live, paper, or both |
live |
TWS_USERID_PAPER |
Paper account username (dual mode) | $TWS_USERID |
TWS_PASSWORD_PAPER |
Paper account password (dual mode) | $TWS_PASSWORD |
| Variable | Description | Default |
|---|---|---|
TWOFA_DEVICE |
2FA device name (IB Key, Mobile Authenticator app) |
— |
TWOFACTOR_CODE |
TOTP base32 secret (for automated code entry) | — |
TWOFA_TIMEOUT_ACTION |
restart or exit on 2FA timeout |
restart |
TWOFA_EXIT_INTERVAL |
Seconds to wait for 2FA approval | 180 |
RELOGIN_AFTER_TWOFA_TIMEOUT |
yes to retry login on timeout |
yes |
| Variable | Description | Default |
|---|---|---|
TWS_ACCEPT_INCOMING |
accept, reject, or manual |
accept |
TWS_MASTER_CLIENT_ID |
Master API client ID | — |
READ_ONLY_API |
yes or no |
— |
BYPASS_WARNING |
yes to bypass all order precaution warnings |
— |
ALLOW_BLIND_TRADING |
yes or no |
— |
EXISTING_SESSION_DETECTED_ACTION |
primary, secondary, primaryoverride |
primary |
| Variable | Description | Default |
|---|---|---|
AUTO_RESTART_TIME |
Daily auto-restart time (e.g., 05:05 PM) |
— |
AUTO_LOGOFF_TIME |
Auto-logoff time (e.g., 11:45 PM) |
— |
TWS_COLD_RESTART |
Sunday cold restart time, 24h format (e.g., 09:00) |
— |
| Variable | Description | Default |
|---|---|---|
JAVA_HEAP_SIZE |
JVM heap size in MB | 768 |
VNC_SERVER_PASSWORD |
Enable VNC with this password | disabled |
IBCTL_COMMAND_PORT |
TCP command server port | 7462 |
IBCTL_LOG_LEVEL |
debug, info, warn, error |
info |
Docker secrets are supported: any variable can use _FILE suffix to read from a file (e.g., TWS_PASSWORD_FILE=/run/secrets/ib_password).
ibctl exposes an IBC-compatible TCP command server (default port 7462):
echo "STOP" | nc localhost 7462
echo "RESTART" | nc localhost 7462
echo "RECONNECTDATA" | nc localhost 7462
echo "RECONNECTACCOUNT" | nc localhost 7462
echo "ENABLEAPI" | nc localhost 7462Wire protocol is identical to IBC — line-based, COMMAND\n → OK message\n or ERROR message\n.
- Login automation (IB API mode selection, trading mode, credentials, login button)
- 2FA device selection (IB Key, Mobile Authenticator)
- 2FA via IB Key mobile push (wait for approval, timeout with retry)
- 2FA via TOTP code (oathtool integration, configurable provider)
- Session conflict handling (primary/secondary/primaryoverride)
- Post-login API configuration via Global Configuration dialog
- Master Client ID
- Read-Only API
- Order precaution bypasses (all 9 checkboxes)
- Auto-restart / auto-logoff time
- Dialog auto-dismissal (paper trading warning, SSL reconnect, version notice, tip-of-day)
- Dual mode (live + paper simultaneously)
- IBC-compatible TCP command server (STOP, RESTART, RECONNECTDATA, RECONNECTACCOUNT, ENABLEAPI)
- TOML config file + env var configuration with Docker secrets support
- SIGTERM/SIGINT graceful shutdown
- VNC support for remote viewing
- Sunday cold restart (weekly full re-auth, mirrors IBC's ColdRestartTime)
- Connection loss recovery (re-login dialog auto-handled)
- Daily auto-restart recovery (handler state reset)
- AT-SPI accessibility tree fallback (v2)
- Built-in TOTP generation (v3, currently shells out to oathtool)
- OCR verification (v2)
- API port override
- Trusted API client IPs configuration
- Save TWS settings on schedule
- Full 27+ IBC dialog handler coverage
See docs/architecture.md for detailed design documentation.
Requires Rust 1.75+ and JDK 17+:
# Build Rust binary
cargo build --release
# Build Java agent
cd agent
javac --release 17 -d target/classes src/main/java/ibctl/agent/*.java
jar cfm target/ibctl-agent.jar src/main/resources/META-INF/MANIFEST.MF -C target/classes .Or use the multi-stage Docker build (no local toolchain needed):
docker build -t ibctl .MIT — same as gnzsnz/ib-gateway-docker.