neo.mjs: Getting Started Guide

August 2, 2026 · View on GitHub

This guide covers two main paths for working with neo.mjs:

Creating your own application: The recommended approach for all developers building apps with the framework.
Contributing to the framework: For those who want to contribute code directly to the neo.mjs core.

1. Creating your own application (Recommended)

For most use cases, creating a dedicated workspace with npx neo-app is the best way to start. This script scaffolds a new project, automatically installs dependencies, runs the initial build, and can even start the development server for you.

A workspace provides the same structure as the main neo.mjs repository, but includes the framework as an NPM dependency, making it easier to manage.

Create a Workspace

Open your terminal and navigate to the directory where you want to create your project.
Run the following command:
```
npx neo-app@latest
```
Follow the interactive prompts. The script will guide you through setting up your workspace and creating your first application.

This single command handles the entire setup process, allowing you to start developing immediately.

2. Contributing to the framework or running examples

If you want to contribute to the development of neo.mjs itself, or if you want to run the many demo applications and examples included in the main repository, you will need to set up the core repository locally. The examples are not included in workspaces created with npx neo-app.

Fork and Clone the Repository

Fork the repository: First, create a fork of the neomjs/neo repository on GitHub to your own account.
Clone your fork: Clone your forked repository to your local machine.
```
git clone https://github.com/YOUR_USERNAME/neo.git
```

Local Setup

Navigate into the cloned repository folder:
```
cd neo
```
Install the required node modules:
```
npm install
```
This is the Body path: build tools, Body tests, and shared tooling — with no native compile. It is everything a frontend (Body) contributor needs.

Working on the Agent OS (Brain) — the ai/ services, daemons, MCP servers, or the memory core — needs the Brain tier instead:
```
npm install
npm run install-brain
```
One documented command overlays the Brain set (better-sqlite3, chromadb, @chroma-core/default-embed; see package.brain.json) onto the base install, resolved from the committed exact closure (package-lock.brain.json) — the same checkout installs the same Brain graph on every machine. Note: a plain npm install or npm ci afterwards prunes the Brain set again — just re-run npm run install-brain. The unit-test runner skips the Brain projects with a clear message while the set is not installed.
Run all relevant build scripts at once:
```
npm run build-all
```
(See the Command-Line Interface for further details.)

Running the Examples

Start the web server:
```
npm run server-start
```
A browser tab will open automatically. You can also manually access it at http://localhost:8080/. A local web server is required because modern browser security policies prevent JavaScript modules from loading directly from the local file system.
Explore the apps:
- Development Mode: You can run the docs and examples apps without any JS build directly in all major browsers (Chrome, Edge, Firefox, Safari).
  
  http://localhost:8080/neo/docs/
  
  http://localhost:8080/neo/examples/
- Distribution Versions: These versions also work in all major browsers and represent the built state of the examples.
  
  http://localhost:8080/neo/dist/development/examples/
  
  http://localhost:8080/neo/dist/production/examples/

Dive Deeper with Learning Resources

Once you have your environment set up, you can dive deeper into the concepts and architecture of the framework. The learning resources provide a structured path to mastering neo.mjs.

Explore the Learning Resources