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

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 – Boots the FastAPI application and optionally starts background tasks
• service/server/worker.py – Runs only background tasks without initializing the HTTP server
• 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, 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). 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:

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:

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

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:

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:

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 (lines 78-82) for the environment variable check and 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 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 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 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 builds the FastAPI instance and wires all route modules. Both main.py and the testing infrastructure import this function to instantiate the application.

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