Skip to main content
Modulo

Getting Started

Modulo is a self-hosted platform for governed Software Development Lifecycle (SDLC) agent pipelines. These docs walk you through setup, configuration, and building your first pipeline.

Prerequisites

  • Docker & Docker Compose v2.20+
  • Python 3.12+ and uv (or pip)
  • A GitHub account (for GitHub connector)

Quick Start

# Clone the repo
git clone https://github.com/farnalabs/modulo
cd modulo

# Start Postgres, Redis, and the SAQ workers (db-local redis-local saq-runner saq-system)
docker compose -f docker-compose.local.yml up -d db-local redis-local saq-runner saq-system

# Generate a SECRET_KEY
python -c "import secrets; print(secrets.token_hex(32))"

# Create backend/.env with your keys (see Installation guide)
# Run migrations
cd backend
uv run alembic upgrade heads

# Start the backend
uv run uvicorn modulo.api.main:app --reload --port 8000

# In another terminal, start the frontend
cd frontend
npm run dev

Open http://localhost:5173 and log in with admin:admin.

Run your first pipeline

A pipeline is a directed graph of agents: each node performs one step (an LLM call, a connector call, a gate, or a human approval). This walkthrough mirrors the product’s real flow: model backend → schemas → pipeline → run.

1. Create a model backend

Agent nodes that call an LLM route through a model backend, a configured provider with a model and credentials. Open Admin → Model Backends (/admin/model-backends) and select Add Model Backend. Choose a provider (OpenAI, Anthropic, Ollama, …), name it, pick a model, and store the provider API key.

Testing without a provider key? The backend also registers a deterministic custom stub backend (fixture-map responses, no API key) used by the test suite. It isn’t listed in the UI’s provider dropdown; create it via POST /api/v1/model-backends with "provider": "custom".

2. Define input and output schemas

Schemas describe the shape of the data an agent consumes and produces. Open Schemas (/schemas) and create a schema (the editor is at /schemas/editor/:id), defining the fields each node will read and write. Schemas are versioned, so a schema update affects every agent bound to it.

You can also let Modulo infer one: with a connected connector that supports sampling, Schema Inference (/schemas/infer) pulls sample records from the tool and generates a JSON Schema via an LLM (POST /api/v1/schemas/infer).

3. Build the pipeline

Go to Pipelines (/pipelines), create a pipeline, and open the Pipeline Editor (/pipelines/:id/editor). Use Add Node to place nodes on the canvas and connect them with edges:

  • An agent node bound to your model backend and schemas (the node that calls the LLM).
  • A second node, e.g. a gate that blocks until a human approves, or a connector node that posts the result to an external tool.
  • Connect the first node’s output to the second node’s input, then Save. The editor validates the graph before saving.

4. Trigger a run

From the editor, click Run pipeline to start the run with an input payload. You can also trigger a run over the API:

curl -X POST http://localhost:8000/api/v1/runs \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"pipeline_id": "<pipeline-uuid>", "input_payload": {}}'

The endpoint returns 202 Accepted immediately; execution happens in the background (the SAQ saq-runner service from Quick Start). Poll GET /api/v1/runs/{run_id} for status.

5. Watch the run

Open Runs (/runs) to see every run and its status (Pending, Running, Awaiting Human, Complete, Failed, …). Open Run Detail (/runs/:id) to inspect:

  • The input payload the run was started with
  • The per-node execution trace, showing each node’s status and output
  • Human-in-the-loop gates: if a node waits for approval the run pauses in Awaiting Human until you claim and approve (or reject) the gate

Next Steps

Next: Installation