Mesh Avatar Studio Installation Guide: Set It Up in 3 Commands

What you need first

Node.js 22.17 or newer — the only hard requirement for the editor and Live page. Get it from nodejs.org or your package manager (node -v checks yours).
Git — recommended for downloading the repository cleanly.

Python 3.10+ with uv and Playwright Chromium are optional: they are needed only when a coding agent builds avatars for you (the layer builder and the motion review renderer). The editor itself never needs them.

The 3-command quick start

npx create-mesh-avatar-studio
cd mesh-avatar-studio
npm run dev

What each command does:

npx create-mesh-avatar-studio downloads the repository, installs its packages and checks the tools Studio needs — no manual clone required.
cd mesh-avatar-studio moves you into the new project folder.
npm run dev starts the local development server. Open the URL it prints (for example http://127.0.0.1:5173/) and the editor opens with a bundled sample avatar.

In the editor, pick a part on the left, drag its dots on the image and watch the live preview on the right. The bundled sample is read-only — changing it offers Copy and keep editing so you work on your own copy.

Check your tools: npm run doctor

If anything misbehaves, run the built-in check:

npm run doctor

It reports each missing tool separately — Node itself, uv/Python (for rebuilding layers) and Chromium (for the agent's motion review). Treat a warning as a blocker only if the step you want needs that tool.

Cloning manually instead

git clone https://github.com/shinshin86/mesh-avatar-studio.git
cd mesh-avatar-studio
npm install
npm run doctor
npm run dev

Use the manual clone when you want to pin a version or contribute back. npm install replaces the one-liner's automatic setup.

The Windows ZIP gotcha (read this before extracting)

If you downloaded a ZIP instead of cloning, open its Properties in File Explorer and select "Unblock" before extracting — if shown. Folders created from a blocked ZIP can carry permissions that stop the editor from reading project files. If a project cannot be read, use the folder's Properties → Security settings to grant your account access to the whole project including subfolders.

Also on Windows: create the projects/ folder under your own user account before asking a coding agent to work in it. Folders created by an agent running in a sandbox may have permissions your account cannot read.

Updating

Pull the latest release and reinstall:

git pull
npm install
npm run doctor

Your avatars live in projects/, which is never committed — a pull does not touch them.

What runs where (privacy)

The editor, Live page and browser Player all run locally. Camera and microphone data never leave your machine; the local server is the only thing running. See the official reference privacy section for details.