Docs

Quick Start — End-to-End in 5 Minutes

This page gets you from zero to a running distributed job as fast as possible. You need three terminals open from the project root.

Step 0 — Activate Your Environment

=== “Windows” powershell .venv\Scripts\activate === “Linux / macOS” bash source .venv/bin/activate

Terminal 1 — Start the Foreman

The Foreman is the orchestrator. It must be running before workers or clients connect.

python tests/run_foreman_simple.py

Expected output:

INFO:     Uvicorn running on http://0.0.0.0:8000
INFO:     WebSocket server started on ws://0.0.0.0:9000

Open the dashboard in your browser: http://localhost:8000

Terminal 2 — Start a Worker

python tests/run_worker_simple.py

Expected output:

[Worker] Connected to Foreman at ws://localhost:9000
[Worker] Registered as worker_<id> — ready for tasks

Scale to Multiple Workers

Open additional terminals or use the multi-worker launcher:

python tests/run_multiple_workers.py 8 --start-port 8001

This spawns 8 workers on sequential ports starting at 8001.

Terminal 3 — Run the Sample Client

python tests/example_client.py localhost

This connects to the Foreman, submits a sample job (squaring a list of numbers), and prints the results.

Expected output:

[1, 4, 9, 16, 25]

What Just Happened?

sequenceDiagram
    participant C as Client (example_client.py)
    participant F as Foreman (:9000)
    participant W as Worker

    C->>F: connect + submit_job (square, [1..5])
    F->>F: create job + 5 tasks in SQLite
    F->>W: assign_task (square, 1)
    F->>W: assign_task (square, 2)
    W-->>F: task_result (1)
    W-->>F: task_result (4)
    Note over F: Aggregates ordered results
    F-->>C: job_results [1,4,9,16,25]

Other Example Scripts

Script What it demonstrates
tests/example_client.py Basic map() over a list
tests/example_checkpoint_client.py Checkpointing and resume
tests/view_database.py Inspect SQLite tables
tests/view_checkpoints.py Inspect checkpoint records
tests/quick_clear_db.py Clear all DB data
tests/check_db_schema.py Verify schema columns

Next Steps