Installing & Starting VolNinja

VolNinja runs on your own machine — a Mac, a Windows PC, a Linux box, or a small cloud server (VPS) you control. That is what keeps your trading data and your IBKR connection private: they live with you, and the cloud only handles your login and billing. See How VolNinja works for the full picture.

There are two ways to install it:

• VolNinja Desktop — an app for Mac and Windows. You download one file, install it like any other app, and VolNinja runs quietly in your menu bar or system tray. Nothing else to install. This is the recommended path for almost everyone.
• Docker — the advanced path, for a cloud server (VPS), Linux, an Intel Mac, or anyone who prefers running VolNinja from a terminal, in an isolated environment.

This page covers both, then the one-time step they share: connecting your machine to your account. When you are done, head to Connecting IBKR.

Before you start

1. An active VolNinja subscription or trial, with a verified email. The desktop download and the Docker install command are both unlocked once your email is verified and your subscription or trial is active. If you have not signed up yet, start with Account & billing.
2. IBKR Gateway or TWS. VolNinja trades through Interactive Brokers, so you will need IBKR's Gateway or Trader Workstation running on the same machine. You can install it now or right after — the walkthrough is in Connecting IBKR.

Which path should I choose?

If you have an Apple Silicon Mac or a Windows PC and you are happy trading while your computer is on, choose VolNinja Desktop. Everything else points to Docker.

Download VolNinja Desktop

You can download the app from either of two places, whenever you need it:

• Your welcome page at volninja.com/welcome, in the Install VolNinja on your machine step.
• Your account page at volninja.com/account, in the Install VolNinja card — this one stays there permanently, so it is where you go to install VolNinja on a second machine later.

Click Download for macOS or Download for Windows.

Install on a Mac

VolNinja Desktop is built for Apple Silicon Macs (M1 or newer). On an Intel Mac, use the Docker path instead.

1. Open the downloaded file, then drag VolNinja into your Applications folder.
2. Open VolNinja from Applications. VolNinja is signed and approved by Apple — macOS only asks the usual one-time "downloaded from the Internet, are you sure you want to open it?" question. Click Open.
3. VolNinja lives in your menu bar, not the Dock — look for the VolNinja icon at the top right of your screen. Its VolNinja window opens the first time you launch it.
4. It starts itself. The first start is the slowest, because VolNinja sets up its own private database. You are running when Engine in the VolNinja window turns green.

Install on Windows

VolNinja Desktop is built for 64-bit Windows 10 and 11 (Intel or AMD).

1. Run the downloaded setup file. The installer is digitally signed, so it should start straight away. If Windows still shows "Windows protected your PC", click More info, then Run anyway — that only happens while a new version is still building its reputation with Microsoft.
2. Follow the installer, then launch VolNinja.
3. VolNinja lives in your system tray, next to the clock — you may need to click the small arrow (^) to see hidden icons. Its VolNinja window opens the first time you launch it.
4. It starts itself. The first start is the slowest, because VolNinja sets up its own private database. You are running when Engine in the VolNinja window turns green.

The VolNinja window

The small VolNinja window is your control panel on the desktop app. Open it any time from the menu bar / tray icon → Open Status.

• Open Trading App — opens the trading app in your browser. This is where you actually trade.
• Check for Updates… — updates VolNinja in place, without downloading anything yourself. If you are already on the newest version, it tells you so.
• Engine — whether VolNinja itself is running and healthy. Green is what you want.
• IBKR — your broker connection at a glance: Connection, Live, Paper, and Market data. All grey until you set up IBKR Gateway or TWS, which is the next article: Connecting IBKR.
• Start Engine / Stop Engine / Restart Engine — manual control, rarely needed.
• Open Logs — opens VolNinja's log files, useful if support asks for them.
• Start at login — have VolNinja start automatically when you sign in to your computer.
• Set up / pair this machine — shown only until this machine is connected to your account (next section).

The menu bar / tray icon carries the same actions, plus Open Setup and Quit. The icon itself is a live status light: green when everything is running, amber while starting, red when something needs attention.

Check for Updates… stays greyed out, labelled Check for Updates… (pair first), until this machine is connected to your account — updates are tied to your subscription, so VolNinja needs to know whose install it is. Connecting it is the next section.

Connect it to your account

Both install paths finish the same way: a one-time pairing that links this machine to your VolNinja account. Nothing to copy, no tokens — you approve it in your browser.

On the desktop app, the VolNinja Setup page opens in your browser by itself the first time VolNinja comes up healthy. You can reopen it any time from the menu bar / tray icon → Open Setup, or from the Set up / pair this machine button in the VolNinja window.

1. On the Connect to VolNinja Cloud card, click Connect to VolNinja Cloud.
2. A short code appears. Click Open approval page — it opens a tab where you are signed in to your VolNinja account — and confirm that the code matches.
3. The card switches to Paired, and an Open trading app button appears.

Below it, Local status shows the two things that matter: Local engine and Cloud tunnel. Once both are healthy and the card says Paired, you can reach your trading app from any browser, on any device, by signing in to your account.

Pairing is covered in more detail in Device pairing.

Advanced: install with Docker

Use this path for a cloud server (VPS), Linux, an Intel Mac, or if you prefer running VolNinja from a terminal, in an isolated environment. VolNinja ships as a self-contained package that Docker runs for you — you never install trading software piece by piece.

Extra prerequisite

Docker Desktop. Download the free version for your platform from docker.com, install it, and launch it. When the whale icon in your menu bar or system tray stops animating, Docker is ready. On Windows, Docker Desktop also sets up WSL2 for you (more on that below). On Linux, Docker Engine plus the Docker Compose plugin works too.

Get your personal install command

