Quick Start

Get Metis running locally and submit your first workflow run in minutes.

Prerequisites

• Docker and Docker Compose v2+
• curl (for API calls)

1. Clone the Repository

git clone https://github.com/jaeaeich/metis.git
cd metis

2. Start All Services

docker-compose up -d

This starts six services:

Service	Port	Description
metis-api	8080	HTTP API
metis-ui	80	Web UI
metis-engine-nextflow	—	Nextflow engine runtime
postgres	5432	State and log storage
valkey	6379	Engine registry and PIDs
nats	4222	Job queue and events

Wait ~15 seconds for health checks to pass, then verify:

curl http://localhost:8080/service-info

3. Submit Your First Run

Send a POST /runs request with workflow parameters:

curl -s -X POST http://localhost:8080/runs \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_engine": "Nextflow",
    "workflow_engine_version": "25.10.4",
    "workflow_type": "NFL",
    "workflow_type_version": "DSL2",
    "workflow_url": "/root/workflows/main.nf",
    "workflow_params": {
      "input": "/data/samples.csv",
      "outdir": "/results/output"
    },
    "workflow_engine_parameters": {
      "profile": "docker",
      "resume": "true"
    },
    "tags": {
      "project": "my-pipeline"
    }
  }'

The response contains the run ID:

{ "run_id": "01965c3f-1234-7abc-..." }

4. Monitor the Run

Via Web UI

Open http://localhost — the UI shows run status, logs, and state history in real time.

Via API — Poll Status

RUN_ID="<your-run-id>"
curl http://localhost:8080/runs/$RUN_ID/status

{ "run_id": "...", "state": "RUNNING" }

Via API — Stream Status (SSE)

curl -N http://localhost:8080/runs/$RUN_ID/status/stream

Events are emitted on each state transition; the stream closes automatically when the run reaches a terminal state.

Via API — Stream Logs (SSE)

curl -N http://localhost:8080/runs/$RUN_ID/logs/stream

Use ?after_seq=N to resume from a known position:

curl -N "http://localhost:8080/runs/$RUN_ID/logs/stream?after_seq=42"

5. Fetch Full Run Details

curl http://localhost:8080/runs/$RUN_ID

Returns the complete run log including command, exit code, stdout/stderr summary, and all task logs.

6. Cancel a Run

curl -X POST http://localhost:8080/runs/$RUN_ID/cancel

7. Stop and Clean Up

docker-compose down

To also remove persisted volumes:

docker-compose down -v

What's Next

• Engine Configuration — customise the engine, add validated parameters, set workdir layout
• Deployment — production Docker Compose setup, Kubernetes, and environment variables
• API Reference — complete endpoint documentation