Cremind
Installation

Native Mode

A lightweight Python venv install with SQLite, for when Docker isn't available or you want a minimal setup without containers.

Native mode installs Cremind into a Python virtualenv on your machine, backed by SQLite, with the agent sharing your desktop and home directory. It's the right choice when Docker isn't available or you want a minimal install without containers.

In native mode the agent is not sandboxed — it shares your desktop and home directory. If you want the agent isolated from your host, use Docker mode instead.

Requirements

Native mode needs Python 3.13.9+ on Linux, macOS, or Windows. See Requirements.

Install

Run the one-liner for your platform and choose native mode when prompted (or skip the prompt with the mode flag — see Installer flags).

curl -fsSL https://cremind.io/install.sh | bash
iwr -useb https://cremind.io/install.ps1 | iex

What the installer does

  1. Detect Python 3.13+ on PATH.
  2. Ask the deployment type (local / server / custom) and the host or advanced fields.
  3. Create a venv at ~/.cremind/venv and pip install cremind. The wheel ships the prebuilt SPA inside it, so no separate UI install is needed.
  4. Generate ~/.cremind/.env from the deployment-type template (server and custom substitute the relevant host / URL placeholders). The installer also appends INSTALL_MODE=native so the backend's Setup Wizard can filter per-service deployment modes.
  5. Generate ~/.cremind/bootstrap.toml selecting SQLite.
  6. Run cremind db upgrade to apply Alembic migrations.
  7. Start cremind serve in the background. The same process opens two listeners: the API on :1112 and the SPA on :1515. The installer waits for /health.
  8. Open http://<host>:1515/#/setup in your browser.

Ports and listeners

A single cremind serve process serves both surfaces:

PortSurface
1112API (and /health)
1515Web UI (SPA), including the Setup Wizard at /#/setup

Running manually

The installer starts the server for you, but you can also drive it by hand from the venv:

~/.cremind/venv/bin/cremind db upgrade   # apply migrations
~/.cremind/venv/bin/cremind serve        # start API + SPA
~/.cremind/venv/bin/cremind chat         # streamed REPL against the same profile
~/.cremind/venv/bin/cremind --help       # every command

Stopping the server

The install-session server records its PID so you can stop it cleanly.

kill $(cat ~/.cremind/install.pid)
Stop-Process -Id (Get-Content ~/.cremind/install.pid)

Native mode is not yet supervised

A real service unit (systemd / launchd / Scheduled Task) for native installs is a follow-up. For now the install-session server runs only until you log out or run kill explicitly. If you need a process that survives logout, use Docker mode, which is supervised by the Docker daemon.

Re-running and reinstalling

Native mode is idempotent: re-running the installer upgrades in place and keeps your existing config and SQLite database. To wipe the venv and start fresh, pass --reinstall (sh) or -Reinstall (ps1).

Where to go next

Files written

Exactly what native mode creates under ~/.cremind.

Deployment types

Local, server, or custom — how the backend is reached.

Setup Wizard

Pick a provider and create your first profile.

Upgrading

Move to a newer Cremind release.

Docker Mode

The recommended install — a sandboxed XFCE desktop the agent runs inside, with VNC observability and on-demand sibling services.

Requirements

What each install mode needs before you run the one-liner — Docker Engine for Docker mode, Python 3.13.9+ for native mode.

On this page

RequirementsInstallWhat the installer doesPorts and listenersRunning manuallyStopping the serverRe-running and reinstallingWhere to go next