All docs ▾
Getting started
Using Vex
Install
Signed builds per OS, verifying what you run, and how updates ship.
Builds come from two places and two places only: projectvex.ai and GitHub Releases. Check Requirements first: Docker and an OpenRouter key are needed before the app is useful.
Per-OS builds
| OS | Artifacts | Signing |
|---|---|---|
| macOS 13+ | DMG and ZIP, arm64 and x64 | Developer ID signed and notarized by Apple |
| Windows 10/11 | NSIS installer, x64 | Azure Trusted Signing with an RFC3161 timestamp |
| Ubuntu 22.04/24.04 | AppImage and .deb, x64 | Unsigned. AppImage and deb are not code-signed at all |
Signing is genuinely per OS, and the release pipeline treats it that way: the macOS and Windows jobs fail the build if a signing credential is missing, and the Linux job needs no signing secrets because there is nothing to sign. What that means for you on Linux is written out in Verify a build.
The application identifier is ai.projectvex.app on every platform, and it is fixed: changing it would break auto-update for every installed client. On macOS the bundled vex-mcp bridge binary that powers Vex Studio carries its own signature inside the app bundle, and the pipeline verifies it before publishing.
Installing
- macOS. Open the DMG and drag Vex into Applications. Take the arm64 build on Apple silicon and the x64 build on Intel.
- Windows. Run the NSIS installer. Docker Desktop must be set to the WSL2 backend before the first launch.
- Linux. Mark the AppImage executable and run it, or install the
.deb. Download it only from the official release page: there is no signature on these artifacts to catch a tampered copy.
On first launch the app checks your system, brings up its Docker stack, runs database migrations and opens the setup wizard, walked through in First run.
How updates ship
Vex uses electron-updater against published GitHub Releases of Vex-Foundation/Vex, and nothing else is a valid update source. Tagging a version runs the pipeline that builds, signs and notarizes the artifacts and uploads them with the update manifests (latest-mac.yml, latest.yml, latest-linux.yml); the release is published as soon as that upload completes. Artifact names are versioned, which is what lets updates download differentially.
Nothing installs itself. The app checks for a new version on start, on window focus and on a periodic timer, but auto-download and auto-install are both off: downloading needs your action, and applying the update needs a restart you trigger. These are the states the update surface can be in:
| State | Meaning |
|---|---|
| idle / checking / current | No update in flight, a check running, or you are on the newest release. |
| available | A newer published release was found. It carries a severity: normal, security or critical. |
| downloading | The download you started is in progress, with percent complete. |
| downloaded | The update is on disk and waiting for you to restart. |
| installing | The app is quitting to apply the update. |
| blockedByOperation | A download or install was held back because a Docker, database or mission operation is running. The reason names which. |
| error | The check, download or install failed; the app keeps running the current version. |
Official channels
The only official channels are projectvex.ai, @ProjectVEXai and GitHub Releases at Vex-Foundation/Vex. The team will never DM you first and will never ask for your seed phrase or master password. A build from anywhere else can drain a self-custodial wallet, and phishing or unofficial builds sit outside the security model.
Vex is source-available and free to use: you may read, audit and run it, and use the official builds to self-custody your own assets for personal, non-commercial purposes. Redistribution, forks and commercial use are not licensed. See the license.