Skip to content
Back to search

LeAgent

Open-source desktop AI agent that gets work done — plans & self-corrects, agentic visual workflows, generative UI, and 100+ offline tools in one self-hostable stack.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/vixues--leagent/badge.svg)](/listings/vixues--leagent)

HTML

<a href="/listings/vixues--leagent"><img src="/api/listings/vixues--leagent/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

Local dev (recommended for hackers)

**Prerequisites:** git, [uv](https://docs.astral.sh/uv/), Node.js 20+ or 22+

git clone https://github.com/vixues/LeAgent.git
cd LeAgent
./start.sh                # backend :7860 + frontend :5173

The dev orchestrator syncs the Python env with `uv`, installs frontend deps, and (unless skipped) installs the Playwright Chromium used by web tools.

Docker

cd LeAgent/deploy
cp .env.example .env      # set LEAGENT_SECRET_KEY + at least one provider key
docker compose up -d --build

API and interactive docs at `http://localhost:8000/docs`. The default image is a single SQLite-backed container; optional overlays add a local GPU vLLM service (`docker-compose.vllm.yml`).

Manual setup

# Backend
cd backend
uv sync --extra dev
uv run leagent init
uv run leagent app

# Frontend (separate terminal)
cd frontend
npm install && npm run dev

One-line install

curl -fsSL https://vixues.com.cn/install.sh | bash

Configuration

Set at least one provider key (env var or **Settings → Environment secrets** in the web UI, which writes `~/.leagent/.env`). The most common knobs:

| Variable | Purpose | | --- | --- | | `LEAGENT_SECRET_KEY` | App secret for signed URLs and session crypto (`openssl rand -hex 32`) | | `DEEPSEEK_API_KEY` | DeepSeek provider — auto-aliased as `tier1` (reasoning) / `tier2` (fast) | | `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` / `DASHSCOPE_API_KEY` | Additional cloud providers | | `VLLM_ENDPOINT` / `LLM_OLLAMA_ENDPOINT` | Local / self-hosted OpenAI-compatible inference | | `DATABASE_URL` | Switch from SQLite to PostgreSQL | | `LEAGENT_DEBUG` | Enable debug logging |

See [`deploy/.env.example`](deploy/.env.example) for the full annotated list.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 294 lines · 1 finding marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <img src="docs/assets/logo.svg" alt="LeAgent Logo" width="120" height="120">
  3. </p>
  4. <h1 align="center">LeAgent</h1>
  5. <p align="center">
  6. <strong>The open-source desktop AI agent that gets work done — an agent that plans and self-corrects, agentic visual workflows, generative UI, and 100+ offline tools in a single self-hostable stack.</strong>
  7. </p>
  8. <p align="center">
  9. <a href="../../actions/workflows/ci.yml"><img src="../../actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  10. <a href="../../releases/latest"><img src="https://img.shields.io/github/v/release/vixues/LeAgent?display_name=tag&sort=semver&color=blue" alt="Latest Release"></a>
  11. <img src="https://img.shields.io/badge/Python-3.11%2B-3776ab.svg" alt="Python 3.11+">
  12. <img src="https://img.shields.io/badge/React-19-61dafb.svg" alt="React 19">
  13. <img src="https://img.shields.io/badge/Database-SQLite%20%7C%20PostgreSQL-003b57.svg" alt="SQLite / PostgreSQL">
  14. <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-green.svg" alt="License"></a>
  15. <img src="https://img.shields.io/badge/PRs-Welcome-brightgreen.svg" alt="PRs Welcome">
  16. </p>
  17. <p align="center">
  18. <a href="README_zh.md">中文文档</a> ·
  19. <a href="README_lzh.md">汉文</a> ·
  20. <a href="./docs/tutorial.md">Tutorial</a> ·
  21. <a href="AGENTS.md">Contributor guide</a> ·
  22. <a href="https://github.com/vixues/LeAgent/releases">Releases</a>
  23. </p>
  24. <p align="center">
  25. <img src="docs/assets/screenshots/hero-en.png" alt="LeAgent Screenshot" width="720">
  26. </p>
  27. ---
  28. **LeAgent** is an open-source desktop AI agent that doesn't just chat — it gets work done. Unlike cloud chatbots and code-only CLIs, LeAgent fuses three capabilities most agents keep apart: a streaming agent runtime that **plans, calls tools, and self-corrects** in one think-act loop; **agentic visual workflows** where the agent designs, runs, and refines ReactFlow DAGs (and every one of its tools is automatically a typed node); and a **generative UI** layer that streams live, interactive interfaces — KPI boards, slide decks, galleries — right into the chat. It ships **100+ built-in offline tools** (documents, web, data, code, databases, media, game-art generation) plus a declarative rule engine, Agent Skills, and the Model Context Protocol — all running locally with **zero external dependencies by default** (SQLite, single process). Bring your own model keys, or run **fully offline** against a local Ollama / vLLM endpoint.
  29. It is built for people who want a private, hackable, self-hosted alternative to closed agent products: your documents, sessions, and credentials never leave the machine unless you point a provider at a remote API.
  30. ## Highlights
  31. - **Agent runtime** — multi-turn sessions with token streaming, tool execution, tiered model routing, layered prompt assembly, and a cognitive three-store memory (episodic / semantic / procedural). The `QueryEngine` session orchestrator drives both chat and background paths through one think-act loop, with durable checkpoints for pausing and resuming turns.
  32. - **100+ offline tools** — documents, web research, data wrangling, code execution, databases, generative UI, charts, media, and coding projects (see the [tool catalog](#tool-catalog) below).
  33. - **Visual workflows** — a ReactFlow editor with YAML export, reusable templates, and automatic typed nodes for every tool. The engine stages ready batches, runs independent branches concurrently, and applies centralized retry/backoff and timeouts.
  34. - **Agent Skills** — [Agent Skills v1.0](https://agentskills.my/specification) `SKILL.md` bundles with progressive disclosure and on-demand loading. Ship built-in skills, install from links or archives, or plug in an HTTP skill registry.
  35. - **Research Paper Mode** — open a PDF and the agent becomes a citation-grounded research analyst: structure & outline extraction, faithful section / whole-paper summaries, reference and LaTeX-formula extraction, and region translation — with reader tabs and matching agent tools, text extraction fully offline. ([guide](docs/research-paper-mode.md))
  36. - **Generative UI** — agents stream declarative UI trees (KPI boards, slide decks, galleries, steppers) that render inline in chat and export to PDF or PPTX.
  37. - **Game-art asset pipeline** — first-class, composable generation nodes (image / video / 3D mesh / VFX) with typed media sockets, a quality gate plus a bounded self-correction loop, and inline canvas previews. Runs end-to-end offline with no credentials. ([docs](backend/docs/workflow-engine/art-asset-nodes.md))
  38. - **Multi-provider LLM** — DeepSeek, DashScope (Qwen), OpenAI, Anthropic, Azure OpenAI, Ollama, and vLLM, with cost-tiered routing and failover. DeepSeek is the most thoroughly validated and recommended for first use.
  39. - **Sidebar desk pet** — a customizable avatar with walk/jump animations and personality bubbles, synced to chat streaming and session state. Upload PNG / SVG / GIF or sprite sheets.
  40. - **Integrations** — MCP servers, inbound webhooks, scheduled cron jobs, outbound channels (IM/console), and a declarative YAML rule engine.
  41. - **Zero-config default** — SQLite out of the box and a single Docker container. Scale out with PostgreSQL and Milvus (vector-backed memory) when you need to.
  42. ## What you can build
  43. LeAgent is a complete agent platform, not a starter kit — the building blocks below are wired together and work out of the box, fully offline by default.
  44. - **Office automation** — point it at a folder of invoices, contracts, or reports: it OCRs and classifies the files, extracts structured data into Excel, and produces a polished Word or PPTX summary in a single turn.
  45. - **Research & briefings** — search across DuckDuckGo / SearXNG / Bing, scrape and download sources, then assemble a cited PDF report with charts and KPI dashboards.
  46. - **Data analysis** — load CSV/Excel or query the database, clean, merge, aggregate, run SQL and vector search, and narrate the findings with generated charts.
  47. - **Coding companion** — scaffold a project from a template, edit files across the tree, run a live dev server behind a preview proxy, and execute code in an isolated sandbox.
  48. - **Game-art production** — turn a text brief into images, video, 3D meshes, and VFX sprite sheets through a node graph that self-corrects against a quality gate and exports an engine-ready (Unity / Unreal / Godot) bundle.
  49. - **Live, interactive answers** — stream Generative UI (KPI boards, slide decks, galleries, steppers) straight into chat, then export it to PDF or PPTX.
  50. - **Always-on automation** — schedule cron jobs, trigger flows from inbound webhooks, fan out to IM channels (DingTalk / Feishu / WeChat Work), and gate behaviour with declarative YAML rules.
  51. ## Architecture
  52. LeAgent is an async Python (FastAPI) backend plus a React 19 single-page app, packaged as a modular monolith. The backend uses a strict, downward-only layered domain model — **File → Code → Project** — over a single persistence layer, and every agent turn (chat, SDK, background task, sub-agent, workflow node) converges on **one think-act kernel**.
  53. ```text
  54. LeAgent/
  55. ├── backend/ # FastAPI backend (Python 3.11+, uv-managed)
  56. │ └── leagent/
  57. │ ├── agent/ # QueryEngine orchestrator, planner, subagents
  58. │ ├── sdk/ # Versioned public Agent SDK (runtime, kernel, protocols)
  59. │ ├── api/ # FastAPI routers (v1 + incubating v2)
  60. │ ├── llm/ # LLM service, providers, transport, streaming, generation
  61. │ ├── tools/ # 100+ tools across 13 categories
  62. │ ├── workflow/ # Workflow engine, nodes, art-asset pipeline, templates
  63. │ ├── context/ # Source-driven, relevance-gated prompt assembly
  64. │ ├── prompts/ # Layered PromptBuilder, registry, templates
  65. │ ├── memory/ # Episodic / semantic / procedural agent memory
  66. │ ├── skills/ # Agent Skills v1.0 loader + registry
  67. │ ├── rules/ # Declarative YAML rule engine
  68. │ ├── mcp/ # Model Context Protocol
  69. │ ├── file/ code/ project/ # Layered file → code → project domain model
  70. │ ├── db/ # Persistence: engine, SQLModel models, repositories
  71. │ └── services/ # DB, auth, chat, session, gen-ui, cron, ...
  72. ├── frontend/ # React 19 + TypeScript SPA (Vite, Zustand, React Query)
  73. ├── desktop/ # Electron shell (bundled Python runtime)
  74. ├── deploy/ # Dockerfile + SQLite-only Compose
  75. ├── config/ # Demo workflows + workflow templates
  76. ├── docs/ # Architecture, guides, deployment docs
  77. └── start.sh / start.ps1 # Dev orchestrator (uv + npm)
  78. ```
  79. ### Execution model
  80. Regardless of where a request enters, it flows through one set of well-defined boundaries. Each ingress mints a single `ExecutionRun` (with a `run_id` and, for child scopes, a `parent_run_id`), goes through a thin facade, runs on the shared kernel, and persists to durable state with one owner per state class:
  81. ```text
  82. Ingress HTTP/SSE · WebSocket · Cron · Background task · GenUI
  83. │
  84. ▼
  85. Facade ServiceManager.runtime_context · AgentRuntime · WorkflowService
  86. │
  87. ▼
  88. Kernel run_loop → QueryEngine → tool executor (single think-act loop)
  89. │
  90. ▼
  91. State TieredSessionStore · CheckpointStore · WorkflowStateStore
  92. │
  93. ▼
  94. Observe EventManager (FLOW_*/TASK_*/AGENT_*) · OpenTelemetry
  95. ```
  96. - **One kernel.** Chat and every background path drive through `leagent.sdk.kernel.run_loop`. Turns pause to a durable checkpoint when they await user input, then resume exactly where they left off.
  97. - **Three workflow shapes, one engine.** Saved DAG flows, chat playbook step-cards (compiled to linear flows), and in-chat graph embeds all execute on the same `WorkflowExecutor`, which stages ready batches, runs independent branches concurrently, and applies centralized retry/backoff and timeouts.
  98. - **Clear state ownership.** The chat transcript lives in `TieredSessionStore`, paused turns in `CheckpointStore` (`agent_checkpoints`), and workflow runs in `WorkflowStateStore` — no shared mutable state across subsystems.
  99. See [`AGENTS.md`](AGENTS.md) for the full subsystem map and [`docs/technical/execution-topology.md`](docs/technical/execution-topology.md) for the authoritative agent-loop / workflow-engine state contract.
  100. ## Tool catalog
  101. Every tool is auto-exposed as a typed workflow node, so anything the agent can call can also be wired into a visual flow.
  102. | Category | What it covers |
  103. | --- | --- |
  104. | **Documents** | Read/write Word, Excel, PPTX, PDF; OCR; classification; archives; text processing |
  105. | **Web** | Search (DuckDuckGo / SearXNG / Bing), scraping, image & native media download |
  106. | **Data** | Clean, merge, validate, transform, aggregate, SQL & vector search |
  107. | **Code** | Sandboxed in-process scripts and a subprocess code-execution agent |
  108. | **Database** | Schema-aware querying over the managed database |
  109. | **Generate** | Word / Excel / PPTX / PDF / report / checklist / template-fill generators |
  110. | **Canvas / GenUI** | Stream and patch declarative UI trees; publish canvases |
  111. | **Charts & Images** | Chart generation and image processing |
  112. | **Media** | Image / video / 3D / audio generation backends |
  113. | **Skills** | Discover, install, and invoke Agent Skills |
  114. | **Workflow** | Save, run, and inspect workflows from inside an agent turn |
  115. | **Integration** | MCP, webhooks, channels, and external service calls |
  116. | **Utilities** | Cron, tasks, rule matching, folders, text splitting, pet bubbles, and more |
  117. ## Capabilities in depth
  118. ### Agent runtime & memory
  119. - Multi-turn streaming sessions with tiered model routing, automatic context compaction (micro + auto), and abort-safe tool execution.
  120. - Hybrid reasoning — ReAct-style tool loops *plus* plan-and-execute — with sub-agent delegation and per-turn recovery.
  121. - Cognitive three-store memory: episodic (past turns), semantic (extracted facts), and procedural (tool success rates), with hybrid semantic + lexical recall that degrades gracefully when no vector store is configured.
  122. - Layered prompt assembly with relevance-gated policy/playbook sources, per-layer and global budgets, and provider-aware rendering (including Anthropic prompt-cache boundaries).
  123. ### Workflow engine
  124. - One DAG executor backs saved flows, in-chat step cards, cron jobs, and agent-authored graphs.
  125. - Concurrent branch execution by ready batches, centralized retry/backoff, per-node timeouts, and durable pause/resume.
  126. - Every registered tool is lifted into a typed `Tool.<name>` node automatically — exposing a new capability visually needs zero glue code.
  127. ### Tools & code execution
  128. - 100+ first-party tools across 13 categories, dispatched through one executor with a path sandbox and permission hooks.
  129. - Two-tier code execution: a fast in-process RestrictedPython sandbox for workflow scripts, and a subprocess sandbox (rlimits, timeouts, per-session workspace) for heavier work.
  130. - Files are first-class — tools return `FileRef`s through a unified file layer with HMAC-signed preview/download URLs.
  131. ### Skills, MCP & integrations
  132. - Agent Skills v1.0 (`SKILL.md`) with progressive disclosure: ship built-ins, install from links/archives, or connect an HTTP skill registry.
  133. - Model Context Protocol client for external tool servers; inbound webhooks; outbound IM/console channels; and a declarative YAML rule engine for guardrails and automation.
  134. ### Generative UI & media
  135. - Declarative UI trees stream and patch live over SSE, render inline in chat, and export to PDF or PPTX.
  136. - A first-class media plane (image / video / 3D / VFX / audio) behind a strategy-and-registry generation service with retry + failover, plus a deterministic offline floor that needs no credentials.
  137. ### Multi-model routing
  138. Cost-tiered routing (`tier1` reasoning / `tier2` fast) with automatic failover — bring cloud keys, or stay fully local.
  139. | Provider | Notes |
  140. | --- | --- |
  141. | **DeepSeek** | Recommended default; auto-aliased to `tier1` (v4-pro) + `tier2` (v4-flash); reasoning content + prompt-cache metrics |
  142. | **DashScope (Qwen)** | Thinking + search modes |
  143. | **OpenAI / Anthropic / Azure OpenAI** | Cloud frontier models |
  144. | **Ollama / vLLM** | Fully local / self-hosted OpenAI-compatible inference |
  145. ## Quick Start
  146. ### Local dev (recommended for hackers)
  147. **Prerequisites:** git, [uv](https://docs.astral.sh/uv/), Node.js 20+ or 22+
  148. ```bash
  149. git clone https://github.com/vixues/LeAgent.git
  150. cd LeAgent
  151. ./start.sh # backend :7860 + frontend :5173
  152. ```
  153. The dev orchestrator syncs the Python env with `uv`, installs frontend deps, and (unless skipped) installs the Playwright Chromium used by web tools.
  154. ### Docker
  155. ```bash
  156. cd LeAgent/deploy
  157. cp .env.example .env # set LEAGENT_SECRET_KEY + at least one provider key
  158. docker compose up -d --build
  159. ```
  160. API and interactive docs at `http://localhost:8000/docs`. The default image is a single SQLite-backed container; optional overlays add a local GPU vLLM service (`docker-compose.vllm.yml`).
  161. ### Manual setup
  162. ```bash
  163. # Backend
  164. cd backend
  165. uv sync --extra dev
  166. uv run leagent init
  167. uv run leagent app
  168. # Frontend (separate terminal)
  169. cd frontend
  170. npm install && npm run dev
  171. ```
  172. ### One-line install
  173. ```bash
  174. curl -fsSL https://vixues.com.cn/install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 225 on GitHub
  175. ```
  176. ### Configuration
  177. Set at least one provider key (env var or **Settings → Environment secrets** in the web UI, which writes `~/.leagent/.env`). The most common knobs:
  178. | Variable | Purpose |
  179. | --- | --- |
  180. | `LEAGENT_SECRET_KEY` | App secret for signed URLs and session crypto (`openssl rand -hex 32`) |
  181. | `DEEPSEEK_API_KEY` | DeepSeek provider — auto-aliased as `tier1` (reasoning) / `tier2` (fast) |
  182. | `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` / `DASHSCOPE_API_KEY` | Additional cloud providers |
  183. | `VLLM_ENDPOINT` / `LLM_OLLAMA_ENDPOINT` | Local / self-hosted OpenAI-compatible inference |
  184. | `DATABASE_URL` | Switch from SQLite to PostgreSQL |
  185. | `LEAGENT_DEBUG` | Enable debug logging |
  186. See [`deploy/.env.example`](deploy/.env.example) for the full annotated list.
  187. ## Desktop app (Beta — features still being refined)
  188. Installers for each platform ship with every GitHub release — download and run. No separate Python, Node, or Docker install required; the build bundles its own Python runtime and backend.
  189. | Platform | Download | Notes |
  190. | --- | --- | --- |
  191. | **Windows 10/11 (x64)** | [`LeAgent-Setup-*.exe`](../../releases/latest) | NSIS installer; desktop + start-menu shortcut |
  192. | **macOS (Apple Silicon)** | [`LeAgent-*-arm64.dmg`](../../releases/latest) | Unsigned — `xattr -dr com.apple.quarantine /Applications/LeAgent.app` after install |
  193. | **macOS (Intel)** | [`LeAgent-*.dmg`](../../releases/latest) | Same Gatekeeper note as above |
  194. | **Linux (x64)** | [`LeAgent-*.AppImage`](../../releases/latest) / [`LeAgent-*.deb`](../../releases/latest) | AppImage: `chmod +x` then run. `.deb`: `sudo dpkg -i` |
  195. See all releases: **<https://github.com/vixues/LeAgent/releases>**
  196. ## Tech stack
  197. | Layer | Technology |
  198. | --- | --- |
  199. | **Backend** | Python 3.11+, FastAPI, Uvicorn/Gunicorn, SQLModel + Alembic, Pydantic v2, async I/O, OpenTelemetry |
  200. | **Frontend** | React 19, TypeScript, Vite, Zustand, TanStack Query, ReactFlow, i18next (zh-CN / en-US / 汉文) |
  201. | **Desktop** | Electron (ESM main process), bundled Python backend |
  202. | **Data** | SQLite (default), PostgreSQL (optional), Milvus (optional vector memory) |
  203. | **Tooling** | uv (Python), npm (frontend), Playwright, black + ruff, ESLint |
  204. ## Operations
  205. - **Ports.** Local dev serves the backend on `:7860` and the Vite frontend on `:5173` (`start.sh`); the Docker image publishes the API on `:8000`.
  206. - **Persistence & backup.** State lives under `LEAGENT_HOME`: the SQLite database (WAL mode) plus the working-uploads, knowledge, and coding-project trees. A complete backup is the database **and** that directory.
  207. - **Scaling.** The default single-process / single-worker setup is correct for SQLite (single writer). To scale out, switch to PostgreSQL via `DATABASE_URL` and front the app with sticky sessions (the in-process execution registry and event bus are per-worker). Milvus is optional and only powers vector-backed memory recall.
  208. - **Observability.** Structured JSON logs (structlog), OpenTelemetry spans when an OTLP endpoint is configured, and Prometheus workflow/quality histograms. Interactive API docs at `/docs`; set `LEAGENT_DEBUG=true` for verbose tracing.
  209. ## Documentation
  210. The full documentation set lives in [`docs/`](docs/README.md) — start with the [architecture overview](docs/technical/architecture.md).
  211. - **Start here** — [Architecture overview](docs/technical/architecture.md) · [Tutorial](docs/tutorial.md)
  212. - **Runtime** — [Execution topology](docs/technical/execution-topology.md) · [Agent runtime](docs/technical/agent-runtime.md) · [Agent SDK](docs/technical/agent_sdk.md)
  213. - **Capabilities** — [Research Paper Mode](docs/research-paper-mode.md) · [Workflow engine](backend/docs/workflow-engine/overview.md) · [Art-asset nodes](backend/docs/workflow-engine/art-asset-nodes.md) · [GenUI standard](docs/technical/genui-rendering-standard.md)
  214. - **Tools & models** — [Tool parameter contract](docs/technical/tool-parameters.md) · [DeepSeek](docs/deepseek-guide.md) · [DashScope](docs/dashscope-guide.md) · [Custom models](docs/technical/custom-models.md)
  215. ## Contributing
  216. Issues and pull requests are welcome. Please:
  217. 1. Open an issue for larger changes or ambiguous scope.
  218. 2. Run tests for touched areas (`cd backend && uv run pytest tests/ -v` / `cd frontend && npm run test`).
  219. 3. Follow [`AGENTS.md`](AGENTS.md) for coding conventions and i18n rules (every new UI string must exist in both `zh-CN` and `en-US` bundles).
  220. See [`CONTRIBUTING.md`](CONTRIBUTING.md) for full guidelines and [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) for community standards.
  221. ## License
  222. Apache License 2.0 — see [`LICENSE`](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.