Connecting to Interactive Brokers

Tempest connects to Interactive Brokers through the Trader Workstation (TWS) application or IB Gateway to read account and market data and — when you choose to enable it — to place and manage orders. This page explains how to set up and verify that connection.

Quick Start

Tempest attempts to connect automatically a moment after it launches. For the connection to succeed, you must have all three of the following in place:

1. TWS or IB Gateway is running and logged in with your Interactive Brokers account.
2. The API socket is enabled in TWS — see Enable the API Socket below.
3. Tempest is pointed at the matching port — the defaults are 7497 (TWS paper) or 7496 (TWS live); IB Gateway uses 4002 (paper) or 4001 (live).

When all three are true, the broker status in the Assisted Trading panel reads ● Connected.

Note: Tempest and the data feed it shows are informational only. Connecting to Interactive Brokers, and any orders you choose to place, are entirely at your own direction and risk. Trading futures carries a substantial risk of loss.

Enable the API Socket

This is the single most common reason a connection fails. Even with TWS running and logged in, the API socket is a separate setting that must be turned on.

1. In TWS (or IB Gateway), open Global Configuration from the menu (in TWS this is under the Edit menu; some versions place it under File).
2. Select the API section, then Settings.
3. Check "Enable ActiveX and Socket Clients".
4. Leave "Read-Only API" unchecked if you intend to place orders (required for assisted trading).
5. Confirm the Trusted IPs list includes 127.0.0.1 (the default for a local TWS).
6. Note the Socket port shown here — it must match the port you set in Tempest.
7. Click OK.

Warning: TWS can silently turn "Enable ActiveX and Socket Clients" back off after it auto-updates. If Tempest was connecting fine and suddenly shows ○ Disconnected while TWS is still logged in, re-check this setting first. See Troubleshooting.

📷 Screenshot: The TWS Global Configuration → API → Settings screen with "Enable ActiveX and Socket Clients" checked and the Socket port visible.

The TWS Connection Dialog

Open the connection settings from the menu: Tools → TWS Connection….

📷 Screenshot: Tempest's "TWS Connection" dialog showing the Host field, Port spin box with the four quick-pick port buttons, and the two client ID spin boxes.

The dialog edits four values:

Each port quick-pick button sets the Port field to a standard value with one click:

Click Save to store your settings, or Cancel to discard them. If you set both client IDs to explicit numbers and they match, Tempest warns you and does not save.

Note: Saving does not force an immediate reconnect — your changes take effect on the next reconnect. Either restart Tempest, or use Tools → Refresh Orders Cache to nudge the broker connection.

Auto-Connect on Launch

Shortly after Tempest starts, it tries to connect to TWS or IB Gateway in the background using your saved host, port, and client ID. The broker status walks through these states:

If no connection is established within about 10 seconds, Tempest shows a dismissible warning titled "Interactive Brokers Not Connected". This window:

• Reminds you that TWS / IB Gateway must be launched and logged in, that "Enable ActiveX and Socket Clients" must be checked, and that the socket port must match the port Tempest is currently using (the exact port is shown in the message).
• Offers Retry Now and Continue Anyway buttons.
• Does not block the rest of Tempest — you can keep viewing signals and changing settings while it is open.

Tempest keeps retrying in the background even if you dismiss the warning. As soon as TWS connects, the status flips to ● Connected and the warning closes on its own.

The Connection Status Indicator

The broker connection indicator lives in the Assisted Trading panel, next to the Broker: label.

Note: The connection state shown at the bottom of the main window is the signal feed status — that is a different connection from the broker. The broker (Interactive Brokers) status is the Broker: indicator described above. They can be in different states: the signal feed can be connected while the broker is not, and the reverse.

Two Separate Connections

Tempest's own connection and the assisted trading engine's connection are two distinct sessions to TWS, each with its own client ID (a number from 0 to 999 that TWS uses to keep sessions apart):

• Tempest client ID — used for account data and chart market data.
• AutoTrader client ID — used by the assisted trading engine to place and manage orders.

