Time devours. Kronos preserves.

Kronos is a Go-based backup manager for scheduled, encrypted, verified database backups. Redis/Valkey currently runs as the most complete native driver; PostgreSQL, MySQL/MariaDB, and MongoDB are implemented as external-tool MVP drivers that require the matching database client tools on worker agents. The product brief and build plan live in .project/:

• Specification
• Implementation
• Tasks
• Full capacity plan
• Branding
• Architecture
• Changelog
• API reference
• Quick start
• CLI reference
• Operations runbook
• Troubleshooting
• Deployment topologies
• Restore drills
• Release verification
• Cloud secret integration
• Project status
• Production readiness
• Implemented-path readiness
• Full-product readiness
• Driver MVP decision
• Agent transport decision
• Secret storage decision
• Kubernetes example

This repository currently has the Phase 0 foundation in place and active Phase 1/early Phase 2 implementation work:

• storage backends: local filesystem, S3-compatible object storage, SFTP, Azure Blob, and Google Cloud Storage
• crypto/chunk core: FastCDC, BLAKE3 chunk IDs, compression, encryption envelopes, dedup index, backup/restore pipeline
• repository metadata: signed manifests, manifest commit/load helpers, manifest and chunk-level verification
• embedded state: pure-Go page store, B+Tree, rollback WAL, buckets, repair
• audit: kvstore-backed hash-chained append log with verification and server mutation recording
• retention: count, time, size, and GFS policy resolver with JSON plan output
• scheduling: 5-field/6-field cron parser, @between windows with stable jitter, catch-up policies, per-target queueing, and persisted server-side scheduler ticks/background loop
• driver scaffold: generic driver interfaces plus executable Redis/Valkey SCAN/DUMP/RESTORE support with ACL snapshot/restore records and JSON command stream replay. PostgreSQL has a logical pg_dump/psql MVP with multi-version conformance, 15-to-17 restore rehearsal, and full global restore rehearsal coverage in CI, plus a 10,000-row PostgreSQL restore drill; its native pgwire foundation now covers TCP/TLS startup, cleartext, MD5, and SCRAM-SHA-256 auth, simple-query result decoding, catalog extension/enum/domain/sequence/table/column/constraint/index/view/routine/ trigger discovery, and plain-SQL snapshot/restore paths behind protocol=native, with real-service integration coverage under the PostgreSQL integration test tag. MySQL/MariaDB has a mysqldump/mysql logical MVP with real-service MySQL 8.4, MariaDB 11.4, and bidirectional MySQL/MariaDB restore rehearsal coverage in CI, plus 10,000-row MySQL and MariaDB restore drills. MongoDB now has a mongodump/mongorestore archive MVP with deterministic unit coverage, authenticated real-service MongoDB 7.0/8.0 conformance, and an authenticated MongoDB 7.0 10,000-document restore drill in CI.
• CLI: dispatcher, version, database repair, backup now/list/inspect/protect/unprotect/verification, target/storage add/list/inspect/update/remove, schedule add/list/inspect/pause/resume/remove, target test, storage test/du, scheduler tick, overview, jobs list/inspect/cancel/retry, audit list/tail/search/verify, token create/list/inspect/verify/revoke/prune, notification add/list/inspect/update/remove, retention plan/apply/policy add/list/inspect/update/remove, key slot/escrow/rotation helpers, restore preview/start, user add/list/inspect/remove/grant, health/readiness, metrics, overview, and repository garbage collection, plus bash/zsh/fish completion generation
• backup listing filters by target, storage, type, protection state, and timestamp windows such as --since 7d
• job listing filters by status, operation, target, storage, agent, restore/verification backup ID, and queued time windows
• audit listing, tailing, and searching filters by actor, action, resource, and occurred-at windows
• server: config-loading HTTP skeleton with /healthz, /readyz, /metrics, probe-friendly HEAD handling, and graceful shutdown
• local mode: starts an embedded control-plane server with local state and can run an embedded worker with --work
• WebUI: embedded React/Tailwind operations dashboard served by the control plane, with live overview/jobs/backups/target/storage data, browser-side bearer token support, target/storage/schedule/retention/job/backup detail inspection, target/storage/schedule/retention create/update editing, guarded target/storage deletion, manual backup drill queueing, backup metadata verification, chunk verification queueing, and verification result display, backup verification history, restore preview plus guarded dry-run/live restore queueing, restore job history with restore outcome summaries and hash-addressed failure/evidence artifacts, schedule pause/resume, job cancel/retry, and backup protect/unprotect actions, a Vite build pipeline, and deployment-safe cache headers
• agent/server: heartbeat endpoint, list/inspect APIs, in-memory agent registry, and heartbeat-only or worker-mode agent process
• agent worker: control-plane HTTP client with resource sync, heartbeat, job claim, finish reporting, full/incremental backup execution, and restore execution
• server state: kvstore-backed job persistence, restart recovery for active jobs, independent evidence artifact retention, config-seeded resources, /api/v1/jobs, claim, finish, and cancel endpoints
• orchestration: scheduler due jobs persist as queued jobs with queued/running/terminal lifecycle transitions and backup metadata capture on successful finish
• REST API: target, storage, schedule CRUD endpoints and manual POST /api/v1/backups/now, operations overview at /api/v1/overview, with a checked OpenAPI spec in api/openapi/
• backups API: list/inspect/protect/unprotect, verification job queueing with persisted verification reports, verification job filtering, plus server-side retention policy CRUD and plan/apply with dry-run support
• restore API: restore preview plans that validate backup parent chains, enqueue restore jobs with dry-run and replace-existing restore options, and persist restore outcome summaries and independently retained hash-addressed evidence artifacts with backup-scoped job filtering and /api/v1/jobs/{id}/evidence export
• notification API: webhook rule CRUD for terminal job events with optional HMAC payload signatures and bounded delivery retries
• token API: scoped API token create/list/verify/revoke/prune with hashed verifier storage and copy-once bearer secret output
• user API: local user metadata create/list/get/delete plus role grants
• HTTP hardening: request IDs, no-store control-plane responses, and baseline browser security headers for API/WebUI responses

