Heartmorrow

The first evening

Bring the lamps home.

Heartmorrow runs on your own machine. Choose Pinokio for the easiest Windows setup, Docker for an isolated container, or Manual for the self-contained scripts and developer setup.

Choose an install method View on GitHub Installation FAQ →

Choose your path

From download to Day 1.

Every method runs Heartmorrow locally and keeps your game data on your machine. Pick the setup that best fits how you already use your computer.

Recommended on Windows

Let Pinokio manage it.

Pinokio downloads Heartmorrow, creates a private Node.js runtime, installs the dependencies, and gives you controls for starting and updating the game. It does not change your system Node.js installation.

  1. Get Pinokio

    Download and open Pinokio Desktop. If you already have it installed, move on to the next step.

    Download Pinokio Desktop

  2. Add Heartmorrow

    Open Heartmorrow’s Pinokio page and choose Install. Pinokio will open the launcher in its desktop app.

    Open Heartmorrow on Pinokio

  3. Let Pinokio set it up

    On Heartmorrow’s screen inside Pinokio, select Install. Pinokio downloads the game and prepares everything it needs inside its own app directory.

  4. Start and open Heartmorrow

    When installation finishes, select Start, then Open Heartmorrow. The game opens locally in your browser and remains on your machine.

  5. Connect a language model

    Pinokio installs Heartmorrow, but it does not bundle a language model. Open Settings → Model & diagnostics, choose your local server or hosted provider, enter its connection details, select a model, and press Test connection.

    Read the model setup guide

Alternative launcher source. If the Pinokio listing does not open the desktop app, paste the launcher’s GitHub URL into Pinokio’s Download field.

Container install

Run it with Docker.

This path needs Docker Desktop or Docker Engine, but no local Node.js or pnpm. The included Compose file builds the web app and API into one container and exposes one local port.

  1. Get Heartmorrow

    Download the project ZIP and extract it, or clone the repository with Git.

    Download the ZIP View on GitHub 
    git clone https://github.com/HMDSimDev/heartmorrow.git
cd heartmorrow

  2. Build and start the container

    Open a terminal in the Heartmorrow folder and run the included Compose configuration.

    docker compose up --build

  3. Open the game

    Visit http://localhost:8787. Docker serves the web app and API together, so there is no separate :5173 address for this method.

    Open the local Docker app

  4. Connect your model

    If your model runs on the host computer, use host.docker.internal instead of localhost in its base URL. For example, LM Studio commonly uses http://host.docker.internal:1234/v1, while Ollama commonly uses port 11434.

    Read the model setup guide

Persistent saves

Your game survives rebuilds.

The database and uploaded art live in the named heartmorrow-data volume. Rebuilding the image does not reset that volume.

Local by default

Keep port 8787 private.

The included Compose file publishes Heartmorrow only on 127.0.0.1. The app has no authentication, so do not expose it to an untrusted network.

Two manual routes

Choose how much to manage.

Use the self-contained installer if you want Heartmorrow to keep its tools inside the game folder. If you already have Node.js 24 or newer and pnpm, use your own environment instead.

Option A

Use the self-contained installer.

No prerequisites are required. The script downloads an official Node.js build into .runtime/node, activates the project’s pinned pnpm version, installs dependencies, and seeds the sample database.

  1. Get the files

    Download the ZIP and extract it somewhere you can find again. If you use Git, clone the project instead.

    Download the ZIP View on GitHub 
    git clone https://github.com/HMDSimDev/heartmorrow.git
cd heartmorrow

  2. Run your platform’s installer

    Windows

    PowerShell

    powershell -ExecutionPolicy Bypass -File .\install.ps1

    macOS & Linux

    Terminal

    chmod +x install.sh run.sh
./install.sh

    Android

    Termux

    chmod +x install.sh run.sh
./install.sh

    Use the Linux installer inside Termux, then play in your phone’s browser.

  3. Launch Heartmorrow

    Windows

    .\run.bat

    macOS, Linux & Android

    ./run.sh

    Open http://localhost:5173 if the page does not open automatically. The installer scripts are safe to run again when you need them.

Option B

Use your own Node environment.

This route requires Node.js 24 or newer and pnpm. The repository pins pnpm@11.7.0 through its package manager configuration.

  1. Install dependencies

    Open a terminal in the extracted or cloned Heartmorrow folder, then install the workspace packages.

    pnpm install

  2. Prepare the game

    You can copy the example environment file if you want to change the defaults. Seed the sample world, characters, and items before your first run.

    cp .env.example .env
pnpm seed

    On Windows PowerShell, use Copy-Item .env.example .env instead of cp.

  3. Start Heartmorrow

    pnpm dev

    Open http://localhost:5173, then connect your model in Settings → Model & diagnostics.

    Read the model setup guide

Platform compatibility. The Pinokio launcher has been tested on Windows. Heartmorrow’s self-contained installers have been tested on Windows, macOS, Linux, and Android through Termux. Docker support depends on a compatible Docker installation.