Install Heartwood¶
Choose one installation route for the environment where your project files already reside. Containers are the easiest workstation route because they package Heartwood, the browser interface, and managed inference software without adding those dependencies to the host. The native installer is intended for compatible Linux hosts and research systems such as Stanford Carina when containers are not the normal execution mechanism.
Choose an Installation¶
| Situation | Use | What You Install |
|---|---|---|
| You have Docker Desktop or Docker Engine | Container | One versioned Heartwood image |
| You use Terra | Terra image | A versioned image selected in Terra |
| You use Stanford Carina | Native release installer | A release-scoped installation in project storage |
| You use Linux without Docker | Generic native installer | A release-scoped installation using uv |
| You contribute to Heartwood | Development installation | The repository and locked development dependencies |
| You operate another platform | Platform integration | A platform-specific image or native installation |
Heartwood images and installers contain no provider credentials and no model weights.
Confirm the Installation¶
After installing, run:
The first command prints the installed release. The second inspects the current directory and environment without changing either one.
Development Installation¶
Use this route only when changing Heartwood itself. It requires Git, uv, and Node.js for browser-interface work.
git clone https://github.com/SchmiedmayerLab/heartwood.git
cd heartwood
uv sync --locked --all-groups --all-extras
uv run heartwood --version
The project uses the locked workspace rather than installing packages individually. See the Development Guide for tests and repository structure.
Update or Remove Heartwood¶
Container users select a new versioned image tag and remove old images with their normal Docker maintenance process. Native release installations are version-scoped, so install the new release beside the previous one, verify it, and then update the executable path.
Do not copy .heartwood/ into an installation directory.
That folder belongs to each research project and persists independently of the executable.