Server Setup

The Heartwood server is a standalone process that runs alongside Vintage Story. It manages all population simulation and persistence.

Starting the server

In-memory mode (no persistence)

Data is lost when the server restarts. Good for testing.

./heartwood-server

With PostgreSQL persistence

Requires Docker. Populations and entity states are saved to a database and survive server restarts.

# Start the database (first time only)
docker compose up -d

# Start the server
./heartwood-server -db postgres://heartwood:heartwood@localhost:5432/heartwood

Or using the included Makefile if running from the source repo:

make run-full    # PostgreSQL, no test species
make run-dev     # PostgreSQL + test hare/fox predator-prey species

Server ports

Port	Purpose
50051	gRPC — VS mod connects here
8080	Web dashboard

Web dashboard

Open http://localhost:8080 in a browser while the server is running to see:

• Live entity map with species color-coding
• Habitat patch overlay with population counts
• Event log (spawns, deaths, migrations)
• Species registry

Password protection

Add -auth <password> to require a password for the web dashboard. Leave it off for open access (default).

./heartwood-server -auth mysecretpassword

Checking the connection

In Vintage Story, run:

/heartwood status

This shows connection state and tracked entity count.