Getting started

This guide creates a local, loopback-only evaluation instance. Hikyo is still in 0.x, so the supported installation path is currently a source build rather than a stable release artifact.

At the end, you will have the Hikyo binary, an embedded browser UI, a local SQLite database, and one administrator account.

Prerequisites

• Go 1.27.0 or newer within the Go 1.27 line.
• Node.js 26.7.0, matching the repository’s .nvmrc.
• Corepack 0.35.0 with pnpm 11.24.0.

1. Clone and build

git clone https://github.com/Hikyo-Org/Hikyo.git
cd hikyo
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
mkdir -p bin
go build -tags ui -o ./bin/hikyo ./cmd/hikyo

The ui build tag embeds the Vite output in the Go binary. A build without that tag remains useful for API-only development but does not serve the browser app.

2. Start an evaluation instance

./bin/hikyo server --dev

Development mode binds to 127.0.0.1:8080, creates hikyo-dev.db, and writes a mode-0600 root key beside it. Keep the database and key together: losing the key makes the encrypted data unrecoverable.

Check the server from another terminal:

curl --fail http://127.0.0.1:8080/healthz

3. Create the first administrator

Run this on the same host and from the same directory as the development server:

HIKYO_DB=sqlite:hikyo-dev.db \
HIKYO_ROOT_KEY="$(tr -d '\n' < hikyo-dev.rootkey)" \
./bin/hikyo admin create \
  --username admin \
  --output-file ./hikyo-admin-authority

The output file is created with mode 0600. The authority is single-use and expiring; it establishes a password but creates no session.

Display the authority on your terminal, then run Hikyo’s credential-establishment command:

cat ./hikyo-admin-authority
./bin/hikyo account establish-credential \
  --instance http://127.0.0.1:8080 \
  --as admin

Confirm the instance identity, paste the authority at the controlling-terminal prompt, and choose a password of at least 12 characters that is not in the bundled common-password list. Neither value crosses argv, environment variables, or a pipe. Delete hikyo-admin-authority after the command succeeds, then open the local sign-in page.

Next steps

• Complete your first project to create environments and a validated value.
• Review installation options before choosing a longer-lived setup.
• Read core concepts before declaring production keys and environments.
• Move to the self-hosting baseline before using real secret material.