Home

TWS Headless — Wiki

TWS Headless is an asyncio-native trading engine for Interactive Brokers. It connects to TWS or IB Gateway, manages a fleet of independently-funded trading plugins, and exposes a Unix-socket CLI (ibctl) for live control.

---

Pages

Page	Description
Theory of Operation	How the system works end-to-end: startup, market data, plugin execution, order lifecycle, state persistence
CLI — Task Guide	How to do common tasks from the command line: fund plugins, transfer assets, place orders, manage plugins
Plugin Design	Concise guide to writing plugins: lifecycle, streams, signals, callbacks, holdings, MessageBus, full example
Plugin Manual	Complete authoring reference: every method, every field, every option

---

Quick Architecture

IB TWS / Gateway
      │  TCP
      ▼
 AsyncIBTransport          ← single asyncio reader coroutine
      │
      ▼
   Portfolio               ← positions, orders, account, P&L
      │
      ▼
 PluginExecutive           ← loads plugins, routes signals → orders
  ┌───┴───┐
Plugin   Plugin  ...       ← isolated funding, state, instruments
      │
      ▼
  DataFeed                 ← tick/bar buffers, stream ref-counting
      │
      ▼
 MessageBus                ← pub/sub between plugins
      │
      ▼
 CommandServer             ← Unix socket → ibctl CLI

---

Key Concepts at a Glance

Plugins are the unit of strategy. Each plugin has its own cash balance, position inventory, and state. The engine routes signals from plugins to IB orders.

Holdings track what a plugin "owns" — cash and positions — independently of the real IB account. They persist across restarts via SQLite.

Transfers move cash or positions between plugins bookkeeping-side; no IB trades are placed.

Signals (TradeSignal) are returned from calculate_signals(). The executive reconciles signals across plugins and sends orders to IB.

Streams are reference-counted. Multiple plugins can subscribe to the same symbol; IB sees only one subscription.

MessageBus lets plugins share indicators, alerts, and signals without coupling.