Skip to content

readme: demote Docker to optional hardened mode #1

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pike00 merged 1 commit into from
May 15, 2026
Merged

readme: demote Docker to optional hardened mode #1

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
45 changes: 19 additions & 26 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,40 +13,21 @@ coldkey generates [post-quantum (ML-KEM-768 + X25519)](https://words.filippo.io/

![Image of Printout](image.png)

## Install
## Quick start

```bash
# Homebrew (macOS/Linux)
# Install — Homebrew (macOS/Linux)
brew install --cask pike00/tap/coldkey

# Or with Go
go install github.com/pike00/coldkey/cmd/coldkey@latest
```

## Quick start

### Docker (recommended)

```bash
# Pull the image
docker pull ghcr.io/pike00/coldkey:latest

# Interactive — generate a key and paper backup
just docker-run

# Backup an existing key
just docker-backup ~/.config/sops/age/keys.txt
```

All `just docker-*` commands include security hardening flags (network isolation, read-only filesystem, dropped capabilities). Output is written to `./output/`.

### From source

```bash
go install github.com/pike00/coldkey/cmd/coldkey@latest
# Generate a key and paper backup
coldkey generate -o ~/.config/sops/age/keys.txt
```

For defense-in-depth during key generation, see [Hardened mode (Docker)](#hardened-mode-docker) below.

## Commands

### `coldkey` (no args) — Interactive mode
Expand Down Expand Up @@ -88,9 +69,21 @@ Print the version string.
| Image | `distroless/static:nonroot` — no shell, non-root UID 65534 |
| Memory zeroing | Best-effort `secure.Zero()` on key buffers before GC (see [Limitations](#limitations)) |

### Docker flags explained
### Hardened mode (Docker)

An optional distroless Docker image runs key generation under network isolation, a read-only root filesystem, and dropped capabilities. Note that the resulting `keys.txt` is written to a host-mounted volume, so the container only hardens the generation step — the key at rest sits on the host like any other file.

```bash
docker pull ghcr.io/pike00/coldkey:latest

# Interactive — generate a key and paper backup
just docker-run

# Backup an existing key
just docker-backup ~/.config/sops/age/keys.txt
```

The `just docker-run` and `just docker-backup` commands apply these flags automatically:
Output is written to `./output/`. The `just docker-run` and `just docker-backup` recipes apply these flags automatically:

| Flag | Purpose |
|------|---------|
Expand Down
Loading