<div align="center">

# Legate Agent

**Self-hosted AI agents and workflow automation, with a human in the loop.**

Legate ingests data, reasons, decides, and performs real actions across your business tools. Every side effect passes a policy engine, sensitive actions wait for human approval, and every privileged step is written to a tamper-evident audit log.

[![CI](https://github.com/sanmaxdev/legate-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/sanmaxdev/legate-agent/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-f5a524.svg)](LICENSE)
![Python 3.11+](https://img.shields.io/badge/python-3.11+-3776ab.svg)
![Next.js 14](https://img.shields.io/badge/next.js-14-000000.svg)

</div>

![Command deck](docs/screenshots/dashboard.png)

---

## Why Legate

Most agent frameworks are libraries you wire together, or hosted products you cannot self-host. Legate is a complete, self-hosted platform built around one idea:

> An agent should be judged by what it safely *does*, not what it says.

That means governance is not an afterthought. Actions are **denied by default**, sensitive tools **route through human approval**, credentials are **envelope-encrypted**, and every privileged action lands in a **hash-chained audit log**.

## Features

- **Agents** - provider-agnostic LLM layer (OpenRouter, Ollama), a plan / act / observe loop, per-agent tool allow-lists, and step / token / wall-clock budgets. Runs stream to the UI live over WebSocket.
- **Workflows** - a no-code visual builder (trigger, agent, tool, condition, approval, wait), plus triggers for manual, signed webhook, cron, and internal events.
- **Connectors + MCP** - ten built-in connectors (Slack, GitHub, Notion, Stripe, Postgres, MySQL, Google, HTTP, Email, Webhook) and first-class **MCP client** support: point Legate at any remote MCP server and its tools become available to your agents.
- **Governance** - a default-deny policy engine, a human approval inbox, role-based access control, and multi-tenant workspaces.
- **Knowledge (RAG)** - document ingestion, swappable embeddings, and vector search with citations.
- **Enterprise** - plans and usage metering, SSO via OIDC, rate limiting, Prometheus metrics and OpenTelemetry traces, Docker and Kubernetes deploys.

## Architecture

```mermaid
flowchart TB
    UI["Next.js dashboard"] -->|REST + WebSocket| API["FastAPI API"]

    subgraph Runtime
        Agent["Agent core: plan / act / observe"]
        WF["Workflow engine: DAG + triggers"]
        Policy["Policy engine + approvals"]
        RAG["Knowledge: ingest + retrieve"]
        Conn["Connectors + MCP"]
    end

    API --> Agent
    API --> WF
    API --> RAG
    API --> Conn
    Agent --> Policy
    WF --> Policy
    Policy --> Conn
    Conn --> Vault[("Credential vault")]
    API --> PG[("PostgreSQL")]
    RAG --> QD[("Qdrant")]
    API --> RQ[("Redis + Celery")]
```

Every tool call an agent or workflow makes is checked by the policy engine before it runs:

```mermaid
sequenceDiagram
    actor User
    participant Agent
    participant Policy
    participant Approver
    participant Tool

    User->>Agent: run(input)
    loop plan / act / observe
        Agent->>Policy: request tool call
        alt denied
            Policy-->>Agent: deny (audited)
        else sensitive
            Policy->>Approver: pause for approval
            Approver-->>Policy: approve or reject
        end
        Policy->>Tool: execute (allowed)
        Tool-->>Agent: observation
    end
    Agent-->>User: final answer (fully audited)
```

## Screenshots

| Agent builder | Visual workflow builder |
|:---:|:---:|
| ![Agent builder](docs/screenshots/agent-builder.png) | ![Workflow builder](docs/screenshots/workflow-builder.png) |
| **Connectors and MCP** | **Hash-chained audit** |
| ![Connectors](docs/screenshots/connectors.png) | ![Audit](docs/screenshots/audit.png) |

## Quick start (Docker)

```bash
cp .env.example .env          # set LEGATE_SECRET_KEY and LEGATE_MASTER_KEY
docker compose up --build     # postgres, redis, qdrant, api, worker, web
docker compose exec api alembic upgrade head   # create the schema

# API:  http://localhost:8000/health
# App:  http://localhost:3000
```

> In production, Legate refuses to start with default secrets. Set a strong
> `LEGATE_SECRET_KEY` and a base64 32-byte `LEGATE_MASTER_KEY` (which encrypts the
> credential vault and is never stored in the database).

## Local development

```bash
# Backend (Python 3.11+)
cd apps/api
python -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
python -m pip install -e ".[dev]"
python -m pytest -q            # test suite
ruff check legate tests        # lint

# Frontend (Node 20+)
cd apps/web
npm install
npm run dev                    # http://localhost:3000 (expects the API on :8000)
```

## Connectors

| Type | What it does |
|---|---|
| `http` | Authenticated HTTP requests, any method |
| `slack` | Post messages, list channels, reply in threads |
| `email` | Send, draft, and search over SMTP / IMAP |
| `github` | Read, open, and comment on issues |
| `notion` | Search, query databases, create pages |
| `webhook` | POST signed JSON to a fixed endpoint |
| `postgres` / `mysql` | Guarded read-only queries and gated writes |
| `stripe` | Look up customers and charges, issue refunds |
| `google` | Google Sheets and Drive |
| `mcp` | Any remote **MCP server** over Streamable HTTP |

Write-capable tools are marked sensitive and route through approval. Adding a new
connector is a single self-registering module, exposed automatically through the
install wizard and agent tool allow-lists. See [`docs/connectors.md`](docs/connectors.md).

## Security model

- Side-effecting actions are **denied by default** and must pass the policy engine.
- `is_sensitive` tools additionally require **human approval**.
- Credentials use **envelope encryption** and are never returned by the API.
- Every privileged action is written to a **hash-chained, tamper-evident** audit log.
- Tenant isolation is enforced at the repository layer per workspace.

More in [`docs/security.md`](docs/security.md).

## Project layout

```
apps/
  api/    FastAPI backend (Python) - agents, workflows, connectors, MCP, policy, RAG
  web/    Next.js dashboard (TypeScript) - the full product surface
packages/
  shared-types/   TS types generated from the API
docs/     architecture, connectors, security, deployment, operations
deploy/   Caddy config and a kustomize Kubernetes manifest set
```

## Tooling

| Concern | Backend | Frontend |
|---|---|---|
| Lint | ruff | eslint |
| Format | black | prettier |
| Types | mypy | tsc |
| Tests | pytest | Playwright |
| CI | GitHub Actions with CodeQL, dependency, and secret scans | |

## License

[MIT](LICENSE) (c) 2026 Sangeeth Thilakarathna
