writenotenow/kv-manager repository overview

⁠KV Manager - Docker Edition

A full-featured management platform for Cloudflare Workers KV, designed for engineering teams and large-scale workloads.

⁠Value Proposition

Browse namespaces with ease. Run bulk operations efficiently. Search across your entire KV footprint. Manage metadata and tags seamlessly. Automate backups to R2. Monitor metric thresholds automatically. Secure everything with Cloudflare Access Zero Trust.

Live Demo⁠ • GitHub⁠ • Wiki⁠ • Changelog⁠ • Release Article⁠

⁠Built on a Modern Stack

Frontend: React | TypeScript | Vite | Tailwind CSS | shadcn/ui

Backend: Cloudflare Workers + KV + D1 + R2 + Durable Objects + Zero Trust

⁠Accelerate Workflows with Powerful Features

• 🗂️ Namespace & Key Management - Full CRUD operations with cursor-based pagination and Grid/List view toggle
• 🎨 Color Tags - 27-color palette for visual namespace organization
• 📊 Dual Metadata System - KV Native (1024 bytes) + D1 Custom (unlimited) metadata
• 🏷️ Tag Organization - Unlimited tags stored in D1 for easy filtering and search
• 🔍 Advanced Search - Cross-namespace search by key name, tags, and custom metadata
• ⚡ Bulk Operations - Process thousands of keys efficiently (delete, copy, TTL, tags)
• 🔄 Cross-Namespace Migration - Migrate keys between namespaces with TTL preservation, metadata migration, and rollback support
• 📥 Import/Export - JSON/NDJSON support with collision handling
• ☁️ R2 Backup & Restore - Cloud-native backup with batch operations
• ⏱️ Scheduled Threshold Monitoring - Track metrics automatically via hourly cron triggers and Cloudflare Analytics API polling to receive alerts when limits are exceeded.
• 📈 Job History - Complete audit trail with event timelines and advanced filtering
• 📊 Metrics Dashboard - View KV analytics, operation counts, and latency percentiles
• 🏥 Health Dashboard - At-a-glance operational status with health score (including an automatic 15-point penalty for critical threshold breaches), job history, and backup coverage
• 🔔 Webhooks - Event-driven HTTP notifications for key operations, bulk jobs, and failures
• 🔐 Enterprise Auth - Cloudflare Access (Zero Trust) integration
• 🎨 Modern UI - Dark/light themes, responsive design, built with React + Tailwind CSS

⁠Deploy Instantly with Docker

Pull and run:

docker pull writenotenow/kv-manager:latest

docker run -d \
  -p 8787:8787 \
  -e ACCOUNT_ID=your_cloudflare_account_id \
  -e API_KEY=your_cloudflare_api_token \
  -e TEAM_DOMAIN=https://yourteam.cloudflareaccess.com \
  -e POLICY_AUD=your_cloudflare_access_aud_tag \
  --name kv-manager \
  writenotenow/kv-manager:latest

Access at: http://localhost:8787⁠

⁠⚙️ Configuration

⁠Required Environment Variables

⁠Setup Steps

1. Create D1 database:

   npx wrangler d1 create kv-manager-metadata
   npx wrangler d1 execute kv-manager-metadata --remote --file=worker/schema.sql
   

   Copy

2. Get credentials:

   • Account ID: Cloudflare Dashboard⁠ URL
   • API Token: Create token⁠ with KV + D1 Edit
   • Team Domain & AUD: Configure Cloudflare Access⁠

Complete Setup Guide →⁠

⁠🐞 Troubleshooting

View logs:

docker logs kv-manager

Common issues:

Health check:

curl http://localhost:8787/health

Complete Troubleshooting Guide →⁠

⁠🔄 Updates

Pull and restart:

docker pull writenotenow/kv-manager:latest
docker compose up -d  # or docker stop/rm/run

Pin version (recommended for production):

services:
  kv-manager:
    image: writenotenow/kv-manager:<version> # see https://github.com/neverinfamous/kv-manager/releases

⁠📦 Image Details

• Base: Node.js 24-alpine (LTS)
• Size: ~150MB
• Architectures: linux/amd64, linux/arm64
• User: Non-root
• Health: /health endpoint

Available tags: latest, v<version> (see releases⁠), sha-XXXXXX

⁠📚 Resources

• 📖 Full Documentation⁠ - Complete guides and references
• 🐳 Docker Hub⁠ - Image repository
• 💻 GitHub⁠ - Source code
• 🐛 Issues⁠ - Bug reports

⁠💬 Support

• 📧 Email: [email protected]⁠
• 🛡️ Security: See Security Policy⁠

⁠📄 License

MIT License - see LICENSE⁠

Made with ❤️ for the Cloudflare and Docker communities