Brokers
↳ Recommended (Local Agent)

Recommended — Local Agent

This method installs a small background application (the Ordertune Agent) on your machine alongside IB Gateway Classic and IBC (IBController). Once configured:

  • IB Gateway starts automatically (no manual login required)
  • IBC handles the daily IBKR re-authentication
  • The Ordertune Agent maintains a persistent connection to Ordertune and executes orders automatically

You do not need to be at your computer. Orders execute 24/7 without any browser involvement.

This setup takes about 30 minutes to configure the first time. After that, it runs entirely unattended — including Sunday restarts when IBKR resets sessions.

How it works

Ordertune Dashboard
       ↓  (you click Confirm)
Ordertune Server
       ↓  (publishes order via Supabase Realtime)
Ordertune Agent  ←  running on your machine
       ↓  (TWS socket API, port 4001/4002)
IB Gateway Classic  ←  also on your machine
       ↓
IBKR

The Ordertune Agent opens an outbound connection to Ordertune's servers. No ports need to be opened on your router or firewall. Your machine initiates the connection; it cannot be reached from the outside.

Prerequisites

  • A machine that stays on most of the time (desktop, NAS, Raspberry Pi, VPS, or similar)
  • Windows, macOS, or Linux (all supported)
  • IB Gateway Classic (not the newer IB Gateway that uses the CP Web API)
  • IBC (IBController) — automates IB Gateway login
  • An active Ordertune subscription with 2FA enabled

Step 1 — Install IB Gateway Classic

⚠️

Download IB Gateway Classic, not the standard IB Gateway. The Classic version uses the TWS socket API (ports 4001/4002) required by the Ordertune Agent.

Download from interactivebrokers.com/en/trading/ibgateway-stable.php (opens in a new tab). Select the offline installer for your platform.

Install IB Gateway Classic but do not configure it yet. IBC will manage the configuration.

Step 2 — Install IBC (IBController)

IBC is a free open-source tool that automates IB Gateway login and handles the daily restart.

Download IBC

Download the latest release from github.com/IbcAlpha/IBC/releases (opens in a new tab). Download the .zip for your platform.

Extract

Extract the contents to a permanent location, for example:

  • Windows: C:\IBC\
  • macOS/Linux: ~/IBC/

Configure IBC

In the extracted folder, open config.ini (or IBCAlpha.ini depending on version). The key settings:

# Your IBKR login credentials
IbLoginId=YOUR_IBKR_USERNAME
IbPassword=YOUR_IBKR_PASSWORD
 
# For paper trading, set to "paper" instead of "live"
TradingMode=live
 
# Where IB Gateway is installed
IBDir=C:\Jts\ibgateway\<version>
 
# Automatically handle 2FA prompts (requires IBKR Mobile app)
AcceptIncomingConnectionAction=accept

Configure the start script

IBC includes start scripts (StartGateway.bat on Windows, StartGateway.sh on macOS/Linux). Open the script and set the TWS_MAJOR_VRSN to match your installed IB Gateway version.

IBC automatically accepts the IBKR 2FA prompt via the IBKR Mobile app. Make sure the IBKR Mobile app is installed on your phone — IBC will trigger the push notification automatically when restarting.

Step 3 — Enable the TWS Socket API in IB Gateway

Start IB Gateway manually (first time only)

Run IB Gateway Classic once manually and log in. Go to Configure → Settings → API → Settings and enable:

  • Enable ActiveX and Socket Clients — check this box
  • Socket port — 4001 for live accounts, 4002 for paper accounts
  • Allow connections from localhost only — enabled (the agent runs on the same machine)

Save and close

After enabling the API, IBC will manage all future startups.

Step 4 — Download and configure the Ordertune Agent

Download the agent

Download the Ordertune Agent for your platform from the Ordertune Settings page (Settings → Broker → Interactive Brokers → Local Agent).

Download ordertune-agent-win.exe

Create config.json

In the same directory as the agent binary, create a file named config.json:

{
  "supabase_url": "https://your-project.supabase.co",
  "supabase_key": "your-anon-key",
  "user_id": "your-ordertune-user-id",
  "ibkr_port": 4001
}

You can copy the correct supabase_url, supabase_key, and user_id from the Ordertune Settings page when you select the Local Agent option.

For paper trading, set "ibkr_port": 4002.

Start the agent

Run the agent:

./ordertune-agent-linux   # Linux/macOS
ordertune-agent-win.exe   # Windows

The agent will print a connection status line. It connects to IB Gateway and registers with Ordertune.

Step 5 — Connect in Ordertune Settings

Open Settings

In Ordertune, go to Settings → Broker.

Select Interactive Brokers — Local Agent

In the broker selector, choose Interactive Brokers and then select the Local Agent (Recommended) option.

Toggle Paper Trading (optional)

Enable Paper Trading if connecting to your IBKR paper account. Make sure the agent's config.json also uses port 4002.

Save

Click Connect Broker. Ordertune will verify that your agent is online (heartbeat check within the last 2 minutes). The status badge will show Agent Online.

Step 6 — Auto-start on boot (optional but recommended)

For fully unattended operation, configure both IBC and the Ordertune Agent to start automatically when your machine boots.

IBC: Use Task Scheduler to run StartGateway.bat at startup.

Agent: Create a Scheduled Task that runs ordertune-agent-win.exe at startup (trigger: At log on, or At system startup).

Paper trading

To use paper trading:

  1. In IBC's config.ini, set TradingMode=paper (or create a separate IBC config for paper)
  2. In config.json for the agent, set "ibkr_port": 4002
  3. In Ordertune Settings, enable the Paper Trading toggle when connecting

Paper and live accounts require separate IB Gateway sessions (different ports). If you want both simultaneously, run two IBC instances on different ports.

How order execution works

When you click Confirm Buy or Confirm Sell:

  1. Ordertune's server publishes the order to a private Supabase Realtime channel
  2. The Ordertune Agent receives the order within milliseconds
  3. The agent places the order via the TWS socket API to IB Gateway Classic (same machine, port 4001/4002)
  4. IB Gateway forwards the order to IBKR
  5. The agent writes the result (order ID or error) back to Ordertune

Total roundtrip is typically under 2 seconds.

Agent status monitoring

The Ordertune Agent sends a heartbeat to Ordertune every 30 seconds. In Ordertune Settings, the broker status shows:

  • Agent Online — heartbeat received within the last 2 minutes
  • Agent Offline — no heartbeat in the last 2 minutes (agent or IB Gateway not running)

If the agent goes offline, orders will fail until it reconnects. The agent automatically reconnects after network interruptions.

Troubleshooting

"Trading agent is offline" → The Ordertune Agent is not running or cannot reach Ordertune's servers. Check that the agent process is running and that config.json credentials are correct.

Agent shows "Online" but orders fail → IB Gateway Classic is not running or the TWS API is not enabled. Start IB Gateway and verify the socket API settings (port 4001 or 4002).

IBC fails to log in → Your IBKR credentials in config.ini may be incorrect. Test by logging in manually. Also confirm the IBKR Mobile app is installed — IBC requires it for 2FA handling.

Agent starts but immediately disconnects → Check that IB Gateway Classic is fully started and logged in before starting the agent. The agent requires an active IB Gateway session on connect.

"Allow connections from localhost only" error → This setting in IB Gateway is correct. The agent runs on the same machine and connects via 127.0.0.1. No change needed.

↳ Quick Start (CP Gateway)↳ Pro Setup (OAuth)