Important driver status: PostgreSQL, MySQL/MariaDB, and MongoDB are currently external-tool driver MVPs, not native wire-protocol implementations. Worker agents need the corresponding client tools installed. Passwords are no longer placed in process-visible command arguments for these tool-wrapper paths: PostgreSQL uses PGPASSWORD, MySQL/MariaDB uses MYSQL_PWD, and MongoDB uses a 0600 temporary --config file. Native protocol drivers and PITR remain roadmap work.

make build
./bin/kronos version

make build stamps version metadata from Git when available. Override VERSION, COMMIT, or BUILD_DATE for reproducible release builds. make release writes a platform-named binary and matching .sha256 checksum under bin/; make release-all writes linux/darwin amd64/arm64 artifacts by default.

Build and embed the WebUI before producing a UI-enabled binary:

make ui
make build

Container builds use the same stamped metadata:

docker build \
  --build-arg VERSION="$(git describe --tags --always --dirty 2>/dev/null || echo dev)" \
  --build-arg COMMIT="$(git rev-parse --short HEAD 2>/dev/null || echo unknown)" \
  --build-arg BUILD_DATE="$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
  -t kronos:local .

make check

In this workspace, a local Go toolchain is available at .tools/go/bin/go, so the equivalent direct check is:

.tools/go/bin/go test ./...

Inspect expanded configuration safely with redacted secret-like fields:

./bin/kronos --output pretty config inspect --config kronos.yaml

Structured command output supports --output json, --output pretty, --output yaml, and --output table; --output can be placed before the command or alongside command flags. CLI color is enabled only for terminals. Use --no-color or NO_COLOR=1 for plain output in logs and scripts.

