Cloud-Computer-Control-Panel

Cloud Computer Control Panel

An open-source cloud infrastructure management platform with automated Dokploy deployment for seamless container orchestration on AWS EC2.

TODO: add https://github.com/Dokploy/mcp

Overview

CCCP (Cloud Computer Control Panel) lets you manage your own personal cloud and run fully self-hosted cloud applications on your own terms. Spin up a full Linux OS, deploy Docker containers, host developer tools, and maintain complete control over your cloud infrastructure.

What is Dokploy?

Dokploy is an open-source, self-hostable Platform-as-a-Service (PaaS) that lets you deploy any Dockerized application or stack with a web UI, Git integration, and real-time resource monitoring. Positioned as an open-source alternative to Vercel, Netlify, and Heroku, Dokploy runs on your own infrastructure and automatically builds and deploys from Git providers (GitHub, GitLab, Bitbucket, Gitea) on every push to a configured branch.

Features

• Automated Dokploy Installation: Instances automatically install Docker, Docker Swarm, and Dokploy for easy container management
• AWS EC2 Management: Create, start, stop, terminate, and snapshot EC2 instances with a single click
• Custom Scripts: Execute custom shell scripts on your instances via SSH for advanced setup
• Docker Hub Integration: Search and deploy Docker images directly from Docker Hub
• GitHub Integration: Search and deploy GitHub repositories with Dokploy
• Development Environment Setup: Automatically install git, docker, nodejs, python3, nginx, and more
• Cost Estimator: Calculate estimated monthly costs before creating instances
• Real-time Monitoring: Track instance status and health in real-time
• Accounts & Sign-in: Email + password out of the box, plus optional Google OAuth and magic links, powered by Better Auth
• Encrypted Credential Storage: AWS keys are sealed with AES-256-GCM and stored per user in a libSQL/SQLite database — the secret key is never sent back to the browser
• Multi-tenant: Every user drives their own AWS account; API routes resolve credentials server-side from the signed-in session
• API Documentation: Built-in Scalar API reference for programmatic access
• VS Code Extension: The same dashboard runs in the editor sidebar via apps/cccp-vscode-ext, which imports these components directly rather than reimplementing them

Tech Stack

This app is built on the template-nextjs-harness-cloudflare starter template, which supplies the auth, database and theming layers.

• Frontend: Next.js 16, React 19, TypeScript
• UI Components: Radix UI, Tailwind CSS, shadcn/ui, shadcn-theme-menu
• Design tokens: app/theme-tokens.css, kept separate from app/globals.css so the VS Code extension can import the palette without re-importing Tailwind
• Auth: Better Auth (email + password, Google OAuth, magic links, anonymous dev login)
• Database: Drizzle ORM over libSQL — a local SQLite file by default, or Turso in production
• AWS Integration: AWS SDK for JavaScript (EC2, SSM, credentials)
• Form Handling: Zod validation
• Deployment: Vercel Analytics, Next Themes for dark mode

Prerequisites

• Bun 1.3+ — the monorepo pins [email protected]; do not use npm or yarn
• AWS Account with IAM credentials (Access Key ID + Secret Access Key)
• Required AWS IAM permissions for EC2 operations:
  • ec2:DescribeInstances
  • ec2:RunInstances
  • ec2:StartInstances
  • ec2:StopInstances
  • ec2:TerminateInstances
  • ec2:CreateSnapshot
  • ec2:DescribeRegions
  • ec2:DescribeAvailabilityZones

Creating AWS IAM Credentials

Follow these guides to create programmatic access credentials:

• Video Tutorial: Creating AWS IAM User
• Step-by-Step Guide: AWS IAM Programmatic Access

Getting Started

This app is a workspace in the dev-tools-starter-agent monorepo, which installs with Bun — not npm or yarn.

git clone https://github.com/OpenSourceAGI/dev-tools-starter-agent.git
cd dev-tools-starter-agent
bun install                                    # from the repo root

cd apps/Cloud-Computer-Control-Panel
cp .env.example .env
openssl rand -base64 32                        # paste into BETTER_AUTH_SECRET
bun run db:push                                # applies lib/db/schema.ts
bun run dev                                    # http://localhost:3000

BETTER_AUTH_SECRET is the only variable you must set. With DATABASE_URL unset the app writes a local SQLite file at ./data/cccp.db, so nothing else is needed to sign in and start managing instances — AWS keys are entered in the UI, not in .env.

Then, in the browser:

1. Click Sign in and create an account with an email and password.
2. In the dashboard, enter your AWS Access Key ID and Secret Access Key.
3. CCCP verifies them against AWS, encrypts the secret, and stores it against your account.

Environment variables

Values are read in env.ts and lib/. Put them in apps/Cloud-Computer-Control-Panel/.env locally, and in your host's environment-variable settings in production. Only BETTER_AUTH_SECRET is required; each of the others turns on one more feature.

App identity

Variable	Enables	Where to get it
NEXT_PUBLIC_APP_NAME	The name shown in the header and page titles.	Your own value; defaults to CCCP.
NEXT_PUBLIC_APP_URL	Absolute URLs, and the OAuth callback origin.	Your own origin — http://localhost:3000 in development.
NEXT_PUBLIC_APP_EMAIL, NEXT_PUBLIC_APP_DESCRIPTION	Contact address and meta description.	Your own values.

Database — libSQL / Turso

Variable	Enables	Where to get it
DATABASE_URL (alias TURSO_DATABASE_URL)	A hosted database instead of the local file. Leave empty for ./data/cccp.db.	Run npm create cloud-db, or create a database at turso.tech and copy its libSQL URL.
DATABASE_AUTH_TOKEN (alias TURSO_AUTH_TOKEN)	Authenticating to that database.	Turso dashboard → your database → Create Token, or turso db tokens create <name>.

Auth

Variable	Enables	Where to get it
BETTER_AUTH_SECRET	Required. Signs sessions, and — unless CREDENTIALS_ENCRYPTION_KEY is set — encrypts stored AWS secret keys.	Generate one: openssl rand -base64 32. See better-auth installation.
CREDENTIALS_ENCRYPTION_KEY	A separate key for credential encryption at rest, so session-secret rotation does not invalidate stored AWS keys.	Generate one: openssl rand -base64 32. Rotating it makes already-stored secret keys unreadable — users must re-enter them.
GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET	"Sign in with Google".	Google Cloud Console → Credentials → OAuth client ID (Web application). Authorized redirect URI: <APP_URL>/api/auth/callback/google.
NEXT_PUBLIC_GOOGLE_CLIENT_ID	The same client ID, for the browser.	Same value as GOOGLE_CLIENT_ID.
RESEND_API_KEY (alias AUTH_RESEND_KEY)	Magic-link sign-in. Without it, only password and OAuth sign-in work.	resend.com/api-keys
AUTH_TRUSTED_ORIGINS	Extra comma-separated origins allowed to call the auth endpoints — needed when the VS Code extension webview signs in against a deployed instance.	Your own origins.

AWS fallback credentials

Optional, and only for single-tenant installs. A user's own saved credentials always take priority over these; see How credentials are stored.

Variable	Enables	Where to get it
AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY	Server-side fallback credentials when the signed-in user has stored none.	AWS IAM console → your user → Security credentials → Create access key. The permissions needed are listed under Prerequisites.
AWS_REGION	The default region. Defaults to us-east-1.	Any AWS region code.

Deploying

The app is a stock Next.js 16 build with a Node server runtime — the AWS SDK, ssh2 and node-forge are marked external in next.config.mjs, so it needs Node, not an edge runtime.

bun run build
bun run start        # serves the production build on :3000

To deploy from this monorepo, point your host at the repository root, set the root directory to apps/Cloud-Computer-Control-Panel, and use bun install as the install command. Then:

1. Provision a hosted database and set DATABASE_URL / DATABASE_AUTH_TOKEN — the default local SQLite file does not survive a container restart.
2. Run bun run db:push once against it to create the schema.
3. Set BETTER_AUTH_SECRET and CREDENTIALS_ENCRYPTION_KEY as secrets, and keep them stable across deploys: rotating either signs everyone out, and rotating the second one orphans every stored AWS credential.
4. Set NEXT_PUBLIC_APP_URL to the deployed origin, and add that origin to the Google OAuth client's authorized redirect URIs if you use Google sign-in.
5. Add AUTH_TRUSTED_ORIGINS if the VS Code extension will sign in against this instance.

How credentials are stored

• The secret access key is encrypted with AES-256-GCM (lib/crypto.ts) before it reaches the cloud_credentials table, keyed by CREDENTIALS_ENCRYPTION_KEY (falling back to BETTER_AUTH_SECRET).
• The browser only ever receives a masked access key id — never the secret.
• API routes send the sentinel "db" instead of real keys; lib/aws-credentials.ts resolves the actual credentials server-side in this order: keys explicitly sent with the request → the signed-in user's stored keys → the server's AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY.
• Rotating CREDENTIALS_ENCRYPTION_KEY makes existing stored secrets unreadable; users have to re-enter them.

Note: instance metadata (ec2Managers) and generated SSH private keys are still kept in the browser's localStorage. Only cloud provider credentials have been moved into the database so far.

Usage

Creating an Instance

1. Navigate to the "Create New" tab in the dashboard

2. Configure your instance:

   • Instance Name: Choose a descriptive name
   • Instance Type: Select from t2.micro, t3.small, t3.medium, etc.
   • Storage Size: Specify EBS volume size in GB (default: 40GB)
   • SSH Key Pair: Optional, for SSH access
   • Region: Select AWS region (default: us-east-1)

3. Choose software to install:

   • Install Dokploy: Automatically installs Docker, Docker Swarm, and Dokploy
   • Development Environment: Select tools like git, docker, nodejs, python3, nginx
   • Custom Shell Script: Add your own bash scripts or docker-compose files

4. Click "Create Instance" and wait for provisioning

Managing Instances

From the "Managers" tab:

• Start/Stop: Control instance power state
• Terminate: Permanently delete the instance
• Create Snapshot: Backup instance EBS volumes
• View Details: Monitor instance status, IP address, and connection info
• Add Software: Install additional tools post-creation
• Access Dokploy: One-click access to Dokploy dashboard (port 3000)

API Reference

Access the interactive API documentation at /api or click the "API Docs" button in the dashboard.

Available endpoints:

All /api/instances, /api/managers and /api/servers routes require a signed-in session.

• GET /api/credentials - The signed-in user's stored credentials (masked)
• POST /api/credentials - Verify and store AWS credentials, encrypted
• DELETE /api/credentials - Forget the stored credentials
• GET|POST /api/auth/* - Better Auth endpoints (sign-in, sign-up, sign-out, OAuth)
• GET /api/instances - List all instances in a region
• GET /api/instances/all-regions - List instances across all regions
• POST /api/instances/install-software - Install software on an instance
• POST /api/servers/create - Create a new EC2 instance
• GET /api/check-credentials - Report session and credential status
• GET /api/docker-search - Search Docker Hub
• GET /api/github-search - Search GitHub repositories