Development

Local development setup, tests, and linting.

Prerequisites

Bun (runtime and package manager)
Docker (for Qdrant and Ollama)

Setup

# Start Qdrant + Ollama (server runs locally, not in Docker)
docker compose -f docker-compose.dev.yml up -d

# Install dependencies
bun install
cd server/ui && bun install && cd ../..

# Run server with hot reload
cd server && bun run dev

The dev compose file starts only Qdrant and Ollama — the HUSK server runs directly on your machine for fast iteration.

Tests

cd server && bun test

Lint and format

cd server && bun run check

This runs Biome for linting and formatting.

Project structure

HUSK/
├── server/           # Main HUSK server (Bun + Hono)
│   ├── src/          # Server source code
│   └── ui/           # Admin UI (separate lockfile)
├── plugins/
│   └── claude-code/  # Claude Code plugin
├── website/          # Documentation site (Fumadocs)
└── docker-compose.yml

Deployment

Production Docker Compose, reverse proxy, and backup strategy.

On this page

Prerequisites Setup Tests Lint and format Project structure