Knox

Last reviewed Sep 13, 2026 · 869 words

Knox is not a password manager, despite where it sits in the catalogue, and it is not a finished server either. It is Pinterest's open-source secrets service for applications: a Go daemon that stores API keys, database passwords and certificates, versions them, rotates them, and hands them to machines and services that have proven who they are. The repository gives you the client, the server library and a development server wired to temporary storage. Turning that into something you would trust in production means writing your own authentication and storage backends in Go. That single fact decides whether it is for you.

A framework for a secrets service, not a product

The README says it plainly: the dev server is for trying things out. Production Knox at Pinterest authenticates machines with mutual TLS certificates and people with an internal identity provider, encrypts keys with a company-managed master key, and persists to a database, and every one of those pieces is an interface you implement. The listing's Apache-2.0 licence and "simple Go service" pro are both true, and both describe raw material. Compare that to OpenBao or Vault, which you download, configure and run.

For a self-hoster this makes Knox an odd item: 256 MB of RAM and a Docker image are not the obstacle. The obstacle is that the Docker image runs the dev server, and the dev server keeps secrets in memory or a temp directory with an authentication scheme suitable for a laptop.

The key model is the good idea worth learning

Where Knox is interesting is its data model, which is cleaner than most. A key is a named object holding a list of versions. Each version is Primary, Active or Inactive. Exactly one version is Primary and is used for new encryption or new connections; Active versions are still accepted for decrypting old data or validating old tokens; Inactive versions are retired but retained. Rotation is therefore two steps: add a new version as Active, then promote it to Primary, and the old one drops to Active while every consumer that cached the key list keeps working. Nothing breaks at the moment of rotation, which is the whole point of rotation tooling and the part most home-grown scripts get wrong.

Access control lists attach to keys and grant read, write or admin to users, groups or machines. The knox command-line client caches keys locally and refreshes them in the background, so an application reads secrets from a file that the client daemon keeps fresh. That local-cache design is why it scales at Pinterest and why it is friendly to services that must start even when the secrets server is briefly unreachable.

Who it actually fits

Three groups. Go developers building an internal platform who want a secrets service with a small, readable codebase and are prepared to implement the backends; that is roughly the same effort as writing a Vault plugin but with far less surface area to secure. Teams who need the exact version-state model above and find Vault's KV engine too loose. And people studying how a large company does secrets management, for whom the code is a good read.

If you are a self-hoster with a few compose stacks and a growing pile of .env files, you are not in any of those groups. Knox will not save you an evening; it will cost several.

OpenBao, Vault and Infisical are the finished alternatives

For machine secrets in a homelab or a small company, OpenBao is the free fork of Vault that kept the open licence, with the same KV store, dynamic database credentials, PKI and the same client tooling. Vault itself remains excellent under its source-available licence if you are not redistributing it. Infisical is the developer-facing option: a web UI, per-environment secrets, and integrations that inject into Docker, Kubernetes and CI without writing code. All three are single binaries or containers you run tonight.

For human passwords, the thing the password managers category is actually about, none of these applies. Vaultwarden is the answer there, and I would not confuse the two problems: a vault for people needs browser extensions and a phone app, a vault for services needs an API and ACLs, and the tools that try to do both do neither well.

Running the dev server anyway

If you want to see the model in action, build the repository and start the dev server, then use the client to register a key, add a version, and promote it. It takes 10 minutes and teaches you more about rotation semantics than a Vault tutorial. Just do not point a production service at it.

What I'd do

Skip Knox unless you write Go and are building a secrets platform on purpose. Run OpenBao for application secrets, Vaultwarden for human ones, and steal Knox's Primary, Active, Inactive versioning idea for your rotation runbook. The catalogue is right that it is battle-tested at Pinterest; it is Pinterest's battle, fought with Pinterest's backends, and you are being handed the parts rather than the machine.