Bootstrap the first admin user and copy-once admin token, then create narrower scoped tokens for automation. The bootstrap endpoint only works while both the user and token stores are empty. After that, the server enforces exact scopes plus resource:*, admin:*, or *.

export KRONOS_BOOTSTRAP_TOKEN=<random-one-time-bootstrap-secret>
./bin/kronos user bootstrap --id admin --email admin@example.com --display-name Admin --token-name initial-admin --bootstrap-token "$KRONOS_BOOTSTRAP_TOKEN"
export KRONOS_TOKEN=<copy-once-admin-secret>
./bin/kronos token create --user admin --name ci --scope backup:read,backup:write
export KRONOS_TOKEN=<copy-once-ci-secret>
./bin/kronos token verify
./bin/kronos --server http://127.0.0.1:8500 --token "$KRONOS_TOKEN" backup list

For non-local deployments, configure server.auth.bootstrap_token before the first bootstrap and pass the same value through --bootstrap-token or KRONOS_BOOTSTRAP_TOKEN.

After rotating credentials, preview and prune inactive token metadata:

./bin/kronos token prune --dry-run
./bin/kronos token prune

Common scope families are backup, target, storage, schedule, job, retention, restore, audit, token, user, agent, and metrics, each using :read or :write where applicable. overview uses metrics:read. Requested token scopes are capped by the token user's role when the token is created and by the user's current role on every authenticated request. The implemented authentication surface is token-only; local password login and TOTP are intentionally not accepted until that login flow exists.

Agents can use the same bearer secret through KRONOS_TOKEN or kronos agent --token <secret> and advertise concurrency with --capacity <n>. Worker agents need agent:write, job:write, target:read, storage:read, and backup:read for heartbeat, resource sync, claim, and finish calls. For TLS-enabled control planes, use an https:// server URL. Agents trust a private server CA with --tls-ca or KRONOS_TLS_CA, and mTLS enrollment uses --tls-cert/--tls-key or KRONOS_TLS_CERT/KRONOS_TLS_KEY.

Run kronos agent --work to claim and execute jobs. Worker mode syncs targets, storages, and backups from the control plane and needs a manifest signing key plus a chunk encryption key:

./bin/kronos keygen --key-id prod-2026
export KRONOS_MANIFEST_PRIVATE_KEY=<ed25519-private-key-hex>
export KRONOS_CHUNK_KEY=<32-byte-hex-key>
./bin/kronos agent --work --server http://127.0.0.1:8500 --token "$KRONOS_TOKEN" --key-id prod-2026

Config secret placeholders support environment variables and files, including structured JSON/YAML selectors such as ${file:secrets.yaml#database.password}. When server.master_passphrase is configured, sensitive target and storage option values are encrypted before being written to the control-plane state DB and decrypted on authorized reads. Agents also resolve full-value target/storage option placeholders at execution time, so API-created resources can store ${env:DB_PASSWORD} or ${file:/run/secrets/s3.json#secret_key} instead of raw credential values. Use CLI helper flags such as --password-ref, --access-key-ref, --secret-key-ref, --session-token-ref, or --credentials-ref to create those references without placing raw resource credentials in command history. The control plane rejects malformed placeholder syntax on target/storage create and update requests.

Manifest existence/signature check:

./bin/kronos backup verify \
  --manifest manifest.json \
  --public-key <ed25519-public-key-hex> \
  --storage-local /path/to/repo

Chunk integrity check, including decrypt/decompress/hash verification:

./bin/kronos backup verify \
  --manifest-key manifests/2026/04/23/backup-1.manifest \
  --level chunk \
  --chunk-key <32-byte-decryption-key-hex> \
  --public-key <ed25519-public-key-hex> \
  --storage-local /path/to/repo

Dry-run unreferenced chunk collection:

./bin/kronos gc \
  --storage-local /path/to/repo \
  --public-key <ed25519-public-key-hex> \
  --dry-run

./bin/kronos retention plan --input retention-plan.json

The input JSON contains policy, backups, and an optional now timestamp. The output marks each backup as kept or droppable with rule reasons.