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 24+ (Engine or Desktop) and Docker Compose v2.20+
  • 4 GB RAM minimum (8 GB recommended)

Quick Start

The default docker-compose.yml starts everything in one command: Postgres 16, Redis 8, the API, the frontend, and the queue workers. The first run builds the Docker images; subsequent starts are fast.

git clone https://github.com/farnalabs/modulo
cd modulo
docker compose up -d

Open http://localhost:5173 and log in with admin:admin. These are development credentials: change them before exposing the instance beyond local use. The backend runs database migrations automatically on first start.

For local development with hot-reload (separate API and frontend processes), see the Installation guide.

Run your first pipeline

A pipeline is a directed graph of agents: each node performs one step, such as a large language model (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 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 through the saq-runner service started in 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, Completed, Failed, Rejected, or Cancelled). See the run lifecycle for what each status means. 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: Installation