Skip to content

Getting Started

After completing this guide, you will have Mantle installed, a Postgres database running, and your first workflow executing — all in under five minutes.

What is Mantle?

Mantle is a headless AI workflow automation platform. You define workflows as YAML, deploy them through an infrastructure-as-code lifecycle (validate, plan, apply), and execute them against a Postgres-backed engine. It ships as a single Go binary — bring your own API keys, bring your own database, no hosted runtime required.

Prerequisites

You need the following installed on your machine:

Optional (for automatic local Postgres provisioning):

Verify your setup:

go version    # go1.25 or later

Install and Start (< 2 minutes)

Install the binary and initialize:

go install github.com/dvflw/mantle/cmd/mantle@latest
mantle init

mantle init connects to Postgres and runs migrations. If no database is reachable on localhost, it offers to start one automatically via Docker. For remote databases, set the URL before running init:

export MANTLE_DATABASE_URL="postgres://mantle:secret@db.example.com:5432/mantle?sslmode=require"
mantle init

You should see:

Running migrations...
Migrations complete.

Development setup: If you want to build from source, clone the repository and use make build instead of go install:

git clone https://github.com/dvflw/mantle.git && cd mantle
make build
./mantle init

See Configuration for all database options.

Verify it works:

mantle version
# mantle v0.1.0 (791fa83, built 2026-03-18T00:00:00Z)

Your First Workflow (< 3 minutes)

The examples/ directory includes several ready-to-run workflows. Start with the simplest one — a single HTTP GET request.

Look at examples/hello-world.yaml:

name: hello-world
description: Fetch a random fact from a public API — the simplest possible Mantle workflow

steps:
  - name: fetch
    action: http/request
    params:
      method: GET
      url: "https://jsonplaceholder.typicode.com/posts/1"

This workflow has one step: it sends a GET request to the JSONPlaceholder API and returns the response.

Step 1: Validate

Check the workflow for structural errors. This runs offline — no database connection required:

mantle validate examples/hello-world.yaml

Output:

hello-world.yaml: valid

If there are errors, Mantle reports them with file, line, and column numbers:

bad-workflow.yaml:1:1: error: name must match ^[a-z][a-z0-9-]*$ (name)

Step 2: Apply

Store the workflow definition as a new immutable version in the database:

mantle apply examples/hello-world.yaml

Output:

Applied hello-world version 1

Every time you edit a workflow and re-apply, Mantle creates a new version. If the content has not changed, it tells you:

No changes — hello-world is already at version 1

You can also preview what will change before applying:

mantle plan examples/hello-world.yaml
No changes — hello-world is at version 1

Step 3: Run

Execute the workflow by name:

mantle run hello-world

Output:

Running hello-world (version 1)...
Execution a1b2c3d4-e5f6-7890-abcd-ef1234567890: completed
  fetch: completed

Step 4: View Logs

Inspect the execution with the execution ID from the previous step:

mantle logs a1b2c3d4-e5f6-7890-abcd-ef1234567890

Output:

Execution: a1b2c3d4-e5f6-7890-abcd-ef1234567890
Workflow:  hello-world (version 1)
Status:    completed
Started:   2026-03-18T14:30:00Z
Completed: 2026-03-18T14:30:01Z
Duration:  1.042s

Steps:
  fetch           completed (1.0s)

If a step fails, the error appears below the step name:

Steps:
  fetch           failed (0.5s)
    error: http/request: GET https://jsonplaceholder.typicode.com/posts/1: connection refused

You can also get a quick status summary with mantle status <execution-id>.

Next Steps