Cloudflare Durable Objects Manager

🎯 Live Demo | 📦 GitHub | 📚 Wiki | 📦 NPM Package

✨ Major Features

Instance Migration

Move instances between namespaces with three flexible cutover modes: Copy Only clones data without touching the source, Copy + Delete removes the source after transfer, and Copy + Freeze locks the source to prevent state divergence. A visual wizard guides you through namespace selection, target naming, and progress tracking. All migrations are logged to Job History for audit purposes.

Instance Freeze/Unfreeze

Protect critical instances from accidental modifications with read-only freeze mode. Frozen instances display a snowflake indicator in both Grid and List views, and the API enforces protection by returning 423 Locked for PUT, DELETE, and Import operations. Restore write access with one-click unfreeze when ready to make changes.

Automated Database Migrations

In-app visual banner prompts for database upgrades when schema changes are detected. Apply all pending migrations with one click. The system tracks schema versions to ensure data integrity and automatically detects legacy deployments to bridge the gap during upgrades.

Namespace Management

Auto-discovery: Automatically discover DO namespaces from your Cloudflare account via API. DO Manager fetches all deployed Workers, identifies Durable Object bindings, and presents them in an organized interface. System namespaces (kv-manager, d1-manager, do-manager internals) are automatically filtered to prevent accidental deletion.

Manual Configuration: For custom setups or Workers not yet deployed, manually add namespaces with class name, script name, and optional admin hook endpoint. Configuration includes support for both SQLite and KV storage backends.

Clone & Download: Duplicate namespace configurations with a new name for testing or migration scenarios. Deep Clone allows cloning a namespace AND all its instances plus storage data in an atomic 2-phase process. Export namespace settings as JSON for backup or sharing across environments. Toggle between card grid and sortable table List views.

Instance Management

Instance Tracking: Track DO instances by human-readable names or hex IDs. Create new instances with custom names directly from the UI. Color-code instances with 27+ preset colors for visual organization. Rename instances directly from the list view.

Clone & Download: Copy all storage data from one instance to another with a single click. Export instance storage as JSON with metadata including timestamp and key count. Compare storage between exactly two instances to identify differences.

Storage Management: View and edit storage contents with full JSON support and syntax validation. Search and filter keys in real-time to find data quickly. Multi-select keys with always-visible checkboxes for batch operations. Import keys from JSON files or paste JSON directly without file upload.

Instance Tags & Organization

Add custom freeform tags (e.g., env:production, team:backend) to any instance. A dedicated tag search tab finds instances by tag across ALL namespaces. Assign color tags to namespaces for better visual distinction in Grid and List views.

SQL Console

Execute any SQL query against SQLite-backed Durable Objects with a rich editor featuring syntax highlighting, auto-complete, and query formatting. View results in a sortable table format. Query history provides quick access to recently executed queries.

Quick Queries: Pre-built templates accelerate common operations including Select All Rows, Row Count, Table Schema, List All Tables, List Indexes, Sample Rows, and Create Table boilerplate. Saved queries allow storing frequently used queries per namespace for quick reuse.

Multi-Select & Batch Operations

Always-Visible Checkboxes: Select namespaces, instances, and storage keys directly from lists without entering a special mode. Floating selection toolbar shows count and provides Select All and Clear actions.

Batch Downloads: Export multiple namespace configs as a ZIP file with manifest. Export multiple instance storage as a ZIP with metadata. Export selected storage keys as JSON with instance/namespace context.

Batch Delete & Backup: Delete multiple namespaces, instances, or storage keys with confirmation dialogs. Backup multiple instances to R2 simultaneously with progress tracking. All batch operations are tracked in job history for audit purposes.

Admin Hook System

NPM Package Integration: Install the do-manager-admin-hooks package for easy integration. Extend your Durable Object class and call handleAdminRequest() in your fetch handler. Configuration options include custom base path, authentication requirements, and admin key validation.

Copy-Paste Template: For custom setups, click "Get Admin Hook Code" in the namespace view to generate TypeScript code. The template handles all standard admin endpoints including list, get, put, delete, SQL execution, alarm management, and export/import operations.