Left on their defaults, Tempest randomizes its own ID at startup and the assisted trading engine uses the next number up. You only need to set fixed IDs if you run more than one copy of Tempest, or want stable IDs to recognize each session in TWS. If you pin them, give each a different value, for example Tempest 50 and AutoTrader 51.

Running TWS or IB Gateway on Another Computer

If TWS or IB Gateway runs on a separate machine (for example a VPS), set the Host field to that machine's IP address or hostname, and make sure:

• The machine is reachable over the network.
• Its firewall allows connections on the port you configured.
• That machine's Trusted IPs list (under the same API settings) includes the address Tempest connects from.
• You comply with Interactive Brokers' own terms for where and how TWS / Gateway may run.

Common Issues

TWS / IB Gateway is not running

Symptom: The broker status stays on ○ Disconnected.

Fix: Launch TWS or IB Gateway and log in. Tempest cannot connect if the target application is not running. If it is running but Tempest still cannot reach it, double-check the port — you may be running Gateway (4001/4002) while Tempest is set to a TWS port (7496/7497), or vice versa.

"Enable ActiveX and Socket Clients" is off

Symptom: ○ Disconnected even though TWS is logged in.

Fix: Re-open the API settings in TWS, confirm "Enable ActiveX and Socket Clients" is checked and "Read-Only API" is unchecked (for order placement), and that Trusted IPs still contains 127.0.0.1. This setting can be reset by TWS updates. After re-enabling it, the broker status should return to ● Connected within a few seconds; if not, restart Tempest.

"Port in use" but nothing is actually using it

Symptom: TWS reports something like "API server failed to start since specified port 7497 is in use by another app", yet nothing appears to be listening on that port.

Cause: On Windows, components such as Hyper-V, WSL2, or Docker Desktop can reserve blocks of TCP ports at startup. Windows then refuses to let any application — including TWS — use a port inside one of those reserved blocks, and the error message misleadingly blames "another app." This is an environment condition, not a Tempest bug.

You have two ways to resolve it:

• Use a different port. In Tempest, open Tools → TWS Connection…, type an unused port into the Port field (for example 7671 or 17497), and click Save. In TWS, change the Socket port (under API → Settings) to the same value and click OK. The two must match.
• Free up the standard port. This involves an administrator command and a reboot to carve the single port back out of the reserved range. Step-by-step instructions are in Troubleshooting.

Connection keeps cycling (connect, drop, reconnect)

Symptom: The status flickers between ◐ Connecting…, ● Connected, and ○ Disconnected repeatedly.

Cause: This typically happens when Tempest is launched before TWS has finished starting. TWS accepts the connection, then closes it while still loading, which can leave the client ID briefly tied up on the TWS side. Current Tempest versions clean up the prior session before each retry so the reconnect succeeds once TWS is ready.

Fix: Whenever possible, start TWS or IB Gateway first, then launch Tempest. If cycling persists, fully close and reopen TWS, then restart Tempest. Keeping Tempest up to date ensures you have the latest reconnect handling.

Assisted trading engine cannot connect

Symptom: The Assisted Trading panel shows "Status: WAITING — no broker connection" even though the Broker: indicator says ● Connected.

Cause: The assisted trading engine connects with its own client ID. If that ID collides with another session, its connection can fail while Tempest's main connection is fine.

Fix: Open Tools → TWS Connection… and give the Tempest client ID and AutoTrader client ID two different fixed values, then Save and restart Tempest. Alternatively, fully restart TWS to clear any leftover sessions, then restart Tempest.

For more diagnostics, see Troubleshooting.

Port Reference

These are Interactive Brokers' standard defaults. If you changed the Socket port in TWS, use that value in Tempest instead. Your host, port, and client ID choices are saved automatically — there is no file to edit by hand; use the Tools → TWS Connection… dialog.

Related Pages

• Assisted Trading — How the assisted trading engine uses its connection to place and manage orders.
• Positions & Orders — Viewing account positions and working orders.
• Licensing & Tiers — Which tiers include assisted trading.
• Troubleshooting — Step-by-step fixes for connection, port, and signal-feed issues.