Getting started

This page covers the fastest path from a clean clone to a running vault binary, plus the commands the team uses every day. The full developer setup is in README.md and CONTRIBUTING.md.

Prerequisites

• Go — the version pinned in .go-version (currently 1.26.1, also reflected in go.mod).
• Node — the version pinned in .node-version and .nvmrc. Required only if you build the UI.
• pnpm — ui/pnpm-workspace.yaml configures the UI workspace.
• Docker — required for make test because many tests stand up real backends in containers.
• Make — the canonical build entry point is Makefile (and make.bat on Windows).

The .go-version file is the source of truth; CI rejects builds that drift from it.

First build

git clone https://github.com/hashicorp/vault
cd vault
make bootstrap        # installs build tools listed in tools/
make dev              # builds bin/vault and copies to $GOPATH/bin
bin/vault version

make dev invokes scripts/build.sh, which sets CGO_ENABLED=0 by default and produces a development binary tagged with the current git SHA. To include the embedded UI, run make static-dist dev-ui instead — this triggers a UI build under ui/ and bakes the resulting bundle into the binary via http/web_ui/.

Running a dev server

Start a single-node, in-memory dev server:

bin/vault server -dev -dev-root-token-id=root

In another shell:

export VAULT_ADDR=http://127.0.0.1:8200
export VAULT_TOKEN=root
bin/vault status
bin/vault secrets list
bin/vault kv put secret/hello value=world
bin/vault kv get  secret/hello

-dev bypasses unseal, mounts a kv v2 backend at secret/, and prints the root token.

Running tests

The full test target lives in Makefile:

make test                       # unit tests with -race, parallel
make test TEST=./vault          # restrict to one package
make test TESTARGS='-run TestCore_Init'   # restrict to one test
make testacc TEST=./builtin/logical/consul   # acceptance tests; needs creds

CI also runs make fmtcheck, make lint (golangci-lint), make proto-lint, and the Enos scenarios under enos/. See Testing for the full layout.

Web UI dev loop

cd ui
pnpm install
pnpm start                    # http://localhost:4200, talks to local Vault
pnpm test                     # ember-cli tests
pnpm test:filter --filter '...'    # focused run

ui/README.md and ui/MODULE_REPORT.md describe the Ember addon layout and the in-house core/ and console/ packages.

Configuration

A production server expects a HCL or JSON config file. The minimum viable config is:

storage "raft" {
  path    = "/vault/data"
  node_id = "node-1"
}

listener "tcp" {
  address     = "0.0.0.0:8200"
  tls_cert_file = "/etc/vault/tls/cert.pem"
  tls_key_file  = "/etc/vault/tls/key.pem"
}

cluster_addr = "https://node-1.example.com:8201"
api_addr     = "https://node-1.example.com:8200"

Configuration parsing lives in command/server/config.go and internalshared/configutil/. Every block (storage, listener, seal, telemetry, service_registration, …) corresponds to a struct in those packages. See Configuration for an enumeration.

Initializing and unsealing

A fresh Vault must be initialized (which generates the master key and unseal keys) and then unsealed:

bin/vault operator init -key-shares=5 -key-threshold=3
bin/vault operator unseal <unseal_key_1>
bin/vault operator unseal <unseal_key_2>
bin/vault operator unseal <unseal_key_3>
bin/vault status

The init implementation is in vault/init.go; unseal flow is in vault/seal.go and vault/seal_autoseal.go. See Seal.

Common follow-ons

• Mount an auth method: bin/vault auth enable userpass
• Mount a secret engine: bin/vault secrets enable -path=kv kv-v2
• Write a policy: bin/vault policy write app policy.hcl
• Open the UI at http://127.0.0.1:8200/ui
• Start the agent: bin/vault agent -config=agent.hcl

For the full CLI surface see CLI app.