Endpoints: Admin hooks provide 8+ endpoints covering storage operations (/admin/list, /admin/get, /admin/put, /admin/delete), SQL execution (/admin/sql), alarm management (/admin/alarm), and data portability (/admin/export, /admin/import).

Data Management

View the current alarm state for any instance with timestamp display. Set new alarms using an intuitive date/time picker interface. Delete existing alarms with a single click. All alarm operations are logged to job history.

Snapshot DO storage to R2 with automatic timestamping. Backups include full storage contents, metadata, and export timestamp. Batch backup multiple instances simultaneously with progress indicators.

Browse backup history for each instance with timestamps and sizes. Restore from any backup with automatic instance refresh. Webhook notifications on backup completion for integration with external systems.

Search & Job History

Search for storage keys by name across all instances in your account. Value search capability finds data within JSON values across instances. Filter search to specific namespaces to narrow results.

Results grouped by namespace for easy navigation. Search terms highlighted in results for quick identification. Value previews show the matching portion of values for value searches. All search operations logged to job history.

Records all operations including namespace (create, delete, clone, download), instance (create, delete, clone, download), storage keys (CRUD operations, batch delete, batch export, import), alarms (set, delete), backup/restore operations, and search operations (key search, value search).

View status, progress percentage, and timing information. Error details for failed operations with full stack traces. Filter by status (pending, in_progress, completed, failed) or namespace. Real-time updates as jobs progress.

Webhooks

Send HTTP notifications on key events including backup_complete, restore_complete, alarm_set, alarm_deleted, job_failed, and batch_complete. Configurable event selection allows enabling only the events you need.

Optional HMAC signature verification for request authenticity. Test webhook functionality before going live with dedicated test endpoint. Webhook configuration stored in D1 with full CRUD operations.

Health & Metrics Dashboard

Total namespaces, instances, and alarms at a glance. Aggregate storage usage across all instances. Recent activity timeline showing operations in last 24 hours and 7 days.

Stale instance detection identifies instances not accessed in 7+ days. Storage quota alerts warn when instances approach the 10GB DO storage limit (80% warning threshold, 90% critical threshold). Active alarms list shows all pending alarms with countdown timers.

Request volume visualization over time showing operation trends. Storage usage metrics with per-instance and aggregate views. CPU time metrics displaying average and total CPU consumption. All metrics powered by Cloudflare's GraphQL Analytics API.

Error Logging

Consistent format with module, operation, context, and metadata fields. Module-prefixed error codes (NS_CREATE_FAILED, INST_DELETE_FAILED, BKP_RESTORE_FAILED) enable easy filtering and alerting.

Severity levels (error, warning, info) for proper alerting thresholds. Automatic webhook triggers for job failures. Full stack trace capture for debugging purposes.

⚡ Performance & Code Quality

Bundle Optimization: Main bundle cut by 48% (702 KB → 364 KB) via code splitting and lazy loading of heavy components. Frontend caching layer with 5-minute TTL minimizes API calls. Parallelized backend queries and upfront indexing deliver lightning-fast global search results.

Type Safety: Strict TypeScript with noUncheckedIndexedAccess and noImplicitOverride enabled. ESLint uses strictTypeChecked and stylisticTypeChecked rulesets for maximum code robustness. Rate limit protection with exponential backoff retry logic for API calls.

🔧 Technical Stack

Frontend: React, TypeScript, Vite, Tailwind CSS, shadcn/ui component library

Backend: Cloudflare Workers for serverless compute, D1 for metadata and job tracking, R2 for backup storage, Zero Trust for enterprise authentication

Authentication: Cloudflare Access integration with JWT validation, support for multiple identity providers (GitHub OAuth, Google, Azure AD, Okta, email), local development mode with mock data and no auth required

🚀 Getting Started

Local Development

Step 1: Clone the repository

git clone https://github.com/neverinfamous/do-manager.git
cd do-manager

Step 2: Install dependencies

npm install

Step 3: Initialize local D1 database

npx wrangler d1 execute do-manager-metadata-dev --local --file=worker/schema.sql

Step 4: Start development servers (in separate terminals)

Terminal 1 - Frontend:

npm run dev

Terminal 2 - Worker API:

npx wrangler dev --config wrangler.dev.toml --local

