How to Deploy the AI Hedge Fund with Docker: Complete Containerization Guide

Deploy the AI Hedge Fund with Docker by building the lightweight Python 3.11-slim image defined in docker/Dockerfile and orchestrating services via docker-compose.yml, which supports both external Ollama endpoints and an embedded LLM server.

The virattt/ai-hedge-fund repository provides a production-ready containerization setup that packages the AI-driven trading system into a reproducible environment. This guide explains how to deploy the AI Hedge Fund with Docker using the official container definitions and helper scripts found in the docker/ directory.

Prerequisites

Before deploying, ensure Docker Desktop or Docker Engine is installed on your system. You will also need a local copy of the repository and API keys for the LLM providers you plan to use.

1. Install Docker from the official site: https://www.docker.com/get-started

2. Clone the repository:

   git clone https://github.com/virattt/ai-hedge-fund.git
   cd ai-hedge-fund

3. Configure your environment variables:

   cp .env.example .env
   # Edit .env to set OPENAI_API_KEY, OLLAMA_BASE_URL, or other required keys
   

Understanding the Container Architecture

The containerization strategy uses a multi-layered approach to optimize build caching and minimize image size.

The Dockerfile Blueprint

The docker/Dockerfile defines a Python 3.11-slim based image that installs Poetry 1.7.1 for dependency management. The build process copies dependency manifests first to leverage Docker layer caching, then installs packages without creating a virtual environment inside the container.

FROM python:3.11-slim
WORKDIR /app

# Install Poetry (exact version for reproducibility)

RUN pip install poetry==1.7.1

# Copy only the dependency manifests first (caches layers)

COPY pyproject.toml poetry.lock* /app/

# Install dependencies without a virtualenv

RUN poetry config virtualenvs.create false \
    && poetry install --no-interaction --no-ansi

# Copy the rest of the source code

COPY . /app/

# Default entrypoint – overridden by Docker Compose or the helper script

CMD ["python", "src/main.py"]

As implemented in virattt/ai-hedge-fund, the PYTHONPATH is set to /app to ensure the package can be imported from anywhere inside the container.

Service Orchestration Overview

The docker/docker-compose.yml file defines several distinct services tailored to different operational modes:

• hedge-fund: Runs the live AI-driven trading loop via src/main.py
• hedge-fund-reasoning: Same as above but adds the --show-reasoning flag for LLM transparency
• hedge-fund-ollama: Forces usage of the bundled Ollama container with the --ollama flag
• backtester: Executes the historical back-testing engine (src/backtester.py)
• backtester-ollama: Back-tester variant configured for local LLM inference
• ollama: Optional bundled LLM server activated via the embedded-ollama profile, exposing port 11434 and persisting data in a named volume

Step-by-Step Deployment Workflow

Navigate to the Docker helper directory to begin the deployment process.

Building the Container Image

Use the provided helper script to build the image with all dependencies:

cd docker
./run.sh build

On Windows, use run.bat build instead. This command executes docker compose build using the Dockerfile described above, compiling the Python environment with Poetry.

Running the Live Hedge Fund

Execute the main trading loop by specifying tickers and optional flags:

# Basic run using remote Ollama endpoint (set OLLAMA_BASE_URL in .env)

./run.sh --ticker AAPL,MSFT,NVDA main

Key flags include:

• --ollama: Force use of the bundled Ollama service profile
• --show-reasoning: Display the LLM's internal decision-making process
• --start-date and --end-date: Limit the trading window (format: YYYY-MM-DD)

Example with bundled Ollama:

./run.sh --ticker AAPL,MSFT,NVDA --ollama main

Running Historical Backtests

Validate strategies against historical data using the backtester service:

./run.sh --ticker AAPL,MSFT,NVDA \
         --start-date 2024-01-01 \
         --end-date 2024-03-01 backtest

The backtester invokes src/backtester.py and outputs a detailed performance report.

Using the Embedded Ollama Service

To run the bundled Ollama container independently:

docker compose --profile embedded-ollama up -d ollama

Then reference it in subsequent commands:

./run.sh --ticker AAPL,MSFT,NVDA \
         --ollama-base-url http://localhost:11434 main

Common Docker Commands and Examples

While the run.sh script provides convenience wrappers, you can invoke Docker Compose directly for advanced use cases.

Direct Compose Commands

# Build and run the live fund

docker compose up --build hedge-fund

# Run the backtester

docker compose up --build backtester

# Start only the Ollama container

docker compose --profile embedded-ollama up ollama

Environment Variable Overrides

Pass configuration directly without modifying .env:

export OLLAMA_BASE_URL=http://my-ollama-host:11434
docker compose run --rm hedge-fund python src/main.py --ticker AAPL,MSFT

The container automatically picks up environment variables defined in your shell or the .env file mounted at runtime.

Summary

• The Dockerfile at docker/Dockerfile uses Python 3.11-slim and Poetry 1.7.1 to create a lightweight, reproducible image with PYTHONPATH=/app.
• Docker Compose orchestrates multiple services including the live trading loop (hedge-fund), backtesting (backtester), and an optional embedded LLM server (ollama).
• The run.sh helper script simplifies common tasks like building images and executing trades with appropriate flags.
• Configuration is managed through environment variables in .env, with support for external or containerized Ollama endpoints via OLLAMA_BASE_URL.
• All source code is mounted or copied into /app, with entry points at src/main.py for trading and src/backtester.py for historical analysis.

Frequently Asked Questions

What base image does the AI Hedge Fund Docker container use?

The container uses python:3.11-slim as specified in docker/Dockerfile. This minimal base image reduces the attack surface and image size while providing a complete Python 3.11 runtime environment required by the project's Poetry dependencies.

Can I use my own Ollama server instead of the embedded one?

Yes. Set the OLLAMA_BASE_URL environment variable in your .env file or export it in your shell before running commands. If this variable is set, the hedge fund services will connect to your specified endpoint rather than launching the bundled Ollama container defined in the embedded-ollama profile.

How do I view the LLM's reasoning during trade decisions?

Use the hedge-fund-reasoning service or pass the --show-reasoning flag via the helper script: ./run.sh --ticker AAPL --show-reasoning main. This executes src/main.py with the reasoning flag enabled, printing the AI's step-by-step analysis to the container logs.

Where are the Ollama models stored when using the embedded service?

The docker-compose.yml defines a named volume called ollama_data that persists the model cache outside the container. This ensures downloaded LLMs survive container restarts and are not re-downloaded on every deployment, with data stored in Docker's volume management system rather than the container's ephemeral filesystem.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}