Docs / Build Sei from source

Build Sei from source

This guide is for developers. It covers what you need and the steps to run the open-source Sei app from its source code.

Just want to use Sei? You don't need this page. Download the app instead. Everything, including local models and local voices, works in the normal app.

What you need

macOS or Windows. Linux builds, but it is experimental and not an official platform.
Node.js 22 and npm.
git.
Python 3.11. One native part (headless-gl, used to render what the companion sees in Minecraft) compiles during install and needs Python with distutils, which Python 3.12 removed.
A C++ build toolchain for that native part. On a Mac, install the Xcode Command Line Tools with xcode-select --install. On Windows, install Visual Studio Build Tools with the "Desktop development with C++" workload.

If npm picks the wrong Python, point it at 3.11 for the install:

npm_config_python=/path/to/python3.11 npm install

On Linux you also need system packages for the native build. On Ubuntu:

sudo apt-get install -y build-essential pkg-config libxi-dev libglu1-mesa-dev libglew-dev

Run it

git clone https://github.com/sei-studio/sei.git
cd sei
npm install
npm run dev

The app opens in dev mode. You don't need a .env file. Sign-in, cloud companions and cloud AI work from a plain clone through the Sei server. Copy .env.example only if you want to point at your own server or Supabase project. To use your own AI key instead, pick a provider in Settings > AI.

Analytics: dev runs send usage analytics like the normal app. Turn them off in Settings > Appearance > Usage analytics.

Useful commands

Command	What it does
`npm run dev`	Run the app in dev mode.
`npm run dev:tools`	Dev mode with DevTools, plus a log and prompt viewer at `localhost:7077`.
`npm test`	Unit tests (Vitest).
`npm run typecheck`	TypeScript check.
`npm run build`	Build without packaging.
`npm run dist:mac`	Package for macOS.
`npm run dist:win`	Package for Windows.
`npm run dist:linux`	Build an AppImage (experimental).

Packages you build yourself are not signed. Official signed builds come from the project's release pipeline.

Good to know

Live2D: npm run dev downloads the Live2D Cubism Core if it is missing. It is Live2D's own runtime and is never committed to the repo.
Mac-only helpers: the screen-audio helper for Backseat (native/mac-audio-tap) and native/mac-input are written in Swift and build only on a Mac. Other systems skip them.
Game support: the installed app downloads game support (Minecraft, Stardew Valley and Don't Starve Together helpers) on first use. In dev it loads from the repo.
Stardew Valley mod: it compiles only against the game's own files, so its build output is checked in under native/stardew-mod/assets/.

How the code is organized

Sei is an Electron app with three parts:

Renderer (src/renderer): the React interface.
Main process (src/main): windows, settings, voice, updates and game setup.
Bot process (src/bot): the companion's brain and the game adapters.

Shared types live in src/shared. The helper mods for Stardew Valley and Don't Starve Together live in native/. CLAUDE.md in the repo is the full contributor guide, with the architecture, rules and known pitfalls.

Contribute

Help is welcome anywhere, for example better play in the supported games, support for new games, or better personality and memory. Open an issue or a pull request on GitHub, or talk to us on Discord.

License

Sei is licensed under AGPL-3.0. The Stardew Valley and Don't Starve Together helper mods and the bundled soulcaster and skin-gen libraries are MIT. The bundled chess engine is AGPL-3.0.