Open http://localhost:5173 - no authentication required, mock data included.

Production Deployment

Step 1: Authenticate with Cloudflare

npx wrangler login

Step 2: Create D1 database

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

Step 3: Create R2 bucket (for backups)

npx wrangler r2 bucket create do-manager-backups

Step 4: Configure Wrangler

cp wrangler.toml.example wrangler.toml

Edit wrangler.toml with your database_id from Step 2.

Step 5: Set up Cloudflare Access

1. Go to Cloudflare Zero Trust
2. Configure authentication (GitHub OAuth, Google, etc.)
3. Create an Access Application for your domain
4. Copy the Application Audience (AUD) tag

Step 6: Create API Token

1. Go to Cloudflare API Tokens
2. Create Custom Token with:
   • Account → Workers Scripts → Read
   • Account → D1 → Edit (if managing D1-backed DOs)

Note: Both API Tokens (Bearer auth) and Global API Keys (X-Auth-Key auth) are supported.

Step 7: Set secrets

npx wrangler secret put ACCOUNT_ID
npx wrangler secret put API_KEY
npx wrangler secret put TEAM_DOMAIN
npx wrangler secret put POLICY_AUD

Step 8: Deploy

npm run build
npx wrangler deploy

Upgrading Existing Installations

If you already have DO Manager v1.0.0 deployed, upgrade to v1.1.0 with these steps:

1. Pull the latest changes: git pull origin main
2. Update dependencies: npm install
3. Deploy the worker: npx wrangler deploy
4. Apply migrations: Open the app in your browser. An "Upgrade Available" banner will appear. Click "Upgrade Now" to apply the new database migrations automatically.

🔌 Admin Hook Setup

To manage a Durable Object's storage, you need to add admin hook methods to your DO class. There are two options:

Option A: NPM Package (Recommended)

Step 1: Install the package

npm install do-manager-admin-hooks

Step 2: Extend your Durable Object class

import { withAdminHooks } from 'do-manager-admin-hooks';

export class MyDurableObject extends withAdminHooks() {
  async fetch(request: Request): Promise<Response> {
    // Handle admin requests first (required for DO Manager)
    const adminResponse = await this.handleAdminRequest(request);
    if (adminResponse) return adminResponse;

    // Your custom logic here
    return new Response('Hello from my Durable Object!');
  }
}

That's it! The package handles all admin endpoints automatically.

Configuration options:

export class SecureDO extends withAdminHooks({
  basePath: '/admin',      // Change admin endpoint path (default: '/admin')
  requireAuth: true,       // Require authentication
  adminKey: 'secret-key',  // Admin key for auth
}) {
  // ...
}

Option B: Manual Copy-Paste

Click "Get Admin Hook Code" in the namespace view to generate copy-paste TypeScript code for your DO class. The template includes all necessary endpoints and handles both SQLite and KV backends.

Enable in DO Manager

