Skip to main content
Local-first mode keeps the Memory Crystal data plane on your machine. The installer still checks your API key against the hosted service at https://convex.memorycrystal.ai before it provisions a local credential. That check happens at install time.
Local-first is not an accountless install. Cloud and local modes both require a hosted API key that passes GET /api/mcp/auth during setup. Passing --api-key or MEMORY_CRYSTAL_API_KEY skips the browser prompt when that key validates. An invalid explicit --api-key fails validation. With a rejected environment key, interactive Bash setup can offer browser sign-in again.
The hosted Memory Crystal service runs on Convex Cloud at https://convex.memorycrystal.ai. Local-first is a separate data plane you operate. It is not the hosted service. macOS, Linux, WSL, and Git Bash:
Native Windows PowerShell:
The installer detects supported clients, summarizes what it found, and asks before configuring each target. --yes selects the cloud backend instead of prompting, so pass --backend local when you want local mode without a prompt.

​
Cloud, local, and self-hosted

External self-hosting is documented in Self-Hosting. Provider keys for embeddings are a separate setup. See Providers.

​
What runs locally

The installer places a versioned artifact at:
You do not need a repository checkout to run it. The artifact’s bin commands do this: The PowerShell install, doctor, rollback, and down wrappers call Bash scripts. The upgrade wrapper only prints instructions. Native PowerShell alone is not enough to provision or stop this backend; Bash must be on PATH. Storage defaults to embedded SQLite. Pass --storage=postgres to bin/install for the Postgres profile. CRYSTAL_LOCAL_STORAGE_MODE accepts embedded or postgres. The installer prints the local dashboard URL and the local admin key after setup. That dashboard inspects the local backend. Hosted billing and account pages stay on the hosted site. Ports 3210, 3211, and 6791 must be free on 127.0.0.1. Docker CLI and a running Docker daemon are required. The installer does not change packages or services without a prompt. Backup and restore of the local volume are separate commands. See Local Backup and Recovery.

​
Clients the installer can configure

Declining a target leaves that client’s config untouched. The installer creates timestamped config backups and attempts owner-only permissions (or a restricted Windows ACL) before editing. If validation fails after a config write, restore the backup the installer printed. To point a client back at the hosted service, re-run the installer with --backend cloud. To stop the local process, run bin/rollback or bin/down in the artifact directory. Removing ~/.memorycrystal/local-backend/<version> deletes that artifact’s files. It does not by itself delete a Docker volume the backend already created.

​
Credentials

After the hosted key validates, the installer provisions a local user id and token for the Docker backend. Client config receives the local token, not the hosted bearer. The local backend stores a hash of that token. Reinstall keeps an existing usable local-auth.json so the same local user still sees existing rows. A later change to your hosted plan does not, by itself, keep re-checking this local token. Local API-key revocation is enforced by the local key record: an inactive or deleted installer key is treated as revoked on the next local request. If local auth fails, run bin/doctor, then re-run the installer. See Uninstall to remove client config.