Headless Setup: IB Gateway 10.41 + IBC 3.23.0 on Ubuntu 22.04 on an Azure VM

[wj109s5]

Headless Setup: IB Gateway 10.41 + IBC 3.23.0 on Ubuntu 22.04 on an Azure VM

After extensive testing on an Azure Ubuntu 22.04 VM, I’ve managed to get IB Gateway 10.41 fully headless under IBC 3.23.0.
Here’s what actually works — and what still feels buggy or undocumented.

1) Version mismatch in gatewaystart.sh

/opt/ibc/gatewaystart.sh still ships with:

TWS_MAJOR_VRSN=1019

That breaks immediately (“can’t find jars”).
Change it to match your install:

TWS_MAJOR_VRSN=1041 ... probably. You'll see why in a moment. This technically didn't work, but you might try 1040 as well.

2) Path rigidity

IBC assumes the classic directory structure:

~/Jts/1041/
~/ibc/config.ini

Any deviation causes startup or classpath errors. Installing Gateway without sudo preserves correct ownership and paths.

3) TOTP Notes (Unverified)

I found mentions of undocumented keys:

TwoFactorAuthMethod=TOTP
TwoFactorAuthTotpSecret=...

However — my success ACTUALLY came only from clicking the “IB Gateway 10.41” icon once via VNC and selecting “Mobile Authenticator App.” The initial screen I got was an error with a link to a log file. Close that and open the convenient icon on the desktop.

After that, headless runs worked perfectly. So treat TOTP config options as theoretical until confirmed.

4) Once fixed, gatewaystart.sh works fine

After correcting version and paths, it launches reliably and is safe to wrap in systemd for automation.

Summary

A working headless setup is possible — but only after:

Fixing TWS_MAJOR_VRSN

Using default folder layout

Doing one VNC login to store 2FA preference

Tested Nov 2025 on Azure Ubuntu 22.04, OpenJDK 17.
Posting here so others can reproduce or refine this further.

[rlktradewright]

Just some comments against each of your points:

1. Version mismatch

TWS_MAJOR_VRSN=1019 was correct when IBC 3.23.0 was released. The documentation makes clear that you need to set this to reflect the version of TWS that you want to run. Just because IBKR decide that the current stable version is now a later version doesn't mean that I should publish a new release.

Eventually I will publish a new release, and that will have TWS_MAJOR_VRSN set to whatever is the current stable version at the time.

2. Path rigidity

The TWS abd Gateway installers create a tree of folders under the top-level installation folder (Ie the Jts folder). The IBC scripts are aware of this structure, and it needs to be correct, otherwise they can't find things they need to find and they fail (as you've found).

There is absolutely no reason to want to change this structure. What you can do is put the Jts folder anywhere you like (sibject to permissions). What you can't do is change any of the folders underneath Jts, and why would you want to?

3. TOTP Notes

I don't know where you found those erroneous keys, but they are complete fictions. The only settings keys that IBC does anything with are the ones documented in config.ini.

If you add other keys to `config'ini', IBC will not object, but it will ignore them (though it will include them in the list of settings in the IBC log file).

The setting you need is:

SecondFactorDevice=Mobile Authenticator app

I should note that there is an issue at the moment where if you change this setting (for example to SecondFactorDevice=IB Key), next time you start IBC it won't work properly (I can't remermber the details, but I'll need to get this fixed soon). This is a result of IBKR changing how/where the list of 2FA options is presented, so IBC doesn't recognise it..In this situation, you need to do a manual login to TWS similar to what you described, and after that it will be ok.

4. Once fixed, gatewaystart.sh works fine

This isn't 'fixing', it's just following the instructions in the User Guide and configuring!...