1. Deploy your Worker with admin hooks installed
2. In DO Manager, add your namespace with the Admin Hook Endpoint URL (e.g., https://my-worker.workers.dev)
3. Admin hooks are automatically enabled when you save with a URL
4. The green "Admin Hook Enabled" badge confirms it's working

📋 API Reference

DO Manager provides 35+ RESTful API endpoints for comprehensive management:

• Namespace Operations - List, discover, create, delete, clone, export
• Instance Operations - List, create, delete, clone, export, color tagging, diff comparison
• Storage Operations - Get, update, import from JSON, batch delete, batch export
• SQL Operations - Execute queries, saved queries CRUD
• Alarm Management - Get, set, delete alarms
• Backup & Restore - List backups, create backup, restore from backup, batch backup
• Search - Cross-namespace key search, value search within JSON
• Job History - List jobs with filtering by status or namespace
• Webhooks - CRUD operations, test webhook endpoints
• Health & Metrics - System health summary, analytics data

📊 External Logging Integration

DO Manager supports integration with external observability platforms via Cloudflare's native OpenTelemetry export. Send traces and logs to services like Grafana Cloud, Datadog, Honeycomb, Sentry, and Axiom.

Step 1: Create a destination in Cloudflare Dashboard

1. Go to Workers Observability
2. Click Add destination
3. Configure your provider's OTLP endpoint and authentication headers

Step 2: Update wrangler.toml

[observability]
enabled = true

[observability.traces]
enabled = true
destinations = ["your-traces-destination"]

[observability.logs]
enabled = true
destinations = ["your-logs-destination"]

For detailed logging integration options including Workers Analytics Engine, Tail Workers, and Logpush, see the full documentation in the GitHub repository.

🙈 Hidden System Namespaces

DO Manager automatically hides internal system Durable Objects to prevent accidental deletion:

• kv-manager_* - KV Manager internal DOs (ImportExportDO, BulkOperationDO)
• d1-manager_* - D1 Manager internal DOs
• do-manager_* - DO Manager internal DOs

These namespaces are filtered during auto-discovery. To modify the filter list, edit worker/routes/namespaces.ts and customize the SYSTEM_DO_PATTERNS array.

🐛 Troubleshooting

"Failed to fetch from Cloudflare API"

• Verify ACCOUNT_ID is correct
• Ensure API token has Workers Scripts Read permission
• If using Global API Key, ensure email is correct in worker/routes/namespaces.ts

"Admin hook not configured"

• Add admin hook methods to your DO class using the NPM package or copy-paste template
• Set the endpoint URL in namespace settings
• Ensure your Worker is deployed and accessible

"No namespaces discovered"

• You may not have any Durable Objects deployed
• System namespaces are filtered by default (see Hidden System Namespaces section)

"Clone instance creates empty instance"

• Ensure your admin hooks use the correct export/import format
• Export should return: { data: {...}, exportedAt: "...", keyCount: N }
• Import should accept: { data: {...} }
• The do-manager-admin-hooks NPM package handles this automatically

Authentication loop

• Check TEAM_DOMAIN includes https://
• Verify POLICY_AUD matches your Access application's AUD tag

🎯 Why This Release Matters

Durable Objects are powerful primitives for building stateful applications on Cloudflare's edge network, but managing them at scale has traditionally required custom tooling or manual API calls. DO Manager fills this gap by providing a comprehensive, enterprise-ready management interface that handles everything from namespace discovery to backup/restore operations.

Whether you're managing configuration storage, game state, real-time collaboration data, or any other stateful workload, DO Manager makes it dramatically easier to inspect, modify, and monitor your Durable Objects. The combination of SQL console, batch operations, global search, and R2 backups provides both operational efficiency and data safety suitable for production use.

Pro Tip: Use instance tags to organize by environment (env:production) or team (team:backend). Combined with global search, tag filtering, and batch operations, this becomes a powerful way to manage related instances at scale!

🚧 Roadmap & Statistics

Future Versions: Scheduled backup policies with retention rules. GraphQL API in addition to REST. Integration with Cloudflare Analytics Engine for custom metrics.

60+ React components, 35+ API endpoints, 12,000+ lines of TypeScript code. React with TypeScript, Vite, and Tailwind CSS for optimal performance. 48% smaller bundle size (702 KB → 364 KB). Support for both SQLite and KV storage backends. Compatible with all modern browsers and Cloudflare Access identity providers.

🤝 Contributing

We welcome contributions from the community! Fork the repository on GitHub, create a feature branch, commit your changes with clear messages, and open a Pull Request. Bug reports, feature requests, and documentation improvements are all appreciated.

📞 Support & Resources

Project Links:

• GitHub Repository
• Live Demo
• Wiki Documentation
• NPM Package
• Admin Hooks GitHub
• Email: admin@adamic.tech

🙏 Acknowledgments

Special thanks to Cloudflare for the Workers, Durable Objects, D1, and R2 platform that makes this possible. Thanks to the React team for React 19, shadcn for the excellent UI component library, and the Vite team for the incredible build tool. Most importantly, thank you to all community contributors for feedback, testing, and support during development.

📄 License

DO Manager is released under the MIT License. See the LICENSE file in the repository for full details.

Thank you to everyone in the Cloudflare community for your interest and support! We're excited to see how you use DO Manager to simplify your Durable Objects management workflows. Whether you're managing a handful of instances or hundreds across multiple namespaces, DO Manager is built to scale with your needs.

Built with ❤️ for the Cloudflare community