iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
To compile Convex locally, check out the official get-convex/convex-backend repository, install the toolchain versions it pins, bootstrap its scripts and JavaScript packages, then run just run-local-backend from the repository root. The command builds the Rust backend and starts a local instance. You can point the included tutorial application at that instance with just convex dev, and run its frontend separately with npm run dev:frontend.
This workflow is intended for developing or changing Convex itself. If your goal is only to operate a self-hosted deployment without modifying the source, use the project’s prebuilt Docker image or binary instead; compiling the repository adds a Rust and JavaScript build toolchain that deployment users do not need.
What this procedure builds
The repository is the Convex backend project, not the unrelated Convex blockchain project that appears in some search results. A source checkout gives you the Rust backend, its supporting scripts, JavaScript packages, and the tutorial application used in the local-development instructions.
Windows Errors? Fix Them Before They Spread
Repair common Windows errors and clear accumulated junk for a smoother, more stable PC - no reinstall needed.Free scan · no reinstallCrashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteRunning the backend locally creates a development deployment on your computer. The included command supplies the local configuration needed by the repository’s scripts, so you do not have to assemble a hosted deployment URL before testing backend changes.
#1 Best Overall
Choose source compilation for development
Compile from source when you need to inspect, debug, or modify the backend, its migration code, or the repository’s local-development tooling. Every change can be rebuilt from the checkout, and the tutorial app can exercise the result before you deploy anything elsewhere.
Choose a prebuilt artifact for unchanged self-hosting
If you only want to self-host Convex and have no source changes to make, the contribution guidance recommends a prebuilt Docker image or binary. That path is an artifact installation rather than a source build: you manage the runtime and deployment configuration, but you do not need the repository’s compiler toolchain.
| Path | Primary purpose | Setup shape | Repository changes required |
|---|---|---|---|
| Compile from source | Developing or modifying Convex | Install Just, the pinned Node.js and Rust toolchains, pnpm/Turborepo dependencies, and run repository tasks | Yes, when you are changing or testing the codebase |
| Prebuilt Docker image or binary | Self-hosting without changing source | Deploy the published artifact rather than compiling the checkout | No |
Prerequisites and pinned versions
Install the tools before invoking the build. The repository pins versions so that contributors use the same language runtimes and package-manager behavior.
- Git and a checkout of
get-convex/convex-backend: Obtain the official backend repository and work from its root directory. The root should contain the project’sJustfile,.nvmrc,rust-toolchain,scripts, andnpm-packagesdirectories. - Just: The repository’s tasks are defined in its Justfile. Install the Just command runner using the method appropriate for your operating system, then confirm that
justis available in your shell. - Node.js: Use the version recorded in
.nvmrc. The project recommends nvm; from the repository root, runnvm useso the shell selects that version rather than a globally installed one. - Rust and Cargo: The backend is written in Rust. The
rust-toolchainfile pins the nightly toolchain. Install rustup, then let it install or select the toolchain named by that file. Cargo is supplied by the selected Rust toolchain. - pnpm and Turborepo: The JavaScript side of the repository uses pnpm and Turborepo. The repository tasks install and invoke the required JavaScript dependencies; do not substitute a different package manager for the documented tasks.
- npm: npm is needed to perform the scripts bootstrap command shown below. Use the npm version that works with the Node.js release selected by
nvm use.
Check the checkout before installing
Run commands from the backend repository root. If nvm use reports that the requested Node version is unavailable, install the version named in .nvmrc with nvm and run nvm use again. If a command says just, cargo, or rustup cannot be found, fix that tool installation before retrying the repository tasks.
Install the repository dependencies
The setup has two bootstrap operations: one installs the scripts’ npm dependencies, and the other installs the Convex JavaScript workspace dependencies through the Justfile.
- Select Node.js: From the repository root, run
nvm use. This reads.nvmrcand switches the current shell to the project’s pinned Node.js version. - Bootstrap the scripts: Run
npm clean-install --prefix scripts. The--prefix scriptsoption targets the repository’s scripts directory, whileclean-installperforms a reproducible install from that directory’s lockfile. - Install Convex JavaScript dependencies: Run
just install-jsfrom the repository root. This invokes the project’s JavaScript installation task and prepares the pnpm/Turborepo workspace used by the backend and examples. - Allow Rust to select the pinned nightly: Run a Cargo command only after rustup has installed the nightly release specified by
rust-toolchain. If rustup prompts to download that toolchain, accept the installation, then rerun the failed task.
Keep the same terminal environment for the subsequent commands so the Node version selected by nvm and the repository’s Rust override remain active.
Compile and start the local backend
Once the tools and dependencies are installed, run the upstream source-build task from the repository root:
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Repair Windows errors before they cause bigger problemsFix Now →just run-local-backendThis task is both the build and the launch step. Cargo compiles the Rust backend using the nightly toolchain pinned by the checkout, and the task starts the resulting local service. The first run can take longer because Rust crates and JavaScript workspace packages must be compiled or prepared. Leave this process running while you use a second terminal for the tutorial application or CLI commands.
What a successful start means
A successful command leaves the local backend process running without a build or startup error. The repository’s local scripts know the local URL and administrative key used by the tutorial setup; you do not need to point the app at a hosted deployment for this workflow.
Do not expose development credentials
The repository warns source-build users to replace the default instance secret and admin key. Treat those values as development credentials: do not copy them into a public repository, a production deployment, or a client-side bundle. Generate and configure replacement values before using the local backend for anything beyond a disposable workstation test.
Run the included tutorial app against the local backend
The tutorial demonstrates the complete client-to-backend loop. Start the backend first with just run-local-backend, then open another terminal for the app.
- Move to the tutorial: From the backend repository root, run
cd npm-packages/demos/tutorial. - Start the Convex development process: Run
just convex dev. The repository’sconvexscript supplies the local--urland--admin-keyvalues, and the command writes the appropriate deployment information to the tutorial’s local environment. - Start the frontend: In another terminal, from the tutorial directory, run
npm run dev:frontend. Open the local address printed by that frontend command and exercise the tutorial against the backend process that is still running in the first terminal.
Do not start dev:backend for this setup. The guide’s convex dev command is already running the development connection needed by the tutorial, so starting a second backend task can create conflicting processes rather than a more complete setup.
Keep the two processes separate
The backend terminal owns the process started by just run-local-backend. The tutorial terminal owns just convex dev, and the frontend terminal owns npm run dev:frontend. If you stop the backend, the tutorial may still have a frontend process, but its requests cannot succeed until the local backend is started again.
Use the local CLI helpers
The repository exposes convenience commands through the same convex script. From the tutorial directory, or wherever the repository’s local script is available, the guide lists these operations:
just convex data— inspect data in the local deployment.just convex env— inspect or work with the deployment environment values.just convex logs— view backend or function logs exposed by the local deployment.just convex import— import data into the deployment.just convex export— export data from the deployment.
Use the helper that matches the operation instead of editing generated environment files by hand. Keep imports and exports tied to the local deployment you intend to inspect; a command run after switching deployments can otherwise target a different environment.
Free tools Windows power users keep installed
One-click scans. No signup required.
Switch safely between hosted and local development
The client reads its deployment URL from .env.local. Before testing a client, run either npx convex dev for a hosted development deployment or just convex dev for the repository’s local backend. The selected command updates .env.local with the corresponding CONVEX_URL.
- Stop or finish the current development process so it cannot rewrite the environment while you switch.
- Run the command for the deployment you want to use:
npx convex devfor hosted development, orjust convex devfor the local source-built backend. - Confirm that
.env.localcontains the expectedCONVEX_URLbefore launching or refreshing the client. - Start the client and verify that its requests are reaching the intended deployment rather than relying on a stale URL from the previous mode.
This explicit switch matters when alternating between hosted and local work. A client can appear healthy while silently talking to the wrong deployment if the environment file still contains the previous URL.
Telemetry, platform support, and local security
Disable the self-hosted beacon when required
Self-hosted source builds send a beacon containing a random deployment identifier, database migration version, backend Git revision, and uptime. The backend binary supports --disable-beacon if you need to turn that beacon off. Apply the flag through the way you launch the backend in your local setup, and verify the resulting command line or task configuration rather than assuming a source build disables telemetry automatically.
Expect the strongest support on Linux and macOS
The repository reports the most testing experience on Linux and Mac and less on Windows. Windows users may be able to build through a compatible Rust, Node.js, and shell environment, but platform-specific failures should be interpreted in light of that stated testing coverage. If you need the path with the least environmental variation, use Linux or macOS for the source-build workflow.
Recommended Free Tools
Keep local data and secrets disposable
A local backend contains data and credentials that are useful for development but are not a substitute for production secret management. Replace the default instance secret and admin key, avoid committing .env.local, and use the local database only for data you can recreate or protect.
Troubleshoot startup and build failures
Persisted database metadata error
If startup reports an error containing persisted db metadata ..., the build guide says the local database may need to be erased. Stop the backend, change to the repository root, and run:
rm convex_local_backend.sqlite3This deletes the local database file and its contents. Use the command only when the local data can be discarded; export anything you need before removing the file. Start just run-local-backend again after the file is gone so the backend can create a fresh local database.
Node.js version mismatch
If npm or a repository task rejects the Node.js version, run nvm use from the repository root and repeat the dependency installation. Do not work around the pinned version by deleting the lockfile or installing dependencies with an unrelated global Node release; the repository expects the version recorded in .nvmrc.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Rust toolchain mismatch
If Cargo reports that the required compiler or standard library is missing, check that rustup is installed and that the nightly toolchain named by rust-toolchain is available. Return to the repository root so rustup can apply the file’s override, install the missing components when prompted, and rerun the Just task.
Just task cannot be found
Install Just and make sure its executable is on PATH. The repository does not replace the Justfile tasks with arbitrary shell commands, so a missing just executable must be fixed before just install-js, just run-local-backend, or just convex dev can work.
The tutorial connects to the wrong deployment
Run the intended development command again and inspect .env.local. Use just convex dev for the source-built local backend and npx convex dev for hosted development. Restart or refresh the client after the file’s CONVEX_URL changes.
Recommended repeatable workflow
After the initial installation, the shortest reliable cycle for backend work is:
The Tool Desk
Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →- Open the repository root and run
nvm use. - Start the backend with
just run-local-backend. - In the tutorial directory, run
just convex devif you need the sample app or local client environment. - Run
npm run dev:frontendin a separate terminal when you need the tutorial UI. - Use
just convex logs,data,import, orexportfor local inspection and data work. - When changing between local and hosted development, rerun the appropriate
convex devcommand before testing so.env.localhas the rightCONVEX_URL.
This sequence keeps the compiler toolchain, backend process, CLI environment, and frontend process distinct, which makes it easier to identify whether a failure occurred during compilation, deployment setup, or client startup.
When to stop using the source-build path
Source compilation is the right choice while you are contributing to or investigating the Convex codebase. It is not automatically the best deployment method. Once you no longer need to modify source, move to the prebuilt Docker image or binary recommended by the contribution guidance, and follow the project’s self-hosting documentation for deployment-specific configuration. That separation reduces the amount of compiler and package-manager state you must maintain on a server.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
