Skip to content
Get packs

Guide · Open source

How to use Leon: install, run and check your setup

Updated · written with AI from the project's own documentation and checked against our catalogue data

Leon is an open-source personal AI assistant that runs on your own computer and can use tools to carry out tasks, not only reply with text. This guide is for developers and technical users who want to install it from source, start it and confirm the setup works. After reading, you will be able to clone the project, install its dependencies, run it locally and know where to look for the current architecture.

Leonleon-ai/leon · ★ 17.6k · MIT

Quick start

  1. 1Clone the repository. Run git clone https://github.com/leon-ai/leon.git to download the source code.
  2. 2Enter the project folder. Run cd leon to move into the project root.
  3. 3Install pnpm. Run npm install --global pnpm@latest. This requires Node.js and npm to be installed.
  4. 4Install dependencies. Run pnpm install to fetch the project dependencies.
  5. 5Start Leon. Run pnpm start. Leon runs locally and is available at http://localhost:5366 by default.
  6. 6Check the setup. Run pnpm run check to confirm the setup went well.

Check whether Leon suits you before installing

The README says Leon is currently focused on the 2.0 Developer Preview on the develop branch, and the new documentation is not ready yet. The legacy, more stable pre-agentic version lives on the master branch.

  • Good fit: developers who want to inspect or extend an open-source assistant, people who want a local assistant for privacy reasons, and contributors interested in the 2.0 architecture.
  • Poor fit: people who want a polished, stable assistant out of the box, or non-technical users who need a simple download-and-use app.

What you need before you start

Leon requires Node.js version 24.0.0 or higher. It supports Linux, macOS and Windows. The README recommends managing Node.js with Volta.

  • Node.js >= 24.0.0
  • Linux, macOS or Windows
  • pnpm, installed through npm in the steps below

Install Leon from source

Installation is a clone-and-build process. Run these commands from a terminal in the folder where you want the project to live.

git clone https://github.com/leon-ai/leon.git cd leon npm install --global pnpm@latest pnpm install

Run Leon and check your setup

Start Leon with pnpm, then run the setup check. By default, Leon runs locally and the app is available on http://localhost:5366.

  • Open http://localhost:5366 in your browser once Leon is running.
  • If the check reports a problem, fix it before going further.
pnpm start pnpm run check

Understand how Leon works before you change it

Leon can run in smart mode, which chooses for you, controlled mode, which follows deterministic native skills and actions, or agent mode, which can plan step by step. Leon-native skills follow Skills to Actions to Tools to Functions (to Binaries).

  • server/: runtime, routing, memory, context management, HTTP API and execution
  • app/: the web application
  • skills/: built-in capabilities split into native/ and agent/
  • bridges/: Node.js and Python bridges and toolkit definitions
  • core/context/: generated identity and architecture documents

Where to read the current documentation

Because the public docs site may lag behind the new core, the README points to two files as the most accurate references: core/context/LEON.md for identity and behaviour, and core/context/ARCHITECTURE.md for the architecture overview.

If you want to contribute, the README lists a 2.0 Developer Preview contributor form, the roadmap, Discord and GitHub issues.

What people use it for

  • Inspecting how an open-source personal assistant is structured, using the server, skills and bridges folders.
  • Running an assistant on your own computer, with local AI providers, for privacy reasons.
  • Extending Leon with new skills or toolkits as a developer.
  • Following the 2.0 Developer Preview architecture as a contributor.

Frequently asked questions

Is Leon free to use?

The repository is released under the MIT licence, as shown in the project's README badge and LICENSE file. Check the LICENSE.md file in the repository for the full terms.

What do I need to install Leon?

You need Node.js 24.0.0 or higher and pnpm, which is installed through npm. Leon supports Linux, macOS and Windows, and setup is done from the command line.

Can Leon run locally?

Yes. The README says Leon runs locally by default and is available at http://localhost:5366. It also supports both local and remote AI providers.

Is Leon a finished, stable app?

Not yet. The README says Leon is focused on the 2.0 Developer Preview, the new docs are not ready, and the legacy master branch is the more stable version.

What should I do if the setup check fails?

Run pnpm run check to see how your setup is doing. The README does not list specific troubleshooting steps, so use the project's GitHub issues or Discord to ask for help.

What are alternatives to Leon?

The project's comparable projects are Home Assistant, Mycroft, OpenVoiceOS and Rhasspy. Pick based on whether you need a home automation hub, a voice assistant platform or a self-hosted assistant framework.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Leon suits developers and contributors who want to read, run and extend an open-source, local-first assistant and who accept a preview that may change. It is not a good choice if you want a stable, fully documented app or a simple download-and-use program, in which case the master branch or one of the comparable projects may serve you better.

Install options & downloads