havn

module

v0.0.0-...-ac86271 Latest Latest Go to latest Published: Jun 25, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/jorgengundersen/havn

Links

Open Source Insights

README ¶

havn

havn is a Go CLI for reproducible development environments with Nix and a Docker-compatible daemon. It starts (or reuses) one container per project and attaches you directly into a Nix dev shell.

What havn does

Derives a deterministic container name from your project path
Creates missing shared infrastructure on demand (network, volumes, base image)
Starts your project container and opens a shell in the configured dev environment
Supports optional shared Dolt server workflows for projects that use beads

Status

havn is in active development.

Specs in specs/ are the normative contract set
User-facing docs in README.md and docs/ are derivative guides and should be read as current-status guidance
Support labels use Implemented, Partial, and Planned
Source builds are the supported installation path right now

For command-level support details, see the support matrix in docs/cli-reference.md.

Prerequisites

Before using havn, install:

Go (current stable)
Docker-compatible daemon endpoint (Docker Desktop, Docker Engine, or Colima with Docker runtime)
Make

Install (from source)

make build
make install

This builds bin/havn and installs the CLI to your Go binary path via go install.

Quickstart

Build and install havn from this repository.
In any project directory under your home directory, run:
```
havn .
```
On first run, havn may create required runtime resources and then attach you to the project shell.
On later runs, it reuses the existing running container when possible.

Lifecycle-only startup and debugging flow

havn up [path] is non-interactive lifecycle startup only (create/start/init)
havn up --validate [path] adds required environment validation
havn up --prepare [path] adds validation plus optional environment preparation (havn-session-prepare when provided)
debugging-first workflow: run havn up . to get the container running, then use havn enter . for a plain shell

Useful follow-up commands:

havn list
havn stop --all
havn doctor

Output contract quick notes:

status/progress/errors are written to stderr
command data is written to stdout
havn list prints name<TAB>path in human mode and a JSON array with --json

Documentation

Directories ¶

Path	Synopsis
cmd
havn command havn manages the lifecycle of development environment containers.	havn manages the lifecycle of development environment containers.
internal
ci/cmd/boundaryconfidence command
cli Package cli defines the Cobra command tree and CLI boundary for havn.	Package cli defines the Cobra command tree and CLI boundary for havn.
config Package config defines the havn configuration types and TOML loading.	Package config defines the havn configuration types and TOML loading.
container Package container manages container lifecycle operations.	Package container manages container lifecycle operations.
docker Package docker wraps the Docker SDK behind havn-native types.	Package docker wraps the Docker SDK behind havn-native types.
doctor Package doctor implements the havn doctor diagnostic framework.	Package doctor implements the havn doctor diagnostic framework.
dolt Package dolt manages the shared Dolt SQL server container lifecycle.	Package dolt manages the shared Dolt SQL server container lifecycle.
mount Package mount resolves bind mounts and named volumes for container creation.	Package mount resolves bind mounts and named volumes for container creation.
name Package name provides named resource types and pure functions for deriving deterministic container names from filesystem paths.	Package name provides named resource types and pure functions for deriving deterministic container names from filesystem paths.
projectpath
volume Package volume manages havn volume lifecycle — listing expected volumes, checking existence, and ensuring volumes exist during container startup.	Package volume manages havn volume lifecycle — listing expected volumes, checking existence, and ensuring volumes exist during container startup.

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL