Cloud Manager

A comprehensive, real-time system for managing distributed Doh instances through a unified web dashboard. Cloud Manager enables remote administration, file synchronization, database backup orchestration, Git repository management, SSL certificate monitoring, reverse proxy configuration, and direct SSH terminal access across multiple cloud-connected Doh deployments.

What is Cloud Manager?

Cloud Manager transforms individual Doh instances into a connected, event-driven ecosystem where you can:

• Monitor multiple instances from a single, real-time dashboard
• Control remote instances with commands, Git operations, and full SSH terminal access
• Synchronize files and folders between instances with smart, bidirectional sync
• Backup databases with automated scheduling and cross-instance mirroring
• Share access to instances with team members using granular, time-limited permissions
• Manage Git repositories across your infrastructure from a central UI
• Monitor SSL certificates with auto-renewal scheduling
• Proxy traffic to instances behind firewalls via secure reverse proxy
• Integrate with AI assistants (Claude Code, Cursor, etc.) via the Model Context Protocol (MCP)

Think of it as your mission control for distributed Doh deployments, built on a secure, modern, and event-driven architecture.

Core Concepts

Instances

Each connected Doh deployment appears as an "instance" in Cloud Manager. Instances maintain persistent connections via WebSocket and can be controlled remotely. Instances can be owned or shared, with ownership and permissions clearly displayed in the UI.

The Cloud Manager Host

A Cloud Manager is not a special type of server; it is simply a standard Doh instance with the cloud_manager module installed. This provides incredible flexibility:

• Any Instance, Any Cloud: Any Doh instance can be turned into a Cloud Manager host
• Clouds of Clouds: Run multiple, isolated Cloud Managers for different teams, projects, or environments
• Networking: The Cloud Manager instance only needs to be network-accessible to instances that will connect to it

Sharing

Any instance owner can share access with other users—either to specific instances or all their instances at once. Shares can have custom permissions (e.g., read-only, command execution) and optional expiration dates.

File Synchronization

Smart bidirectional sync between instances with server-side comparison, conflict detection, and progress tracking. Options include:

• One-time sync for ad-hoc transfers
• Active Mirrors for push-based ongoing synchronization
• Pull Mirrors for destination-initiated sync
• Scheduled Mirrors for automated sync at regular intervals
• Pins for bookmarking frequently-used locations

Remote Management

Cloud Manager provides multiple ways to manage instances remotely:

• Commands: Execute predefined or custom shell commands
• Git: Full-featured UI for managing repositories
• SSH Terminal: Fully functional, browser-based terminal for direct shell access
• Database Backup: Create, restore, and replicate database backups

MCP (Model Context Protocol)

Cloud Manager implements the Model Context Protocol (MCP), enabling AI assistants and LLMs to securely interact with managed instances. When you use AI coding tools like Claude Code, Cursor, or other MCP-compatible editors, Cloud Manager exposes your instances as controllable resources—allowing AI to list instances, read logs, execute commands, sync files, and manage deployments on your behalf.

Important: Instances must explicitly opt-in by setting mcp_controllable: true in their configuration. Only instances with this flag can be controlled via MCP.

Reverse Proxy

Cloud Manager can act as a reverse proxy for managed instances, creating HTTPS servers that forward HTTP and Socket.IO traffic over the secure WebSocket connection. This allows external access to instances without direct network exposure.

Getting Started

Part 1: Setting Up Your Cloud Manager Host

Step 1: Install the Cloud Manager Module

On the Doh instance you want to designate as your Cloud Manager, run:

doh install cloud cloud_manager

Step 2: Create a Superadmin User

A Cloud Manager needs at least one user account to own and manage instances:

doh poduser

Follow the prompts to create a superadmin user. This user will be able to log in to the Cloud Manager and anchor other instances to their account.

Step 3: Start Your Manager

doh run

Ensure this instance is accessible over the network from any other instances you plan to connect.

Part 2: Connecting an Instance to Your Manager

From any other Doh instance you want to manage:

doh cloud anchor http://your-cloud-manager-url.com

This command will prompt for the username and password you created in Part 1. Your credentials are used only once to get a secure token and are never stored on the client instance.

Once anchored, the instance will appear on your Cloud Manager's dashboard at /admin/cloud.

The Dashboard

The Cloud Manager dashboard at /admin/cloud is a centralized UI for all management tasks. It features a responsive, event-driven interface that updates in real-time without polling.

Dashboard Tabs

Key UI Components

• Instance Selection Toolbar: Once an instance is selected, a floating toolbar appears providing quick access to common actions like update, restart, and upgrade
• Recent Actions Panel: A consolidated, real-time log of all commands and operations performed across instances, showing their status and output
• Mobile Support: Responsive hamburger menu and mobile toolbar for managing instances on smaller screens

Feature Deep Dives

File Synchronization

The File Sync tab provides a modern, efficient synchronization system with server-side comparison and cross-platform compatibility.

One-Time Sync

1. Select a source instance and browse to the file/folder
2. Select a destination instance (files sync to the same path by default)
3. The system performs server-side analysis showing all files with their sync status (identical, different, new)
4. Execute the sync with real-time, file-level progress feedback

Active Mirrors (Push-Based)

For ongoing synchronization, save a sync configuration as an "Active Mirror". The dashboard shows the mirror's status (in sync, needs sync, stale) and allows one-click re-sync.

Pull Mirrors (Destination-Initiated)

Pull Mirrors work in the opposite direction—the destination instance pulls changes from a source. Useful when the destination needs to control when updates are applied.

Scheduled Mirrors

Configure automated sync operations at regular intervals:

The scheduler checks mirrors every 60 seconds and executes sync when due.

Pins

Save location bookmarks for quick navigation between frequently-used paths across instances. Pins store both left and right pane positions for instant dual-pane restoration.

Advanced Features

• Server-Side Comparison: Eliminates duplicate comparison logic by centralizing file analysis in the Cloud Manager
• Cross-Platform Compatibility: Automatic line ending normalization (CRLF/LF) for text files
• Large File Support: Chunked streaming for efficient transfer with progress tracking
• Conflict Resolution: Automatic backup of destination files that are newer than source before overwriting
• Glob Pattern Exclusions: Standard glob patterns for file filtering (e.g., node_modules/**, .doh/**)

Database Backup System

The DB Backup tab provides comprehensive database backup, restore, and replication capabilities.

Creating Backups

1. Select an instance and database from the browser
2. Click "Create Backup" to generate a timestamped backup (tar.gz with embedded metadata)
3. WAL checkpoint is performed before backup for consistency

Restoring Backups

1. Browse to the backup you want to restore
2. Click "Restore" to replace the current database with the backup
3. Undo support allows reverting the last restore operation

Backup Mirrors

Configure cross-instance backup replication:

1. Set a source instance and database
2. Set one or more destination instances
3. Backups are automatically replicated when created

Scheduling

Configure automated backups with preset intervals (1m to 1y). The scheduler:

• Checks schedules every 60 seconds
• Creates backups when due
• Applies retention policies to clean up old backups

Retention Policies

• Auto mode: Automatically delete backups beyond a configured count
• Manual mode: Keep all backups until explicitly deleted
• Configurable retention count per schedule

Browser Features

• Search and filter databases and backups
• Column sorting and pagination
• Expandable rows for backup details

SSH Terminal Access

Cloud Manager provides a fully functional, browser-based SSH terminal compatible with both Bun and Node.js runtimes.

How to Use

Navigate to the SSH tab, or click the "Terminal" button on any instance card. A terminal window opens with direct shell access to the instance.

Technical Implementation

The terminal uses the script command on Unix-like systems to allocate a proper pseudo-terminal (PTY). This ensures the shell runs in interactive mode with a visible prompt and full terminal feature support.

Features

• Real-time, low-latency interaction via WebSockets
• Terminal resizing with proper SIGWINCH handling
• Full ANSI color and UTF-8 support
• Quick command buttons for common operations (cd ~, doh update, etc.)
• Secure permission-based access

Git Repository Management

The Git tab provides a comprehensive UI for managing Git repositories on any connected instance.

Features

• Discovery: Automatically discovers all Git repositories within an instance's project directory
• Status: View staged/unstaged files, commit history, and branch information
• File Actions: Stage, unstage, and commit files directly from the UI
• Branching: View, create, and switch between branches
• Remotes: Pull from and push to remote repositories
• Diff Viewer: See changes between commits using Monaco Editor

SSL Certificate Management

The SSL tab monitors SSL certificates across instances and provides auto-renewal scheduling.

Status Monitoring

• Certificate expiration dates and validity
• Status caching with configurable refresh intervals
• Visual indicators for expiring/expired certificates

Auto-Renewal Scheduling

Configure automatic certificate renewal checks:

1. Select instance and hostname
2. Set check interval (uses same preset intervals as mirrors)
3. Scheduler automatically triggers renewal when certificates approach expiration

Operations Audit Log

All SSL operations are logged with:

• User who performed the action
• Instance and hostname affected
• Operation type and status
• Timestamp

Reverse Proxy System

Cloud Manager can act as a reverse proxy for managed instances, allowing external access to instances behind firewalls or NAT.

How It Works

When an instance connects with reverse proxy enabled:

1. Cloud Manager creates a dedicated HTTPS server on the configured external_port
2. Socket.IO server attached for real-time connections
3. All HTTP and Socket.IO traffic forwarded to the instance via the existing secure WebSocket

Configuration

On the Cloud Manager (ensure SSL certificates are configured):

express_config:
  ssl_info:
    key: '/path/to/private.key'
    cert: '/path/to/certificate.crt'

On the Managed Instance:

cloud:
  endpoint: 'https://your-cloud-manager.com'
  reverse_proxy:
    enabled: true
    external_port: 4443

Pause/Resume

The Proxies tab displays all active reverse proxies with controls to:

• Pause: Temporarily disable external access without disconnecting the instance
• Activate: Re-enable external access

Proxy states persist across Cloud Manager restarts (stored in /.doh/static/cloud_proxies.yaml).

Architecture Details

• Per-Instance Ports: Each proxied instance gets its own unique port
• Dual Protocol Support: Both HTTP and Socket.IO proxied over the same port
• Cookie Management: Per-client cookie jars maintain authentication state
• Timeout Protection: 35-second timeout (longer than instance's 30s timeout)
• Automatic Cleanup: Servers and mappings removed when instance disconnects

Redbird Proxy Management

The Redbird tab manages Redbird reverse proxy configurations on instances that have Redbird installed.

Features

• List all proxy sites configured on an instance
• Create, edit, and delete proxy site mappings
• View proxy status and SSL certificate status per site
• Reload Redbird configuration after changes

Cloud Sharing

The Shares tab allows secure sharing of instance access with other users.

Share Types

Permissions

Shares can grant specific permissions:

• read:cloud_instance - View instance status and information
• command:cloud_instance - Execute commands on the instance
• update:cloud_instance - Manage instance settings and files

If no permissions are specified, the sharee inherits the owner's full permissions.

Expiration

Shares can be configured with optional expiration dates for time-limited access.

How It Works

When you share an instance, the sharee sees it in their dashboard under "Shared with Me". All Cloud Manager features (Git, SSH, File Sync, etc.) respect sharing permissions.

Configuration

Cloud Manager Host Configuration

# boot.pod.yaml or pod.yaml
cloud_manager:
  auth_required: true           # Require authentication for dashboard
  session_timeout: 3600000      # Session timeout in ms (1 hour)
  max_instances_per_user: 10    # Maximum instances per user
  command_timeout: 30000        # Default command timeout in ms (30 seconds)
  heartbeat_timeout: 120000     # Instance heartbeat timeout in ms (2 minutes)
  jwt_secret: 'your-secret'     # JWT signing secret (required for production)

# SSL configuration for reverse proxy
express_config:
  ssl_info:
    key: '/path/to/private.key'
    cert: '/path/to/certificate.crt'

Managed Instance Configuration

# boot.pod.yaml or pod.yaml
cloud:
  endpoint: 'https://your-cloud-manager.com'
  mcp_controllable: true  # Allow AI assistants to control this instance

  # Optional: Enable reverse proxy
  reverse_proxy:
    enabled: true
    external_port: 4443  # Unique port for this instance

Security & Architecture

JWT Authentication

Instance connections are secured using JSON Web Tokens (JWT):

• Short-lived siteAuthToken generated during anchor process
• Tokens validated on every connection
• Revocation list support for invalidating compromised tokens

Contextual Permissions

Access control is dynamically evaluated against the action being performed and the specific object being acted upon. This enables:

• Fine-grained instance-level permissions
• Secure sharing without over-provisioning access
• Runtime context validation (e.g., checking ownership before allowing commands)

Event-Driven Architecture

The dashboard uses WebSocket connections for real-time updates:

• No polling—data pushed instantly when state changes
• Instance status updates broadcast to all connected dashboards
• Progress tracking for long-running operations

Database-Driven Persistence

All persistent data (shares, mirrors, schedules, pins) stored in database tables ensuring data integrity across sessions and restarts.

API Reference

REST Endpoints

Instance Management

File Operations & Sync

Mirrors

Pins

Shares

SSL Operations

Redbird Operations

Proxies

Authentication

WebSocket Events

Real-Time Updates

Terminal I/O

Instance Events

MCP Protocol (AI/LLM Integration)

The Model Context Protocol enables AI assistants to interact with Cloud Manager programmatically. MCP-compatible tools (Claude Code, Cursor, etc.) connect via a dedicated Socket.IO namespace (/mcp) and can then control instances using the authenticated user's permissions.

How It Works:

1. Your AI tool's MCP server connects to Cloud Manager's /mcp namespace
2. It authenticates using your siteAuthToken
3. The AI can then issue commands to any instance marked mcp_controllable: true
4. All operations respect the same permission system as the dashboard

Note: Only instances that have opted-in with mcp_controllable: true will appear in MCP command results.

Authentication

socket.emit('mcp:authenticate', {
  siteAuthToken: '<jwt>',
  connectionType: 'mcp_client'
}, callback);

Available Commands

These commands are what AI assistants use to interact with your instances:

Database Schema

Cloud Manager automatically creates and manages the following tables.

Core Tables

cloud_shares

CREATE TABLE cloud_shares (
  id TEXT PRIMARY KEY,
  sharerId TEXT NOT NULL,
  shareeId TEXT NOT NULL,
  instanceId TEXT,              -- NULL for global shares
  permissions TEXT,             -- JSON array or NULL for all
  description TEXT,
  createdTimestamp TEXT NOT NULL,
  expiresTimestamp TEXT,
  isEnabled INTEGER DEFAULT 1
);

File Sync Tables

active_mirrors

CREATE TABLE active_mirrors (
  id TEXT PRIMARY KEY,
  userId TEXT NOT NULL,
  sourceInstanceId TEXT NOT NULL,
  destinationInstanceId TEXT NOT NULL,
  sourcePath TEXT NOT NULL,
  targetPath TEXT NOT NULL,
  type TEXT NOT NULL,              -- 'File' or 'Folder'
  description TEXT,
  createdTimestamp TEXT NOT NULL,
  lastCheckTimestamp TEXT,
  lastSyncTimestamp TEXT,
  needsSync INTEGER,               -- 0 for false, 1 for true
  isEnabled INTEGER DEFAULT 1
);

pull_mirrors

CREATE TABLE pull_mirrors (
  id TEXT PRIMARY KEY,
  userId TEXT NOT NULL,
  sourceInstanceId TEXT NOT NULL,
  destinationInstanceId TEXT NOT NULL,
  path TEXT NOT NULL,
  type TEXT NOT NULL,
  description TEXT,
  createdTimestamp TEXT,
  lastCheckTimestamp TEXT,
  lastSyncTimestamp TEXT,
  needsSync INTEGER,
  isEnabled INTEGER DEFAULT 1
);

pins

CREATE TABLE pins (
  id TEXT PRIMARY KEY,
  userId TEXT NOT NULL,
  name TEXT NOT NULL,
  description TEXT,
  leftInstanceId TEXT,
  rightInstanceId TEXT,
  leftPath TEXT,
  rightPath TEXT,
  createdTimestamp TEXT
);

SSL Tables

ssl_operations

CREATE TABLE ssl_operations (
  id TEXT PRIMARY KEY,
  userId TEXT,
  instanceId TEXT,
  hostname TEXT,
  operation TEXT,
  status TEXT,
  timestamp TEXT
);

ssl_status

CREATE TABLE ssl_status (
  id TEXT PRIMARY KEY,
  instanceId TEXT,
  hostname TEXT,
  port INTEGER,
  certStatus TEXT,
  certMtime TEXT,
  lastUpdated TEXT
);

ssl_schedules

CREATE TABLE ssl_schedules (
  id TEXT PRIMARY KEY,
  instanceId TEXT,
  hostname TEXT,
  scheduleMode TEXT,
  interval TEXT,
  enabled INTEGER DEFAULT 1,
  lastCheckTimestamp TEXT
);

Redbird Tables

redbird_operations

CREATE TABLE redbird_operations (
  id TEXT PRIMARY KEY,
  userId TEXT,
  instanceId TEXT,
  operation TEXT,
  status TEXT,
  timestamp TEXT
);

redbird_status

CREATE TABLE redbird_status (
  id TEXT PRIMARY KEY,
  instanceId TEXT,
  configStatus TEXT,
  lastUpdated TEXT
);

Backup Tables

backup_schedules

CREATE TABLE backup_schedules (
  id TEXT PRIMARY KEY,
  userId TEXT,
  instanceId TEXT,
  database TEXT,
  scheduleMode TEXT,
  interval TEXT,
  retentionMode TEXT,
  retentionCount INTEGER,
  enabled INTEGER DEFAULT 1,
  lastBackupTimestamp TEXT
);

backup_mirror_destinations

CREATE TABLE backup_mirror_destinations (
  id TEXT PRIMARY KEY,
  userId TEXT,
  sourceInstanceId TEXT,
  sourceDatabase TEXT,
  destinationInstanceId TEXT,
  enabled INTEGER DEFAULT 1
);

backup_mirror_history

CREATE TABLE backup_mirror_history (
  id TEXT PRIMARY KEY,
  mirrorId TEXT,
  backupId TEXT,
  status TEXT,
  timestamp TEXT
);