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

> Deploy the AI Hedge Fund with Docker using a complete containerization guide. Build the Python 3.11-slim image and orchestrate services with docker-compose for LLM integration.

- Repository: [Virat Singh/ai-hedge-fund](https://github.com/virattt/ai-hedge-fund)
- Tags: how-to-guide
- Published: 2026-03-09

---

**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`](https://github.com/virattt/ai-hedge-fund/blob/main/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:
   ```bash
   git clone https://github.com/virattt/ai-hedge-fund.git
   cd ai-hedge-fund
   ```

3. Configure your environment variables:
   ```bash
   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.

```dockerfile
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`](https://github.com/virattt/ai-hedge-fund/blob/main/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`](https://github.com/virattt/ai-hedge-fund/blob/main/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`](https://github.com/virattt/ai-hedge-fund/blob/main/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:

```bash
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:

```bash

# 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:

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

```

### Running Historical Backtests

Validate strategies against historical data using the backtester service:

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

```

The backtester invokes [`src/backtester.py`](https://github.com/virattt/ai-hedge-fund/blob/main/src/backtester.py) and outputs a detailed performance report.

### Using the Embedded Ollama Service

To run the bundled Ollama container independently:

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

```

Then reference it in subsequent commands:

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

```

## Common Docker Commands and Examples

While the [`run.sh`](https://github.com/virattt/ai-hedge-fund/blob/main/run.sh) script provides convenience wrappers, you can invoke Docker Compose directly for advanced use cases.

### Direct Compose Commands

```bash

# 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`:

```bash
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`](https://github.com/virattt/ai-hedge-fund/blob/main/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`](https://github.com/virattt/ai-hedge-fund/blob/main/src/main.py) for trading and [`src/backtester.py`](https://github.com/virattt/ai-hedge-fund/blob/main/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`](https://github.com/virattt/ai-hedge-fund/blob/main/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`](https://github.com/virattt/ai-hedge-fund/blob/main/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.