Installation & Prerequisites

System Requirements

• Linux OS: Ubuntu 24.04 LTS (recommended) or Debian 12
• Docker Engine: 26.0+ with Docker Compose v2
• Node.js: 24.x LTS (for local CLI/development)
• RAM: Minimum 4GB (8GB recommended for concurrent workspaces). Each counted workspace can use up to 1 GiB of container memory, one CPU, and 256 pids, so size host memory for MAX_ACTIVE_WORKSPACES_PER_OWNER (default 3) multiplied by the expected number of simultaneous builds.
• Disk: Minimum 40GB SSD for container images, jobs, and build caches

1-Click Automated Server Installer (Recommended)

Deploy a production-ready CloudHarness MCP server with automated Let's Encrypt TLS (Caddy) or Cloudflare Tunnel in a single command on any clean Linux VPS (Ubuntu 24.04 LTS recommended):

# Interactive setup (prompts for domain and ingress preference)
curl -fsSL https://raw.githubusercontent.com/bestagentkits/cloud-harness-mcp/main/scripts/install.sh | sudo bash

# Or non-interactive with automated Caddy TLS
curl -fsSL https://raw.githubusercontent.com/bestagentkits/cloud-harness-mcp/main/scripts/install.sh | sudo bash -s -- \
  --domain mcp.example.com \
  --email [email protected] \
  --non-interactive

# Or with Cloudflare Tunnel (0 open host ports)
curl -fsSL https://raw.githubusercontent.com/bestagentkits/cloud-harness-mcp/main/scripts/install.sh | sudo bash -s -- \
  --ingress tunnel \
  --domain mcp.example.com \
  --tunnel-token "<your-cloudflare-tunnel-token>" \
  --non-interactive

The installer automatically:

1. Validates OS, RAM (>= 2GB), and storage prerequisites.
2. Configures Docker CE and Docker Compose plugin.
3. Generates high-entropy cryptographic keys (MCP_BEARER_TOKEN, RUNNER_TOKEN, and secret-keyring.json) with strict 0700/0600 permissions.
4. Sets up automated TLS via Caddy reverse proxy or Cloudflare Tunnel attached to the loopback ingress network.
5. Registers and enables cloud-harness-mcp.service via systemd.
6. Runs image builds and executes the automated canary health verification.
7. Outputs copy-pasteable client configuration for Claude Desktop and Cursor.

Managing the Server (cloudharness CLI)

Once installed, use the cloudharness utility to manage your instance:

# Check service, container, and ingress health status
cloudharness status

# View service logs
cloudharness logs api -f
cloudharness logs runner -f

# View or safely rotate MCP bearer token
sudo cloudharness token view
sudo cloudharness token rotate

# Upgrade to the latest release
sudo cloudharness upgrade

---

Installing the Companion Agent Skill

You can install the self-contained cloudharness agent skill directly from this repository using the Skills CLI:

# Project scope
npx skills add bestagentkits/cloud-harness-mcp --skill cloudharness

# Or global user scope
npx skills add bestagentkits/cloud-harness-mcp --skill cloudharness --global

Claude Code Plugin Marketplace

claude plugin marketplace add bestagentkits/cloud-harness-mcp
claude plugin install cloud-harness@bestagentkits

OpenAI Codex Plugin

codex plugin marketplace add bestagentkits/cloud-harness-mcp
codex plugin add cloud-harness@bestagentkits

---

Manual Setup with Docker Compose (Alternative)

1. Clone the Repository:

   git clone https://github.com/bestagentkits/cloud-harness-mcp.git
   cd cloud-harness-mcp

2. Configure Environment:

   cp .env.example .env
   # Edit .env and supply your secrets (MCP_BEARER_TOKEN, RUNNER_TOKEN, etc.)

3. Build Images and Start Containers:

   docker compose --profile images build executor-image api runner
   docker compose up -d

4. Verify Health:

   curl http://127.0.0.1:3100/readyz
   # Returns: {"status":"healthy"}