Leon 2.0 Developer Preview: an open-source assistant built on tools, context and memory

What Leon solves, and which branch you are actually adopting

Leon is an open-source personal AI assistant written mainly in TypeScript and released under the MIT licence. The problem it addresses is provider lock-in and the privacy cost of routing every request through a hosted model: the README says Leon supports both local and remote AI providers, and that this balance is deliberate. The .env.sample file backs that up with separate keys for local llama.cpp, an OpenAI-compatible SGLang endpoint, and remote services including OpenRouter, Z.AI, MiniMax, OpenAI, Anthropic, DeepSeek, Moonshot AI, HuggingFace, Cerebras, Groq and Celeris.

The catch is which Leon you get. The README carries an important notice dated 2026-03-29 stating that Leon is focused on the 2.0 Developer Preview on the develop branch, that the new documentation is not ready, and that the current docs site and older guides mostly reflect the legacy architecture. If you want the legacy, more stable pre-agentic version, the README points you at master. That single paragraph decides whether this project fits you, and it is the first thing to settle before reading anything else.

The audience is therefore narrow and specific: engineers who want to inspect or extend a TypeScript assistant core, not people shopping for a finished desktop assistant.

How the 2.0 core routes a request: modes, skills and the tool chain

Leon 2.0 is described as running in three modes. In smart mode, Leon chooses how to handle a task. In controlled mode, it follows deterministic native skills and actions. In agent mode, it can plan step by step. That split is the central design decision: instead of one agent loop for everything, the project keeps a deterministic path for actions it can enumerate and reserves planning for the rest.

Skills are split into native skills and agent skills, the latter backed by SKILL.md files. The README states that Leon-native skills follow Skills -> Actions -> Tools -> Functions (-> Binaries). So a skill is the user-facing capability, an action is a step inside it, a tool is what the action calls, and a function is the concrete implementation, which may in turn invoke a binary on the host.

The rest of the runtime is visible in the repository layout. server/ holds routing, memory, context management, the HTTP API and agent or controlled execution. bridges/ holds Node.js and Python bridges plus toolkit definitions and tool runtimes, and tcp_server/ holds Python services used by parts of the stack. The recent releases match that layout: tcp-server_v2.0.0, python-bridge_v1.4.0 and nodejs-bridge_v1.3.0 all landed on 2026-02-19. Memory is layered rather than a single store, and the README describes a compact self-model plus a bounded proactive pulse system intended to keep Leon consistent without flooding it with context.

Installing the preview and checking the setup

The README requires Node.js >= 24.0.0 and supports Linux, macOS and Windows, with Volta recommended for managing Node. The package.json pins the Volta toolchain to Node 24.21.0 and declares pnpm as the package manager, so pnpm is not optional here.

Clone the repository and install dependencies:

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

The install is not inert. package.json defines preinstall and postinstall hooks that run node scripts/setup/preinstall.js and node scripts/setup/run-setup.js, so the setup script executes during pnpm install. If that script fails, the install fails with it.

Start Leon and then verify the environment:

pnpm start
pnpm run check

By default Leon runs locally and the app is available on http://localhost:5366. The check command is the one to trust when something looks wrong, because the README offers no separate troubleshooting guide for the preview.

Provider credentials go in .env, not config.yml. The README states that non-secret profile configuration lives in config.yml, while .env.sample holds the keys. A minimal local setup only needs the local key:

LEON_LLAMACPP_API_KEY=
LEON_OPENAI_API_KEY=
LEON_PROFILE_TOKEN=

The same file defines LEON_PROFILE_TOKEN as the token used to authenticate every remote request for this profile, which matters as soon as Leon is reachable beyond localhost.

The documentation gap is the real limitation

The README does not merely admit that docs lag; it names the two files that replace them. core/context/LEON.md is described as the source for Leon's current identity and behavior, and core/context/ARCHITECTURE.md as the current architecture overview. Both live under core/context/, which the repository layout describes as generated identity and architecture context documents. Generated documents track the code, but they are not a tutorial, and nothing in the README promises a migration path from the legacy architecture to the new one.

The second limitation is contribution throughput, and the README addresses it directly rather than hiding it. It asks why there are few contributors and answers with two reasons: the 2.0 core is a major transition that makes contribution harder than it will be once the docs and architecture settle, and Leon is still developed largely during spare time, so progress can be uneven. Onboarding is described as progressive, through a 2.0 Developer Preview contributor form rather than open season on the issue tracker.

A third constraint is environmental. The stack is not a single Node process: it includes Python bridges and a Python TCP server, so a working install depends on more than the Node.js version the README lists as a prerequisite. The README does not document the Python side of the setup, which is exactly the kind of gap that makes the preview a poor fit for anyone who needs a reproducible deployment today. It is the wrong tool if you want a packaged assistant you install once and forget. It is also the wrong tool if you need documented rollback or upgrade procedures, because the README does not document rollback.

Leon compared with Home Assistant's voice pipeline

The closest genuinely different approach is Home Assistant, whose Assist pipeline chains separate speech-to-text, intent handling and text-to-speech components and runs them on a home automation hub. The difference is where the intelligence sits. Home Assistant treats the assistant as one component of a device-control system, and its intent matching is built for commands that map onto entities you have already registered. Leon inverts that: the assistant is the product, and device or desktop control is one capability among many, reached through computer use that the README says can operate desktop and browser interfaces and verify visual outcomes.

That inversion has consequences. Home Assistant gives you a stable, documented configuration model and a large integration catalogue, at the cost of an assistant that is weak at open-ended tasks. Leon 2.0 aims at open-ended tasks through agent mode and SKILL.md workflows, at the cost of documentation that the project itself says is not ready. The memory models also differ in kind: Home Assistant persists state about entities, while Leon keeps layered memory for durable preferences, day-to-day context and recent discussion context, which is a conversational design rather than a device-state design.

If your goal is turning on lights with a local voice command, Home Assistant is the better-specified choice. If your goal is an assistant that plans, calls tools and runs against your own machine, Leon's model is the more interesting one, and the preview status is the price.

Licence, maintenance and what an upgrade costs you

Leon is MIT-licensed, and package.json declares the same licence, so the code can be inspected, modified and redistributed under those terms. That is a permissive arrangement, but it says nothing about the skills, toolkits or model providers you connect to it. Each provider key in .env.sample points at a service with its own terms, and the README's privacy argument only holds while you are actually running a local provider such as llama.cpp rather than a remote one. Choosing local models is a configuration decision, not a licence guarantee.

On maintenance, the last push to the repository was on 2026-02-19, and the most recent releases are dated the same day: tcp-server_v2.0.0, python-bridge_v1.4.0 and nodejs-bridge_v1.3.0. The repository is not archived. The README's own notice is dated 2026-03-29, later than the last push, which is consistent with a project publishing its current status while the core is in transition. Treat the version string in package.json, 1.0.0-beta.10+dev, as the honest label for what you are running.

Upgrade cost on the develop branch is the cost of tracking a moving core. The README does not document rollback, and it does not describe a supported upgrade path between preview revisions. The practical mitigation available from the README is branch selection: pin to master for the legacy version, or accept that develop changes under you. There is no migration guide in the README to soften that choice.

Editorial conclusion

Adopt Leon 2.0 if you want to read a TypeScript assistant core and contribute to a preview that is still being rebuilt, and stick to the master branch if you need the legacy, more stable version. Do not adopt the develop branch if you need stable documentation, because the README states the new docs are not ready and the public docs site mostly reflects the legacy architecture. Before anything else, run pnpm run check and read core/context/ARCHITECTURE.md, since those two sources describe the current state more accurately than the docs site does.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes