Cloud Harness MCP

Cloud Harness MCP is an MIT-licensed remote coding harness exposed through authenticated Streamable HTTP MCP. It opens an isolated clone in a TTL-limited Docker executor and gives a trusted owner or named mutually trusted operators structured workspace, file, code-intelligence, command, shell, session, dependency-task, Git, worktree, skill, hook, memory, and repository-defined deployment tools.

[!WARNING] This is a private service for one security domain. Its operators must trust one another because it is intentionally capable of arbitrary command execution inside a shared-kernel executor. Principal isolation is not a hostile multi-tenant sandbox. Read the security model before operating it.

The Managed OAuth MCP URL is:

https://harness.zuey.me/mcp

Static-header clients use dashboard-managed API keys at the separate gateway:

https://api.harness.zuey.me/mcp

Architecture

MCP is the northbound control protocol; the harness is the execution runtime. The split keeps Internet-facing request handling away from Docker authority and keeps repository credentials out of long-lived executors.

flowchart LR
  OAuthClient["Managed OAuth client"] -->|"Access OAuth"| Nginx["nginx + loopback ingress"]
  StaticClient["Static-header client"] -->|"managed API key"| Gateway["Cloudflare Worker gateway"]
  Gateway -->|"Access service assertion + API key"| Nginx

  subgraph Control["Trusted control plane"]
    Nginx --> API["Stateless MCP API"]
    API -->|"private authenticated RPC"| Runner["Runner · policy · lifecycle"]
    Runner --> Store[("SQLite workspace state")]
    Runner --> Docker["Docker authority"]
    Runner --> Broker["GitHub App broker"]
  end

  subgraph Execution["TTL-bound execution plane"]
    Docker --> Executor["Non-root workspace executor"]
    Docker --> GitHelper["Ephemeral Git transfer helper"]
    Executor --> Repo[("Isolated repository clone")]
  end

  Broker -->|"short-lived token over stdin"| GitHelper
  GitHelper -->|"validated HTTPS origin"| GitHub["GitHub repository"]
  Executor -.->|"no control-plane credential"| GitHub

The source of truth for these boundaries is compose.yaml, apps/runner/src/workspace-service.ts, and the security model.

Coding workflow

sequenceDiagram
  participant C as AI client
  participant A as MCP API
  participant R as Runner
  participant E as Isolated executor
  participant G as Ephemeral Git helper
  participant H as GitHub

  C->>A: workspace_open(repositoryUrl, idempotencyKey)
  A->>R: authenticated operation
  R->>G: constrained clone + optional short-lived token
  G->>H: credential-free or GitHub App HTTPS clone
  R->>E: start bounded workspace container
  R-->>C: opaque workspaceId
  C->>E: inspect, edit, test, session, task graph, commit
  C->>R: git_push(refspec, forceWithLease?, expectedRemoteOid?)
  R->>G: stage clean bare transfer + short-lived token
  G->>H: origin-only push
  G-->>R: bounded sanitized result
  R-->>C: structured MCP result
  C->>R: workspace_close(workspaceId)
  R->>E: terminate and remove

Remote fetch, pull, and push use a sibling transfer repository that the executor cannot see. Push requires a GitHub App installation with repository write access; clone/fetch/pull need read access. See configuration and MCP semantics.

Getting started

1. Read the security model, then configure one of the supported clients below with the owner token kept in local private configuration.
2. Ask the client to call workspace_open with a credential-free HTTPS repository URL and a fresh idempotency key. Keep the returned opaque workspaceId; do not derive it from a path or repository name.
3. Use the bounded tools in the existing workspace, then close shells, sessions, and unwanted tasks before calling workspace_close.

Start with the normal workflow in MCP usage for lifecycle, cursor, network, and Git-transfer semantics.

Local stdio workspace mode

In addition to the remote HTTP/Docker service, Cloud Harness MCP can operate directly against an explicitly selected project folder on your local machine over stdio transport.

# Start local stdio server for a project:
cloud-harness-mcp --transport stdio --workspace /path/to/project

In local mode:

• The configured folder behaves as an already-opened workspace (with an opaque workspaceId). workspace_open is not required.
• File operations, patches, grep search, symbol search, sessions, tasks, and local Git tools operate directly on the folder.
• workspace_close terminates owned child processes and tasks but never deletes your local project folder.
• Tool paths and working directories are strictly confined within the workspace root.
• Commands (exec_run, shells, tasks) execute with host-user permissions. File path confinement is not an OS sandbox.
• Network Git (git_fetch, git_pull) and Git push (git_push) are disabled by default and require explicit startup opt-in flags (--git-network, --git-push).
• v1 supports POSIX (Linux and macOS); Windows process semantics are a documented follow-up (use WSL on Windows).

This is the beginning of the README. Read the rest at the original. Read the full README ↗