Build from source

The source build is the current installation path. It produces one Hikyo binary containing the server, CLI, migrations, and optional browser UI.

Prerequisites

Install these exact toolchain lines:

Git is required for a source checkout. SQLite support is compiled into the binary; no local SQLite service is needed.

1. Clone a reviewed revision

git clone https://github.com/Hikyo-Org/Hikyo.git
cd hikyo
git status --short --branch
git rev-parse HEAD

Record the commit printed by git rev-parse HEAD. Before 1.0.0, main may change interfaces and schema behavior without a compatibility promise.

2. Build the embedded UI

npm install --global --ignore-scripts corepack@0.35.0
corepack enable
corepack install --global pnpm@11.24.0
pnpm --dir clients/ts install --frozen-lockfile
pnpm --dir web install --frozen-lockfile
pnpm --dir web build

The generated TypeScript client is a local web dependency, so install both packages. Their frozen lockfiles prevent dependency resolution from drifting away from the reviewed checkout.

3. Build Hikyo

mkdir -p bin
go build -trimpath -tags ui -o ./bin/hikyo ./cmd/hikyo
./bin/hikyo version

The ui tag embeds web/dist into the binary. Omitting it creates an API-only development binary that cannot serve the browser application.

4. Install for your user

install -d "$HOME/.local/bin"
install -m 0755 ./bin/hikyo "$HOME/.local/bin/hikyo"
"$HOME/.local/bin/hikyo" version

Ensure $HOME/.local/bin is on PATH before using the shorter hikyo command. System-wide installation may instead copy the binary to /usr/local/bin with administrator approval.

Verify the checkout

Run the repository tests before deploying a self-built binary:

go test ./...
pnpm --dir web test

The complete CI pipeline also checks PostgreSQL conformance, the browser flow suite, release fixtures, generated code, documentation, and supply-chain rules.

Update a source build

Source builds stamp the CLI update channel as off: they do not silently replace themselves with a release artifact. Fetch and rebuild from the reviewed source revision instead.

Do not overwrite a running production binary in place. First create an encrypted Hikyo export and preserve the root key through its separate recovery path.

Then fetch a reviewed commit, repeat the build, stop the service, replace the binary, and start it. Follow the upgrade checklist for schema and rollback handling.

Next: run a local evaluation or prepare the self-hosting baseline.