Installing Premation
There are two ways in: the prebuilt desktop installer, and building from source. Most people want the installer. Build from source if you intend to change the code, or want the edition that never contacts our servers.
Check System requirements first — the GPU is the part that decides whether this works.
Two editions
One source tree builds two editions, chosen at build time with the
VITE_EDITION environment variable. The split exists because the editor is open
source (AGPL-3.0-only )
while the hosted backend it can talk to is not.
local (VITE_EDITION=local) | server (default) | |
|---|---|---|
| Accounts / sign-in | None — opens straight into the editor | A free sign-in |
| Projects | On disk, as a .motion bundle | Cloud, with autosave |
| Assets | On disk, content-addressed | Cloud library |
| Version history | Local, structurally shared | Local and server-side |
| Export | On your computer, with the ffmpeg a packaged build ships | On your computer, with the ffmpeg the installer ships |
| Editing, compositing, 3D, rigging, effects | Identical | Identical |
| AI assistant | Included, on your own provider key | Included, on your own provider key |
| Native plugins | They run in the engine. Installed from a .pplugin file or the plugins folder | The same, plus the plugin store and Premation Cloud plugins |
| Cloud sync, hosted render, billing | Absent | Optional |
The local edition is the one to build from the repository. It makes no
requests to our servers — the API layer refuses to send, so an offline build
cannot quietly phone home. (The assistant, if you give it a key, talks to the
provider you chose.) The server edition targets a backend service that is
not part of the repository, so its cloud features sit on a sign-in screen without
one.
In the codebase, read the edition as a capability, never as a flag:
cloudAccountsEnabled(), cloudProjectsEnabled(), billingEnabled() and
friends in src/core/config/edition.ts say why a surface is gated.
isLocalEdition() only says where that happens to be true today. The AI
assistant is on in both editions; the only thing that differs is where your
provider key lives (the operating system’s keystore in the local edition, the
server in the server edition).
The desktop installer
Builds are published on GitHub Releases , next to the source they were built from.
| Platform | Release asset | Status |
|---|---|---|
| Windows 10 / 11 · x64 | Premation-Setup-Windows.exe | Available |
| macOS · Apple silicon / Intel | Premation-macOS-arm64.dmg / Premation-macOS-x64.dmg | Available |
| Linux · x64 | Premation-Linux-x86_64.AppImage | Available since 1.0.2 |
Download from the Premation site or straight from the releases page, run the installer, and launch. There is nothing else to configure for the editor itself — the installer carries the engine, a bundled font set and, since 1.0.1, the ffmpeg that video export encodes with.
On macOS, 1.0.1 is the first 1.0 release with a macOS build: the 1.0.0 macOS engine did not build.
On Linux, mark the AppImage executable and run it:
chmod +x Premation-Linux-x86_64.AppImage
./Premation-Linux-x86_64.AppImageIt needs FUSE 2 (libfuse2) and a Vulkan-capable GPU driver; on Wayland it runs through XWayland. The AppImage updates itself in place, like the Windows
installer. It is new in 1.0.2 and is checked by CI rather than by daily use, so
please report anything that goes wrong on your distribution.
The download buttons point at
releases/latest/download/<asset>, so they always fetch the newest published
release rather than a pinned version.
The installers are unsigned for now, and that has a different consequence on each platform.
On Windows, SmartScreen warns you the first time — choose More info → Run anyway — and automatic updates work normally.
On macOS, Gatekeeper blocks the app until you open it once with right-click ▸ Open, and automatic updates are switched off, so each new version is a manual download.
Updates & macOS setup walks through both, and explains why. All of it goes away once the builds are signed — no reinstall needed.
Building from source
Get the code and its dependencies
git clone https://github.com/isroil01/premation.gitcd motion-editor && npm installYou need Node.js 20 or newer and npm.
Build the engine
Since 0.9 the frames are drawn by a native engine process, and the app will not start without it. Build it once:
npm run native:configure -- --enginenpm run native:build -- --engineThis needs the C++ toolchain described in native/README.md: Clang (clang-cl
on Windows, with the Visual Studio 2022 Build Tools for the Windows SDK), CMake
3.25 or newer, Ninja, and vcpkg with VCPKG_ROOT pointing at it. Nothing in the
repository downloads a compiler for you. The first build fetches and compiles the
engine’s dependencies through vcpkg and takes a while; later builds reuse them. In a
development checkout the app looks for the result in
native/build/<preset>/engine/ — windows-clang-cl-engine, macos-clang-engine
or linux-clang-engine — or wherever PREMATION_ENGINE_PATH points.
Run the desktop app with hot reload
npm run electron:dev:localThis is the real app. It compiles the Electron main process, starts Vite on
localhost:5173, waits for it, and launches Electron, which starts the engine.
Renderer edits hot-reload.
There is no browser mode. The engine is a separate native process that the desktop app starts, so the interface cannot render in an ordinary browser tab.
Both :local scripts set VITE_EDITION=local. Dropping the suffix
(npm run electron:dev) builds the server edition, which will sit on a
sign-in screen unless you point it at a backend you run yourself.
Every script, and what it does
| Command | What it does |
|---|---|
npm run electron:dev:local | Vite + the Electron shell, both watching — local edition |
npm run build:local | Typecheck (tsc -b) and build the renderer bundle |
npm run electron:build:local | Build the renderer + compile electron/ |
npm run pack:local | Unpacked desktop build — fast, for testing packaging |
npm run dist:local | Installer for the current platform, into release/ |
npm test | The full Jest suite |
npm run typecheck | tsc --noEmit |
npm run lint | ESLint |
npm run native:build / native:test | Build and test the C++ engine (add -- --engine for the engine target) |
npm run native-golden | The golden gate: the engine renders each test scene and every frame is compared with its committed reference frame |
npm run cli -- render … | The headless renderer from a checkout — see the CLI |
The :local scripts have a suffix-free twin (npm run electron:dev,
npm run dist, …) that builds the server edition instead.
A changed reference frame is a claim that the new pixels are correct. Look at
the diff first, and check git status on the references directory before you
commit — an unreviewed reference change hides a regression.
ffmpeg when you run from source
The installers ship ffmpeg, so there is nothing to install for them. A
development run from a checkout (npm run electron:dev:local) has no shipped
copy: video export (MP4, WebM, MOV, GIF and the HDR formats) uses FFMPEG_PATH,
ffmpeg on your PATH, or a copy the app downloads for you from Window ▸
Customize… ▸ Appearance ▸ Video Export ▸ Fix…. Stills, image sequences, WAV,
Lottie and project export do not need it.
Windows
Using winget:
winget install Gyan.FFmpegOr download a build, unzip it, and add the bin folder to your PATH.
Verify with ffmpeg -version. If you would rather point at a specific build,
set FFMPEG_PATH to the executable and Premation will use that in preference to
anything else.
The companion server
The server edition talks to a companion NestJS service (motion-back, a
separate repository, not open source) for:
- sign-in and accounts,
- cloud project storage, sync and billing,
- hosted rendering and the automation API,
- the AI assistant’s model calls, when you choose to route them through it rather than your own key.
The editor expects it on port 4000.
In the local edition none of that is present — those surfaces are absent rather than broken, which is what makes the build genuinely offline. You keep everything else, including every export format. If you only want the editor, build local and skip the server entirely.
Packaging refuses to produce an installer without the engine or ffmpeg:
npm run dist:local stages premation-engine from the preset build directory
first, and stops if it is not there — build the engine before you package. It
then fetches the pinned ffmpeg build (below).
npm run dist:selfhosted is a third packaging config that bundles a sibling
../motion-back checkout into the installer. It ships that project’s
.env.example, not its .env; the app reads the server’s configuration from
a file in its user-data folder at first run.
ffmpeg in your own package
Packaging bundles ffmpeg for you. Before each platform and architecture is
packed, scripts/fetchFfmpeg.cjs downloads the build pinned in
electron/ffmpegManifest.json (Windows x64, macOS arm64 and x64) into
build/.cache/ffmpeg/, checks its SHA-256, runs it to confirm its encoders
(where the build machine can run it), and
stages it with its GPL licence and source notice as <resources>/ffmpeg/. Any
failure stops the build. PREMATION_PACKAGE_WITHOUT_FFMPEG=1 allows an offline
local rehearsal without it; that package then offers the in-app repair download
on first export. See ffmpeg & codecs.
Next
- Updates & macOS setup — opening an unsigned build on macOS, and how new versions reach you
- First launch — the dashboard, creating a project, the onboarding tour
- Your first animation