Skip to main content
This guide walks you through setting up Handhold for local development. The setup process installs all required dependencies and prepares your environment for building the application.

​
Prerequisites

Before you begin, ensure you have the following tools installed:
DependencyVersionPurpose
RuststableTauri backend
Bun>= 1.0Frontend dependencies and Vite
Tauri CLI>= 2.0Build tooling
Podman or DockeranyLab services (optional)

​
Install Rust

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
Restart your terminal after installation, then verify: 
rustc --version

​
Install Bun

curl -fsSL https://bun.sh/install | bash
Verify the installation: 
bun --version

​
Install Tauri CLI

cargo install tauri-cli --version "^2"

​
Platform-Specific Dependencies

Install Xcode Command Line Tools:
xcode-select --install

​
Clone the Repository

git clone https://github.com/dutch-casa/handhold.git
cd handhold

​
Automated Setup

The quickest way to set up your development environment is using the automated installer with the --dev flag:
1

Run the dev installer

bash scripts/install-handhold.sh --dev
This script:
  • Verifies all prerequisites (Rust, Bun, Tauri CLI)
  • Checks platform-specific build dependencies
  • Installs frontend packages via Bun
  • Downloads the TTS sidecar binary
  • Verifies the Rust build compiles
2

Wait for completion

The script will output progress as it checks dependencies and installs packages. If any prerequisites are missing, it will provide instructions for installing them.

​
Manual Setup

If you’ve already installed dependencies manually or prefer more control:
1

Install frontend dependencies

bun install
2

Run the standalone setup script

bash scripts/install.sh
This downloads the TTS sidecar and verifies the build environment.

​
TTS Sidecar Binary

Handhold uses Kokoro for text-to-speech synthesis. The koko binary must be built separately and placed in the correct location: 
src-tauri/binaries/koko-<target-triple>
The install scripts handle downloading the pre-built binary for your platform. If the binary is missing, the scripts will notify you.
The target triple depends on your platform:
  • macOS ARM: aarch64-apple-darwin
  • macOS Intel: x86_64-apple-darwin
  • Linux: x86_64-unknown-linux-gnu
  • Windows: x86_64-pc-windows-msvc

​
Verify Installation

Confirm everything is set up correctly: 
bun tauri dev
This launches the app in development mode with hot reload enabled. If the app opens successfully, your environment is ready.

​
Optional: Container Runtime for Labs

To run interactive labs with service dependencies (Postgres, Redis, etc.), install either Podman or Docker: 
brew install podman
podman machine init
podman machine start
Container runtimes are only required for labs that spin up services. Narrated lessons work without containers.

​
Troubleshooting

​
Rust compilation errors

Ensure you’re using the stable Rust toolchain: 
rustup default stable
rustup update

​
Tauri build fails on Linux

Double-check that all system dependencies are installed. The error messages usually indicate which library is missing.

​
Frontend build errors

Clear the Bun cache and reinstall: 
rm -rf node_modules bun.lockb
bun install

​
Next Steps

Architecture

Understand how Handhold is structured

Building

Learn how to build and run the app

Frontend

Explore the React frontend architecture

Backend

Dive into the Rust backend

Build docs developers (and LLMs) love

Get started for freeTalk to us