Hikyo

Secrets and configuration you can reason about.

A fully open-source, self-hosted control plane for explicit values across development, staging, and production.

Documentation · Getting started · Self-hosting · Contributing · Security checks

[!IMPORTANT] Release maturity, interface freeze, and distribution status live only under CAP-PUBLIC-RELEASE in the machine-checked implementation-status ledger.

Implementation status

One matrix. No hidden inheritance.

Hikyo makes every environment answer for itself. A value is explicitly set or absent; production never silently borrows a development default.

The same model is available through the embedded web UI, CLI, and API. Hikyo ships as one Go binary and supports both SQLite and PostgreSQL.

What makes Hikyo different

• Explicit state. Empty never means “inherited,” “unknown,” or “use a default.” Each environment records set or absent.
• Declarations before values. Define config vs. secret, validation, and presence rules first. Stage edits as drafts, then validate and publish them before they change the delivered snapshot.
• Deliberate secret disclosure. Normal reads return metadata and presence. Reveal and copy require reauthentication and create dedicated audit events.
• One authorization chokepoint. Humans, machine identities, and local break-glass use the same capability-and-scope decision model.
• Self-hosting is the product. One binary, an embedded UI, your database, your root key, and no enterprise-only implementation.

Quick start

Requires Go 1.27.2+, Node.js 26.7.0 (see .nvmrc), Corepack 0.35.0, and pnpm 11.24.0.

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
go build -tags ui -o ./bin/hikyo ./cmd/hikyo

mkdir -m 700 .hikyo-runtime
./bin/hikyo server --dev --cli-socket "$PWD/.hikyo-runtime/cli.sock"

Open http://localhost:8080. The command creates hikyo-dev.db and a permission-0600 root key in the current directory.

Local CLI authentication uses the same-user Unix socket, not the browser's plaintext loopback TCP listener:

./bin/hikyo login http://localhost:8080 --local --as admin \
  --socket "$PWD/.hikyo-runtime/cli.sock"

--dev is loopback-only and intended for evaluation. A -tags ui build embeds the browser app; a plain go build produces an API-only binary.

WebAuthn requires a hostname in the public origin. Local development uses localhost even when the server binds a loopback IP. For a configured server, set HIKYO_EXTERNAL_ORIGIN to its HTTPS hostname; an explicit IP-address origin is rejected at startup.

Next, follow Getting started to create the first administrator, then Your first project to declare a key and set its first value.

CLI at a glance

One binary handles both operator and day-to-day client workflows.

# Operate the instance
hikyo server [--dev] [--listen ADDR] [--cli-socket PATH] [--root-key-file PATH]
hikyo migrate [--dev]
hikyo admin [--dev] create --username admin
hikyo backup [--dev] export
hikyo restore [--dev] run --from <archive> --identity-file <path>
sudo hikyo upgrade [--target VERSION]
hikyo update channel stable|nightly|off
hikyo update check

# Create a scoped environment
hikyo login <instance-url> --tls-mode system-ca --local --as <user>
hikyo org create --name <name>
hikyo project create --name <name> --org <org-id>
hikyo env create --name <name> --org <org-id> --project <project-id>
hikyo context create <name> --instance <url> --org <id> --project <id> --env <id>

# Declare and manage values
hikyo key create --context <ctx> --name NAME --classification config|secret \
  --declaration '{"rule":{"type":"string"}}'
hikyo values set NAME --context <ctx> --value-file PATH
hikyo values get NAME --context <ctx>
hikyo values get NAME --context <ctx> --reveal --output-file PATH
hikyo values list --context <ctx>
hikyo values diff --context <ctx> --left development --right production
hikyo values copy --context <ctx> --from staging --to production --keys NAME

New HTTPS trust requires an explicit --tls-mode system-ca or --tls-mode spki choice before connecting. Existing stored and provisioned pins retain their behavior; a missing pin never enables CA verification.

Secret values never belong in command-line arguments. Use --value-file or --stdin. Every command answers --help at any depth (hikyo values set --help, hikyo help adapter target). See the complete CLI reference.

Run in production

Outside --dev, provide a datastore, native TLS certificate, external origin, and root key:

HIKYO_DB=sqlite:/var/lib/hikyo/hikyo.db \
HIKYO_EXTERNAL_ORIGIN=https://hikyo.example.com \
./hikyo server --listen 0.0.0.0:8443 \
  --operational-listen 127.0.0.1:8081 \
  --tls-cert-file /etc/hikyo/tls.crt \
  --tls-key-file /etc/hikyo/tls.key \
  --root-key-file /etc/hikyo/root.key

HIKYO_DB accepts sqlite:PATH or a PostgreSQL DSN. Native TLS reloads renewed files without restart. Reverse-proxy mode remains available when exact trusted proxy CIDRs are configured; never expose that plaintext listener directly.

Read Self-hosting before deployment and Configuration for every flag and environment variable.

Fully open. One product.

Every capability required to run Hikyo in production is and will remain open source; there is no /ee directory and there will never be one.

The enforceable commitment and amendment process live in GOVERNANCE.md.

Explore the project

Security · Support · Governance · Trademark

License

Hikyo is licensed under the Mozilla Public License 2.0.

Sponsors