Open your welcome page at volninja.com/welcome or your account page at volninja.com/account, and expand Advanced: install with Docker (VPS / headless). Copy the one-line install command shown there with the copy button.

This command is personal to you — it carries a private download credential tied to your subscription. Treat it like a password and do not share it.

The command looks like this (your credential replaces the …):

curl -fsSL https://volninja.com/install.sh | VOLNINJA_PULL_USER=appliance VOLNINJA_PULL_PASS=… bash

Running it installs VolNinja, starts it, and leaves you with a small volninja command for everyday control. Pick your platform below.

Mac

1. Install Docker Desktop for Mac and launch it. Apple Silicon and Intel Macs are both supported — the right version is selected automatically.

2. Open the Terminal app (Applications → Utilities, or search "Terminal" with Spotlight).

3. Paste your personal install command and press Return. The first run downloads VolNinja before starting it.

4. When it finishes, VolNinja is already running. Confirm it with:

   volninja status
   

Windows

On Windows, this path runs VolNinja inside WSL — a lightweight Linux environment that Docker Desktop sets up for you. You run the install command in a WSL terminal, not in PowerShell.

1. Install Docker Desktop for Windows. During setup, keep the Use WSL 2 option enabled, then launch Docker Desktop.

2. If you have never used WSL, open PowerShell and run wsl --install, then restart if prompted. This gives you an Ubuntu Linux terminal.

3. Open your WSL terminal — search the Start menu for Ubuntu (or WSL).

4. Paste your personal install command and press Enter. The first run downloads VolNinja before starting it.

5. Confirm it is running:

   volninja status
   

Linux

1. Install Docker Engine and the Docker Compose plugin (Docker Desktop for Linux works too). Start Docker, and make sure your user is allowed to run it without sudo.

2. Open a terminal.

3. Paste your personal install command and press Enter. The first run downloads VolNinja before starting it.

4. Confirm it is running:

   volninja status
   

VPS (a cloud server)

Running VolNinja on a small cloud server (a VPS) lets it trade around the clock without depending on your laptop being open. The setup is the same as Linux, with one difference at the end: because a server has no desktop browser, you connect it to your account from the command line.

1. On the VPS (Ubuntu or Debian works well), install Docker Engine and the Docker Compose plugin, and start Docker.

2. Connect to the server over SSH.

3. Paste your personal install command and press Enter.

4. Confirm it is running with volninja status.

5. Connect it to your account from the terminal:

   volninja pair --headless
   

   Follow the short code and link it prints on your own computer to approve the connection.

Confirm it is running

Two commands tell you everything about the state of a Docker install.

• volninja status lists each part of VolNinja and whether it is running and healthy, shows the folder VolNinja lives in, and reports whether the machine is connected to your account yet.
• volninja doctor checks the prerequisites for you — that Docker is installed and running, and that VolNinja is responding — and flags anything that is missing.

When status shows the services running and healthy, VolNinja is up and ready to connect.

Pair a Docker install

On a Mac, Windows, or Linux desktop, run:

volninja pair

This opens the same VolNinja Setup page in your browser, at http://localhost:8037/setup. Follow the three steps in Connect it to your account above. On a headless VPS, use volninja pair --headless instead, as shown earlier.

Everyday control

With a Docker install, you manage VolNinja with a few simple commands:

Using your own database

VolNinja keeps all of your data in a Postgres database that ships with the appliance. You do not need to set this up, and most people never change it.

If you already run your own Postgres and would rather VolNinja used that, open ~/volninja/.env in a text editor and add a line pointing at your server:

DATABASE_URL=postgresql+psycopg2://user:password@host.docker.internal:5432/autotrader2

Use host.docker.internal for a database on the same computer as VolNinja — 127.0.0.1 there would mean "inside VolNinja's own container", not your machine. For a database on another machine, use its hostname or IP address.

Then apply it:

volninja restart

A few things worth knowing:

• The database does not have to exist yet. VolNinja creates it on the next start. The server does have to be running, and the user in the address needs permission to create databases.
• VolNinja reserves two more names on that server. Alongside the database you name, it uses <name>_volninja_prev and <name>_volninja_restore — creating, renaming and dropping them while it backs up and restores. The name you pick must be lowercase letters, digits and underscores, must not start with a digit, and must be at most 46 characters long.
• Nothing is copied over. Pointing VolNinja at a different database gives you a fresh, empty one. To move your existing data, take a backup first with volninja backup, switch, then volninja restore.
• If VolNinja cannot reach the database, it will not start. It never quietly falls back to the bundled one, because that would split your trading history across two places. Run volninja doctor to see what it found.
• Use a database on your own machine or local network. VolNinja talks to its database constantly, and a database reached over the internet will make it slow and unreliable.
• Restoring a backup needs the database to itself, so close any other program connected to it first — including your own psql session.

You can go back to the bundled database at any time by removing the DATABASE_URL line and running volninja start again. The bundled database keeps your old data, so switching back restores what was there before you switched away.

Keeping VolNinja up to date

You never have to go looking for updates. When a new version is available, VolNinja tells you with a banner across the top of the trading app.

On the desktop app, updating is one click: press Update now in that banner, or Check for Updates… in the VolNinja window or the menu bar / tray menu. VolNinja fetches the new version, installs it over itself, and restarts — you do not download or run an installer. Your positions, templates, strategies, and history are untouched. (If you are on an older desktop version that predates in-app updating, the banner offers Download update instead: download it and run the installer over your existing copy, once. After that, updates are one click.)

With a Docker install you run volninja update. Both paths are covered in Updating VolNinja.

Next steps

VolNinja is installed, running, and connected to your account. Now:

• Connect IBKR — get IBKR Gateway or TWS ready and confirm the connection.
• Take the tour — a quick walk through the main screens before your first trade.