Skip to main content
Local-first mode keeps your Memory Crystal data plane on your machine and still uses the hosted Memory Crystal account flow for auth and license entitlement.
Local-first is not accountless mode. You still sign in with Memory Crystal so the installer can validate your license before it provisions local credentials.
For macOS, Linux, WSL, and Git Bash environments, use the universal installer:
For native Windows PowerShell, use the PowerShell companion when it is available for your release:
The installer detects supported clients, summarizes what it found, and asks before configuring each target.

​
Cloud vs local

​
What runs locally

Local mode installs or verifies a versioned local backend artifact under:
That artifact is the end-user distribution for local Convex assets. It should include install, doctor, upgrade, and rollback entrypoints so you do not need a repository checkout. Expected local endpoints after setup: The installer prints the local dashboard URL and the local Convex admin key after setup. The dashboard is for local backend/data inspection. Hosted billing, admin, and production account-management surfaces are not part of the public local dashboard.

​
Supported client prompts

The universal installer is the primary path for:
  • Claude Code
  • Claude Desktop
  • Codex CLI
  • Factory Droid
  • OpenClaw
  • generic MCP clients
For each detected client, it asks whether to configure Memory Crystal. Declining a target should leave that client’s config untouched.

​
Prerequisites

Local mode needs:
  • Docker CLI and a running Docker daemon
  • ports 3210, 3211, and 6791 available on 127.0.0.1
  • a Memory Crystal account with the required entitlement
  • a supported shell: Bash for macOS/Linux/WSL/Git Bash, or native PowerShell on Windows
The installer may offer best-effort Docker guidance. It should not run package-manager or service changes without a prompt.

​
Backup and rollback behavior

Before editing supported client config files, the installer should create timestamped backups with owner-only permissions where the platform supports it. If validation fails after a config mutation, the installer should restore the previous config and explain what failed. Common rollback actions:
  1. Restore the config backup printed by the installer.
  2. Re-run cloud mode if you want the client to use the hosted backend again.
  3. Stop the local backend with the artifact-local rollback or down command.
  4. Keep or remove old ~/.memorycrystal/local-backend/<version> directories according to your backup policy.
See Uninstall for client-specific removal commands.

​
Auth and local credentials

Local mode performs hosted device auth first. After license validation, the installer provisions a local credential for the Docker Convex backend. The intended safety model is:
  • raw hosted bearer/device tokens are not stored in client config
  • local Convex stores hashed local credentials only
  • cleartext local tokens are written only where the client needs them
  • reinstall and upgrade preserve a stable local user mapping for existing local data
  • revoked or expired hosted entitlement fails closed after any documented grace window
If re-auth is required, re-run the installer or use the release’s documented re-auth command.
  1. Re-run the universal installer and choose Cloud hosted backend.
  2. Restore a client config backup if you need to undo a specific client change.
  3. Stop the local backend with the artifact rollback/down command:

​
Source of truth

Primary repo files behind this page:
  • apps/web/public/install.sh
  • apps/web/public/install.ps1
  • scripts/convex-local-up.sh
  • scripts/convex-local-down.sh
  • scripts/convex-local-doctor.sh
  • scripts/convex-local-auth-keys.ts
  • scripts/convex-local-provision-env.ts
  • scripts/convex-local-write-env.ts