# How to Run the FastAPI Server Separately from Background Workers in AI-Trader

> Learn to run the FastAPI server separately from background workers in AI-Trader. Guide shows how to manage independent API and background task execution for better control.

- Repository: [✨Data Intelligence Lab@HKU✨/AI-Trader](https://github.com/HKUDS/AI-Trader)
- Tags: how-to-guide
- Published: 2026-05-09

---

**To run the FastAPI server independently from background workers in AI-Trader, start the API with `uvicorn service.server.main:app` while ensuring the `AI_TRADER_BACKGROUND_TASKS` environment variable is unset, then launch background tasks separately via `python service/server/worker.py`.**

The HKUDS/AI-Trader repository implements a clean architectural separation between its HTTP API layer and long-running background processes. This design allows you to run the FastAPI server separately from background workers, optimizing resource allocation and improving system resilience for production deployments.

## Understanding the Entry Point Architecture

AI-Trader organizes its server logic into three distinct entry points that control process initialization:

- **[`service/server/main.py`](https://github.com/HKUDS/AI-Trader/blob/main/service/server/main.py)** – Boots the FastAPI application and optionally starts background tasks
- **[`service/server/worker.py`](https://github.com/HKUDS/AI-Trader/blob/main/service/server/worker.py)** – Runs only background tasks without initializing the HTTP server
- **[`service/server/routes.py`](https://github.com/HKUDS/AI-Trader/blob/main/service/server/routes.py)** – Defines `create_app()` to build the FastAPI instance and register routes

This modular structure, complemented by configuration in [`service/server/config.py`](https://github.com/HKUDS/AI-Trader/blob/main/service/server/config.py), ensures that CPU-intensive background operations never compete with latency-sensitive HTTP request handling.

## Controlling Background Tasks in the API Process

When you launch the FastAPI server using `uvicorn service.server.main:app`, the application executes a startup event handler (lines 56-84 in [`service/server/main.py`](https://github.com/HKUDS/AI-Trader/blob/main/service/server/main.py)). This handler checks for the environment variable `AI_TRADER_BACKGROUND_TASKS`.

If the variable is unset or empty, the startup code explicitly skips launching background tasks and logs the following message:

```python
logger.info(
    "API background tasks disabled. Run `python service/server/worker.py` "
    "to process prices, profit history, settlements, and market intel."
)

```

This check occurs at lines 78-82, ensuring that by default, the API process remains dedicated to HTTP request handling.

### Starting the FastAPI Server Without Workers

To ensure the API process never launches background tasks, explicitly unset the environment variable before starting uvicorn:

```bash
export AI_TRADER_BACKGROUND_TASKS=
uvicorn service.server.main:app --host 0.0.0.0 --port 8000

```

## Running the Standalone Worker Process

The [`service/server/worker.py`](https://github.com/HKUDS/AI-Trader/blob/main/service/server/worker.py) script provides a lightweight entry point that initializes the same database and cache connections as the main application but deliberately avoids creating the FastAPI app.

Instead, it immediately invokes `start_background_tasks(logger)` and blocks indefinitely using `await asyncio.Event().wait()` (lines 23-38). This keeps the process alive while handling price updates, profit-history pruning, and market-intel snapshots in isolation.

To start the worker:

```bash
python service/server/worker.py

```

## Production Deployment Configuration

For containerized deployments, create separate Docker images for each component to maintain strict process isolation.

**Dockerfile for the API:**

```dockerfile
FROM python:3.11-slim
WORKDIR /app
COPY . .
RUN pip install -r requirements.txt
ENV AI_TRADER_BACKGROUND_TASKS=
CMD ["uvicorn", "service.server.main:app", "--host", "0.0.0.0", "--port", "8000"]

```

**Dockerfile for the Worker:**

```dockerfile
FROM python:3.11-slim
WORKDIR /app
COPY . .
RUN pip install -r requirements.txt
CMD ["python", "service/server/worker.py"]

```

Orchestrate these containers using Docker Compose or Kubernetes, allowing you to scale the API layer horizontally without duplicating background work.

## Why Separation Matters

Running the FastAPI server separately from background workers delivers three operational advantages:

1. **Resource Isolation** – HTTP request handling requires low latency, while background tasks involve heavy database queries and external API calls. Separate processes prevent I/O contention.
2. **Independent Scaling** – You can deploy multiple uvicorn workers for the API while running a single dedicated worker process on a high-memory instance.
3. **Fault Tolerance** – A crash in a background task does not bring down the API server, and vice versa, improving overall system stability.

## Summary

- **Unset `AI_TRADER_BACKGROUND_TASKS`** when starting the FastAPI server to prevent the API process from launching background tasks.
- **Run `python service/server/worker.py`** in a separate terminal or container to handle price updates and data pruning independently.
- **Reference [`service/server/main.py`](https://github.com/HKUDS/AI-Trader/blob/main/service/server/main.py)** (lines 78-82) for the environment variable check and [`service/server/worker.py`](https://github.com/HKUDS/AI-Trader/blob/main/service/server/worker.py) (lines 23-38) for the standalone task loop.
- Deploy using separate containers to achieve true process isolation and horizontal scaling.

## Frequently Asked Questions

### Can I run background tasks in the same process as the FastAPI server?

Yes, but it is not recommended for production. If you set `export AI_TRADER_BACKGROUND_TASKS=1` before starting uvicorn, the startup event in [`service/server/main.py`](https://github.com/HKUDS/AI-Trader/blob/main/service/server/main.py) will launch background tasks alongside the HTTP server. However, this causes CPU and I/O competition that degrades API responsiveness.

### What happens if I forget to unset `AI_TRADER_BACKGROUND_TASKS` when starting the API?

The API process will attempt to start background tasks during the FastAPI startup event, potentially causing duplicate work if you also run [`worker.py`](https://github.com/HKUDS/AI-Trader/blob/main/worker.py) separately. Always ensure the environment variable is empty for the API process in production deployments.

### How does the worker process keep running without exiting?

The [`service/server/worker.py`](https://github.com/HKUDS/AI-Trader/blob/main/service/server/worker.py) script uses `await asyncio.Event().wait()` at line 38 to create an infinite blocking call. This prevents the Python process from terminating while the background event loop continues processing periodic tasks.

### Which file contains the route definitions for the FastAPI application?

The `create_app()` function in [`service/server/routes.py`](https://github.com/HKUDS/AI-Trader/blob/main/service/server/routes.py) builds the FastAPI instance and wires all route modules. Both [`main.py`](https://github.com/HKUDS/AI-Trader/blob/main/main.py) and the testing infrastructure import this function to instantiate the application.