Quickstart

Install and start Runsight

The fastest way is uvx:
Terminal window
```
uvx runsight
```
Or use Docker:
Terminal window
```
docker run -p 8000:8000 -v "$(pwd)":/workspace ghcr.io/runsight-ai/runsight
```
Don’t have uv? Install it first: curl -LsSf https://astral.sh/uv/install.sh | sh

Open http://localhost:8000. The onboarding flow walks you through API key setup.

Create a workflow file

Create custom/workflows/my-first-flow.yaml:

version: "1.0"
blocks:
  research:
    type: linear
    soul_ref: researcher
  write_summary:
    type: linear
    soul_ref: writer
    depends: research
  quality_review:
    type: gate
    soul_ref: reviewer
    eval_key: write_summary
    depends: write_summary
workflow:
  name: Research & Review
  entry: research

Three blocks: research calls an LLM, write_summary runs after it, and quality_review evaluates the summary.

Define your souls

Each soul_ref in the workflow points to a soul — the agent identity behind a block.

Inline (single file, fastest)

Add a souls: section directly in the workflow file:

version: "1.0"
souls:
  researcher:
    id: researcher
    role: Senior Researcher
    system_prompt: >
      You are an expert researcher. Given a topic, provide a concise,
      well-structured summary of the key findings, trends, and insights.
    provider: openai
    model_name: gpt-4.1-mini
blocks:
  research:
    type: linear
    soul_ref: researcher
workflow:
  name: My First Flow
  entry: research

Soul file (reusable across workflows)

Extract the soul to its own file in custom/souls/. Any workflow can reference it by filename stem (soul_ref: researcher):

id: researcher
role: Senior Researcher
system_prompt: >
  You are an expert researcher. Given a topic, provide a concise,
  well-structured summary of the key findings, trends, and insights.
provider: openai
model_name: gpt-4.1-mini

See Inline Souls and Soul Files for details.

Run it
1. Open the GUI at http://localhost:8000
2. Your workflow appears on the Flows page (auto-discovered from custom/workflows/)
3. Click the workflow to open it on the canvas
4. Click Run

What’s next

Key Concepts — blocks, souls, tools, and how they fit together
Block Types — the block types and when to use each
Custom Tools — give your agents tools defined as YAML files
Assertions & Eval — add quality checks to your workflows
Git Integration — save, commit, and simulation branches