Skip to content
Back to search

bestagentkits

Developer plugins from Best Agent Kits.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 15 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/bestagentkits/cloud-harness-mcp with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/bestagentkits/cloud-harness-mcp'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/bestagentkits--cloud-harness-mcp/badge.svg)](/listings/bestagentkits--cloud-harness-mcp)

HTML

<a href="/listings/bestagentkits--cloud-harness-mcp"><img src="/api/listings/bestagentkits--cloud-harness-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Read the [security model](docs/security-model.md), 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](docs/mcp-api.md#normal-workflow) for lifecycle, cursor, network, and Git-transfer semantics.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 17 lines
  1. {
  2. "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
  3. "name": "bestagentkits",
  4. "owner": {
  5. "name": "Best Agent Kits",
  6. "url": "https://github.com/bestagentkits"
  7. },
  8. "description": "Developer plugins from Best Agent Kits.",
  9. "plugins": [
  10. {
  11. "name": "cloud-harness",
  12. "source": "./plugins/cloud-harness",
  13. "description": "Operate private Cloud Harness MCP coding workspaces safely.",
  14. "version": "2.1.0"
  15. }
  16. ]
  17. }
README.md · README · 714 lines
  1. # Cloud Harness MCP
  2. ![Cloud Harness MCP — isometric cutaway of the authenticated control plane and isolated coding workspaces](docs/assets/cloud-harness-architecture-banner.png)
  3. Cloud Harness MCP is an MIT-licensed remote coding harness exposed through
  4. authenticated Streamable HTTP MCP. It opens an isolated clone in a
  5. TTL-limited Docker executor and gives a trusted owner or named mutually trusted
  6. operators structured workspace,
  7. file, code-intelligence, command, shell, session, dependency-task, Git,
  8. worktree, skill, hook, memory, and repository-defined deployment tools.
  9. > [!WARNING]
  10. > This is a private service for one security domain. Its operators must trust
  11. > one another because it is intentionally capable of arbitrary command
  12. > execution inside a shared-kernel executor. Principal isolation is not a
  13. > hostile multi-tenant sandbox. Read the [security model](docs/security-model.md)
  14. > before operating it.
  15. The Managed OAuth MCP URL is:
  16. ```text
  17. https://harness.zuey.me/mcp
  18. ```
  19. Static-header clients use dashboard-managed API keys at the separate gateway:
  20. ```text
  21. https://api.harness.zuey.me/mcp
  22. ```
  23. ## Architecture
  24. MCP is the northbound control protocol; the harness is the execution runtime.
  25. The split keeps Internet-facing request handling away from Docker authority and
  26. keeps repository credentials out of long-lived executors.
  27. ```mermaid
  28. flowchart LR
  29. OAuthClient["Managed OAuth client"] -->|"Access OAuth"| Nginx["nginx + loopback ingress"]
  30. StaticClient["Static-header client"] -->|"managed API key"| Gateway["Cloudflare Worker gateway"]
  31. Gateway -->|"Access service assertion + API key"| Nginx
  32. subgraph Control["Trusted control plane"]
  33. Nginx --> API["Stateless MCP API"]
  34. API -->|"private authenticated RPC"| Runner["Runner · policy · lifecycle"]
  35. Runner --> Store[("SQLite workspace state")]
  36. Runner --> Docker["Docker authority"]
  37. Runner --> Broker["GitHub App broker"]
  38. end
  39. subgraph Execution["TTL-bound execution plane"]
  40. Docker --> Executor["Non-root workspace executor"]
  41. Docker --> GitHelper["Ephemeral Git transfer helper"]
  42. Executor --> Repo[("Isolated repository clone")]
  43. end
  44. Broker -->|"short-lived token over stdin"| GitHelper
  45. GitHelper -->|"validated HTTPS origin"| GitHub["GitHub repository"]
  46. Executor -.->|"no control-plane credential"| GitHub
  47. ```
  48. The source of truth for these boundaries is
  49. [`compose.yaml`](compose.yaml),
  50. [`apps/runner/src/workspace-service.ts`](apps/runner/src/workspace-service.ts),
  51. and the [security model](docs/security-model.md).
  52. ## Coding workflow
  53. ```mermaid
  54. sequenceDiagram
  55. participant C as AI client
  56. participant A as MCP API
  57. participant R as Runner
  58. participant E as Isolated executor
  59. participant G as Ephemeral Git helper
  60. participant H as GitHub
  61. C->>A: workspace_open(repositoryUrl, idempotencyKey)
  62. A->>R: authenticated operation
  63. R->>G: constrained clone + optional short-lived token
  64. G->>H: credential-free or GitHub App HTTPS clone
  65. R->>E: start bounded workspace container
  66. R-->>C: opaque workspaceId
  67. C->>E: inspect, edit, test, session, task graph, commit
  68. C->>R: git_push(refspec, forceWithLease?, expectedRemoteOid?)
  69. R->>G: stage clean bare transfer + short-lived token
  70. G->>H: origin-only push
  71. G-->>R: bounded sanitized result
  72. R-->>C: structured MCP result
  73. C->>R: workspace_close(workspaceId)
  74. R->>E: terminate and remove
  75. ```
  76. Remote fetch, pull, and push use a sibling transfer repository that the
  77. executor cannot see. Push requires a GitHub App installation with repository
  78. write access; clone/fetch/pull need read access. See
  79. [configuration](docs/configuration.md#optional-github-app-repository-access) and
  80. [MCP semantics](docs/mcp-api.md).
  81. ## Getting started
  82. 1. Read the [security model](docs/security-model.md), then configure one of the
  83. supported clients below with the owner token kept in local private
  84. configuration.
  85. 2. Ask the client to call `workspace_open` with a credential-free HTTPS
  86. repository URL and a fresh idempotency key. Keep the returned opaque
  87. `workspaceId`; do not derive it from a path or repository name.
  88. 3. Use the bounded tools in the existing workspace, then close shells,
  89. sessions, and unwanted tasks before calling `workspace_close`.
  90. Start with the normal workflow in [MCP usage](docs/mcp-api.md#normal-workflow)
  91. for lifecycle, cursor, network, and Git-transfer semantics.
  92. ## Local stdio workspace mode
  93. 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**.
  94. ```bash
  95. # Start local stdio server for a project:
  96. cloud-harness-mcp --transport stdio --workspace /path/to/project
  97. ```
  98. In local mode:
  99. - The configured folder behaves as an already-opened workspace (with an opaque `workspaceId`). `workspace_open` is not required.
  100. - File operations, patches, grep search, symbol search, sessions, tasks, and local Git tools operate directly on the folder.
  101. - `workspace_close` terminates owned child processes and tasks but **never deletes your local project folder**.
  102. - Tool paths and working directories are strictly confined within the workspace root.
  103. - Commands (`exec_run`, shells, tasks) execute with host-user permissions. File path confinement is not an OS sandbox.
  104. - 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`).
  105. - v1 supports POSIX (Linux and macOS); Windows process semantics are a documented follow-up (use WSL on Windows).
  106. To serve several persistent project folders from one process, register them in
  107. a versioned YAML/JSON file and pass `--workspace-config <absolute-path>` instead
  108. of `--workspace`. It works over stdio, or over `--transport http` as an
  109. authenticated local endpoint that needs no Docker runner. Each folder keeps its
  110. own path confinement, processes, and stable `workspaceId`. See
  111. [Several local workspaces from one server](docs-site/connect.md#several-local-workspaces-from-one-server)
  112. for the file format and client setup, and [MCP usage](docs/mcp-api.md#local-multi-workspace-mode)
  113. for selection and failure semantics.
  114. ### CLI options
  115. | Option | Description |
  116. |---|---|
  117. | `--transport <http\|stdio>` | Select transport protocol: `http` (default) or `stdio` |
  118. | `--workspace <path>` | Absolute path to one local project folder (stdio) |
  119. | `--workspace-config <path>` | Absolute path to a registry of named local folders (stdio or local HTTP); mutually exclusive with `--workspace` |
  120. | `--git-network` | Enable network Git operations (`git_fetch`, `git_pull`) |
  121. | `--git-push` | Enable Git push (`git_push`, implies `--git-network`) |
  122. | `--env <NAME>` | Forward additional host environment variable (repeatable) |
  123. | `-h, --help` | Display help message |
  124. | `-v, --version` | Display version information |
  125. ### Configuring local stdio in AI clients
  126. #### Claude Desktop
  127. In `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `~/.config/Claude/claude_desktop_config.json` (Linux):
  128. ```json
  129. {
  130. "mcpServers": {
  131. "cloud-harness-local": {
  132. "command": "node",
  133. "args": [
  134. "/path/to/cloud-harness-mcp/apps/api/dist/index.js",
  135. "--transport",
  136. "stdio",
  137. "--workspace",
  138. "/path/to/my-project"
  139. ]
  140. }
  141. }
  142. }
  143. ```
  144. #### Claude Code
  145. ```bash
  146. claude mcp add cloud-harness-local --transport stdio -- node /path/to/cloud-harness-mcp/apps/api/dist/index.js --transport stdio --workspace /path/to/my-project
  147. ```
  148. #### Cursor
  149. In `.cursor/mcp.json`:
  150. ```json
  151. {
  152. "mcpServers": {
  153. "cloud-harness-local": {
  154. "command": "node",
  155. "args": [
  156. "/path/to/cloud-harness-mcp/apps/api/dist/index.js",
  157. "--transport",
  158. "stdio",
  159. "--workspace",
  160. "/path/to/my-project"
  161. ]
  162. }
  163. }
  164. }
  165. ```
  166. #### OpenAI Codex
  167. In `~/.codex/config.toml`:
  168. ```toml
  169. [mcp_servers.cloud_harness_local]
  170. command = "node"
  171. args = ["/path/to/cloud-harness-mcp/apps/api/dist/index.js", "--transport", "stdio", "--workspace", "/path/to/my-project"]
  172. ```
  173. ## MCP tools
  174. The public tool names are owned by
  175. [`RunnerOperationSchema`](packages/contracts/src/runner-api.ts). Inputs,
  176. bounds, and approval annotations are owned by
  177. [`TOOL_SPECS`](packages/contracts/src/tool-schemas.ts); the API registers each
  178. of those specs in [`mcp-server.ts`](apps/api/src/mcp-server.ts).
  179. ### Workspace lifecycle
  180. `workspace_open`, `workspace_list`, `workspace_status`, `workspace_capabilities`,
  181. `workspace_lease_renew`, `workspace_recover`, `workspace_context`,
  182. `workspace_set_active`, `workspace_close`, `secrets_list`
  183. ### Files and code intelligence
  184. `files_list`, `files_read`, `files_write`, `files_write_batch`, `files_apply_patch`, `files_delete`,
  185. `files_move`, `files_mkdir`, `grep_search`, `symbols_search`,
  186. `symbols_references`
  187. ### Commands, shells, sessions, and tasks
  188. `exec_run`, `shell_open`, `shell_io`, `shell_close`, `sessions_list`,
  189. `sessions_open`, `sessions_io`, `sessions_close`, `tasks_list`, `tasks_run`,
  190. `tasks_status`, `tasks_cancel`, `tasks_graph`, `operation_status`,
  191. `operation_cancel`, `operation_wait`
  192. ### Git and worktrees
  193. `git_status`, `git_diff`, `git_log`, `git_branch`, `git_checkout`, `git_add`,
  194. `git_commit`, `git_identity_status`, `git_identity_set`, `workspace_finalize`,
  195. `git_fetch`, `git_pull`, `git_push`, `git_merge`, `git_rebase`,
  196. `worktrees_list`, `worktrees_create`, `worktrees_remove`, `github_action`
  197. ### Repository extensions
  198. `skills_list`, `skills_read`, `skills_run`, `hooks_list`, `hooks_run`,
  199. `memories_list`, `memories_read`, `memories_write`, `deployments_list`,
  200. `deployments_run`
  201. The HTTP endpoint also serves built-in and owner skills through the
  202. `io.modelcontextprotocol/skills` protocol extension (`skills/list`,
  203. `skills/get`, `resources/read`); see
  204. [Skills over MCP extension](docs/mcp-api.md#skills-over-mcp-extension).
  205. The remote HTTP endpoint also offers signed webhook notifications when a durable
  206. task or managed agent finishes, through MCP Events (`events/list`,
  207. `events/subscribe`, `events/unsubscribe`); see
  208. [MCP Events](docs/mcp-api.md#mcp-events-webhook-delivery).
  209. ### Retained artifacts
  210. `artifacts_snapshot`, `artifacts_list`, `artifacts_read`, `artifacts_restore`,
  211. `artifacts_delete`
  212. ## Install the Cloud Harness skill
  213. Install the self-contained `cloudharness` operating skill directly from this
  214. repository with the [skills CLI](https://www.npmjs.com/package/skills):
  215. ```bash
  216. npx skills add bestagentkits/cloud-harness-mcp --skill cloudharness
  217. ```
  218. Use `--global` to install it for the current user instead of the current
  219. project. The skill includes detailed, portable references for every public
  220. operation, input bound, side effect, recovery path, and security boundary. It
  221. does not install credentials or connect the MCP endpoint; complete one of the
  222. client configurations below separately.
  223. This repository also publishes the same skill as a plugin package for both
  224. Claude Code and OpenAI's plugin format.
  225. <details>
  226. <summary>Install from the Claude Code marketplace</summary>
  227. ```bash
  228. claude plugin marketplace add bestagentkits/cloud-harness-mcp
  229. claude plugin install cloud-harness@bestagentkits
  230. ```
  231. The package is skills-only, so register the authenticated MCP connection under
  232. **Claude Code** below after installation. See Anthropic's
  233. [plugin marketplace guide](https://code.claude.com/docs/en/plugin-marketplaces)
  234. for update and uninstall commands.
  235. </details>
  236. <details>
  237. <summary>Install from the OpenAI plugin marketplace</summary>
  238. Once this repository has been added to an available OpenAI marketplace, install
  239. the package with:
  240. ```bash
  241. codex plugin marketplace add bestagentkits/cloud-harness-mcp
  242. codex plugin add cloud-harness@bestagentkits
  243. ```
  244. The OpenAI package contains the portable skill, store metadata, logo, privacy
  245. policy, and terms. It intentionally does not embed an app registration ID,
  246. bearer token, or MCP authorization. OpenAI reviews skills-only and MCP-only
  247. plugins, but a public authenticated remote MCP listing requires a supported
  248. OAuth flow. The owner deployment uses Cloudflare Access Managed OAuth; the
  249. package itself still embeds no deployment-specific authorization or app
  250. registration.
  251. See OpenAI's [plugin packaging](https://developers.openai.com/plugins/build/plugins),
  252. [submission](https://developers.openai.com/plugins/deploy/submission), and
  253. [authentication](https://developers.openai.com/plugins/build/auth) guidance.
  254. </details>
  255. ## Connect from AI clients
  256. The owner deployment exposes two remote Streamable HTTP MCP lanes:
  257. ```text
  258. Managed OAuth: https://harness.zuey.me/mcp
  259. Static API key: https://api.harness.zuey.me/mcp
  260. ```
  261. The owner deployment uses `cloudflare-access`: Managed OAuth clients connect to
  262. the first URL and complete GitHub or Google login in the browser. Cloudflare
  263. Access is the OAuth authorization server for that lane; Cloud Harness verifies
  264. the assertion Access forwards (see
  265. [how the Managed OAuth lane works](docs/security-model.md#inbound-mcp-oauth-cloudflare-access-is-the-authorization-server)). Static-header
  266. clients use only the second URL with `Authorization: Bearer <dashboard-api-key>`.
  267. Its dashboard is `https://harness.zuey.me/dashboard`.
  268. Create, list, and revoke API keys under **Dashboard → API keys**. A new key is
  269. shown once and cannot be recovered; store it only in the client's private
  270. credential store. Keys expire after 1–3,650 days (approximately 10 years), and each identity may have at
  271. most 10 active keys. There are no per-tool scopes or rotation endpoint: replace
  272. a key by creating a new one and then revoking the old one. Every key has the
  273. creator's full MCP authority, including arbitrary command execution in the
  274. executor. Revocation or expiry denies the next request.
  275. The API-key gateway is not an alternate dashboard login and does not accept
  276. Managed OAuth. Conversely, `https://harness.zuey.me/mcp` does not accept a
  277. dashboard-managed API key. See the [security model](docs/security-model.md) for
  278. the independent Worker/Access/key checks.
  279. `owner-bearer` remains the software default for separate private deployments.
  280. The direct-header examples below use `CLOUD_HARNESS_MCP_TOKEN`. For this owner
  281. deployment, set it to a dashboard-managed key and use
  282. `https://api.harness.zuey.me/mcp`. For a separate `owner-bearer` deployment,
  283. use the owner-provided token and `https://<owner-bearer-hostname>/mcp`. Keep the
  284. credential and URL in client-local private configuration; never put the token
  285. in a repository, prompt, or shared project configuration.
  286. Other operators may deploy `cloudflare-access` on an eligible hostname in an
  287. owned Cloudflare zone. Access provides Managed OAuth and GitHub/Google SSO;
  288. Cloud Harness verifies the forwarded assertion and exposes the dashboard at
  289. `/dashboard`. Treat client login as supported only after the exact client,
  290. Access policy, discovery, refresh, and revocation flow has been verified live.
  291. Implementation, merge, and Cloudflare configuration are separate evidence
  292. states. See [configuration](docs/configuration.md#authentication-and-request-policy)
  293. and [deployment](docs/deployment.md#cloudflare-access-rollout).
  294. Granting either form of access grants remote execution authority. Read the
  295. [security model](docs/security-model.md) before connecting it.
  296. <details>
  297. <summary>ChatGPT</summary>
  298. ChatGPT custom MCP apps are configured in the web app and must be reachable
  299. from OpenAI's infrastructure. Enable Developer mode, then go to **Settings or
  300. Workspace settings → Apps → Create**, enter the endpoint above, scan its tools,
  301. and create the app. Initially, the connector is in **Draft (Dev)** state and
  302. can be tested in standard 1-on-1 ChatGPT Web chats with Developer Mode enabled.
  303. To enable access across team members without Developer Mode constraints, a
  304. Workspace Admin/Owner can publish the connector under **Workspace settings →
  305. Apps → Drafts → Publish**. The exact availability and controls depend on the
  306. ChatGPT plan (Business, Enterprise, or Edu beta for full MCP actions) and
  307. workspace role; follow [OpenAI's current Developer mode guide](https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt)
  308. and the [ChatGPT Configuration Guide](https://docs.harness.agentkit.best/ai-tools/chatgpt.md).
  309. The `owner-bearer` mode is not a documented direct path because the custom-app
  310. flow has no arbitrary-header field. In `cloudflare-access` mode, use the
  311. owner-controlled Access URL and complete its OAuth flow; keep the connection
  312. provisional until the live compatibility checklist passes. Never place the
  313. owner bearer in an app definition or a chat. If invocation fails with
  314. `FORBIDDEN: This conversation does not support developer MCPs`, consult the
  315. [Troubleshooting Guide](https://docs.harness.agentkit.best/troubleshooting.md).
  316. </details>
  317. <details>
  318. <summary>Codex</summary>
  319. Set the token in your shell before starting Codex:
  320. ```bash
  321. export CLOUD_HARNESS_MCP_TOKEN="<owner-provided-token>"
  322. ```
  323. On PowerShell, use:
  324. ```powershell
  325. $env:CLOUD_HARNESS_MCP_TOKEN = "<owner-provided-token>"
  326. ```
  327. Add this to `~/.codex/config.toml` (or a trusted project's
  328. `.codex/config.toml`):
  329. ```toml
  330. [mcp_servers.cloud_harness]
  331. url = "https://<owner-bearer-hostname>/mcp"
  332. bearer_token_env_var = "CLOUD_HARNESS_MCP_TOKEN"
  333. required = true
  334. tool_timeout_sec = 300
  335. default_tools_approval_mode = "writes"
  336. ```
  337. Restart Codex, then use `/mcp` or `codex mcp list` to confirm the connection.
  338. The fields follow the [Codex MCP configuration documentation](https://developers.openai.com/codex/mcp).
  339. </details>
  340. <details>
  341. <summary>Claude Desktop app</summary>
  342. Claude's remote custom connectors are set up from the Claude app and are called
  343. from Anthropic's cloud, rather than from your computer. In **Settings →
  344. Connectors**, add the public endpoint and complete the connector's supported
  345. authentication flow. The current workflow and plan availability are documented
  346. by [Anthropic](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp).
  347. The hosted connector flow is OAuth-oriented and has no documented
  348. static-header field. Use `cloudflare-access` and complete its OAuth flow for a
  349. hosted connector, subject to live compatibility verification, or use Claude
  350. Code below with the default owner bearer.
  351. </details>
  352. <details>
  353. <summary>Claude Code</summary>
  354. Set the token, then register the server for your user account:
  355. ```bash
  356. export CLOUD_HARNESS_MCP_TOKEN="<owner-provided-token>"
  357. claude mcp add --transport http --scope user \
  358. --header "Authorization: Bearer $CLOUD_HARNESS_MCP_TOKEN" \
  359. cloud-harness https://<owner-bearer-hostname>/mcp
  360. ```
  361. Use `claude mcp get cloud-harness` to inspect the entry, then `/mcp` in a
  362. Claude Code session to confirm that it is available. Claude Code documents
  363. remote HTTP registration and static headers in its [MCP guide](https://code.claude.com/docs/en/mcp).
  364. </details>
  365. <details>
  366. <summary>Gemini CLI</summary>
  367. Set the token, then add a remote HTTP MCP server:
  368. ```bash
  369. export CLOUD_HARNESS_MCP_TOKEN="<owner-provided-token>"
  370. gemini mcp add --transport http \
  371. --header "Authorization: Bearer $CLOUD_HARNESS_MCP_TOKEN" \
  372. cloud-harness https://<owner-bearer-hostname>/mcp
  373. ```
  374. Restart Gemini CLI if it is already running and use its MCP management command
  375. to confirm the server. See the [Gemini CLI MCP-server reference](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md)
  376. for the supported transports and header syntax.
  377. </details>
  378. <details>
  379. <summary>Cursor</summary>
  380. Open **Customize → MCP** and add a remote Streamable HTTP server, or add the
  381. following to the global `~/.cursor/mcp.json` (use `.cursor/mcp.json` for a
  382. trusted project only):
  383. ```json
  384. {
  385. "mcpServers": {
  386. "cloud-harness": {
  387. "url": "https://<owner-bearer-hostname>/mcp",
  388. "headers": {
  389. "Authorization": "Bearer ${env:CLOUD_HARNESS_MCP_TOKEN}"
  390. }
  391. }
  392. }
  393. }
  394. ```
  395. Restart Cursor, approve the server, and check that `cloud-harness` appears in
  396. the chat's available tools. Cursor documents the configuration locations and
  397. remote MCP support in its [MCP guide](https://cursor.com/docs/mcp).
  398. The global file is user-local; do not copy the token-bearing project file into
  399. source control.
  400. </details>
  401. <details>
  402. <summary>Google Antigravity</summary>
  403. In the agent side panel, choose **… → MCP Servers → Manage MCP Servers → View
  404. raw config**. This opens the global `~/.gemini/config/mcp_config.json`; add a
  405. remote server entry:
  406. ```json
  407. {
  408. "mcpServers": {
  409. "cloud-harness": {
  410. "serverUrl": "https://<owner-bearer-hostname>/mcp",
  411. "headers": {
  412. "Authorization": "Bearer <owner-provided-token>"
  413. }
  414. }
  415. }
  416. }
  417. ```
  418. Save the file and confirm that the server is enabled in the MCP Servers panel.
  419. Antigravity's [MCP reference](https://antigravity.google/docs/mcp) defines the
  420. global path, `serverUrl`, and `headers` for remote MCP servers. Keep this local
  421. configuration private.
  422. </details>
  423. <details>
  424. <summary>Grok</summary>
  425. In Grok web, open the **+** menu, choose **Connectors**, then select **Add
  426. connector** to create a custom MCP connection. It must use a public URL; see
  427. xAI's [connector overview](https://x.ai/news/grok-connectors). The consumer
  428. connector UI may require an OAuth flow, so use the Access-mode endpoint and
  429. verify that flow live. It is not a documented direct path for owner-bearer
  430. mode.
  431. For the xAI API, Remote MCP Tools support an explicit authorization token. Add
  432. this object to a Responses API request's `tools` array:
  433. ```json
  434. {
  435. "type": "mcp",
  436. "server_url": "https://<owner-bearer-hostname>/mcp",
  437. "server_label": "cloud-harness",
  438. "authorization": "Bearer <owner-provided-token>"
  439. }
  440. ```
  441. Limit `allowed_tools` when the request needs only a subset. The [xAI Remote MCP
  442. Tools reference](https://docs.x.ai/developers/tools/remote-mcp) documents
  443. Streamable HTTP support, authorization, and tool allowlisting.
  444. </details>
  445. Start by asking a connected client to call `workspace_open` with a
  446. credential-free HTTPS repository URL and a new idempotency key. Reuse the
  447. returned opaque `workspaceId` for later calls and finish with
  448. `workspace_close`. See [MCP usage](docs/mcp-api.md) for the workflow and
  449. important semantics.
  450. ## Run locally
  451. Prerequisites are Node.js 24+, npm, Docker Engine, and Docker Compose v2.
  452. ```bash
  453. npm ci
  454. cp .env.example .env
  455. # Replace every change-me value in .env with an independent random secret.
  456. docker compose --profile images build executor-image api runner
  457. docker compose up -d runner api ingress
  458. curl --fail http://127.0.0.1:3100/readyz
  459. ```
  460. Local Compose publishes only a credential-free TCP ingress proxy on host
  461. loopback. The API and runner remain on separate internal networks; only the
  462. runner has Docker authority. Local Compose does not configure TLS. Stop it with:
  463. ```bash
  464. docker compose down
  465. ```
  466. ## Configure environment variables
  467. The local setup command above creates an ignored runtime environment file from
  468. the maintained template. Generate two independent secrets, then replace the
  469. two placeholder values in that runtime file:
  470. ```bash
  471. openssl rand -hex 32 # MCP_BEARER_TOKEN
  472. openssl rand -hex 32 # RUNNER_TOKEN
  473. ```
  474. Both tokens must contain 32–512 characters. Never commit the runtime file or
  475. paste either value into prompts, logs, or shared project configuration.
  476. When a direct secret and its `_FILE` alternative are both set, the file value
  477. takes precedence.
  478. The server-side `MCP_BEARER_TOKEN` is the owner credential accepted by `/mcp`.
  479. The client examples above store that same value under the client-local name
  480. `CLOUD_HARNESS_MCP_TOKEN`. `RUNNER_TOKEN` is a separate, internal API-to-runner
  481. credential and must never be given to an MCP client.
  482. ### Required and common settings
  483. The values below are runtime defaults when a variable is omitted. The
  484. maintained template may prefill the current public host and browser origin;
  485. replace those entries with the hostname and origins of your deployment.
  486. | Variable | Runtime default | Description |
  487. |---|---:|---|
  488. | `MCP_BEARER_TOKEN` | required | Owner bearer token for MCP requests. Use `MCP_BEARER_TOKEN_FILE` instead when a secret is mounted as a file. |
  489. | `RUNNER_TOKEN` | required | Independent service token used only between the API and runner. `RUNNER_TOKEN_FILE` is also supported. |
  490. | `OWNER_ID` | `owner` | Stable identifier attached to the single owner's workspaces. Changing it does not add multi-user isolation. |
  491. | `API_PUBLIC_HOSTS` | `localhost,127.0.0.1` | Comma-separated `Host` allowlist. Add the public MCP hostname in a deployed environment. |
  492. | `API_ALLOWED_ORIGINS` | empty | Comma-separated exact browser origins allowed to send requests. CLI clients that omit `Origin` do not need an entry. |
  493. | `ALLOWED_GIT_HOSTS` | `github.com` | Comma-separated repository-host allowlist. Repository URLs must still use credential-free HTTPS. |
  494. | `WORKSPACE_NETWORK_PROFILE` | `dependency-access` | Executor networking default. `dependency-access` permits only public DNS and TCP 80/443 via a Linux host firewall attested before each executor start, and is required for `gh` and the GitHub API; `network-none` blocks all egress. A default saved on the dashboard Settings page overrides this variable, and `workspace_open.networkProfile` overrides both. The legacy `WORKSPACE_NETWORK_MODE` is rejected. |
  495. | `WORKSPACE_WALL_TTL_SECONDS` | `900` | Maximum workspace lifetime, from 60 to 86,400 seconds. |
  496. | `WORKSPACE_IDLE_TTL_SECONDS` | `300` | Maximum idle time, from 30 to 43,200 seconds. |
  497. | `JOBS_ROOT` | `/var/lib/cloud-harness/jobs` | Runner path for ephemeral workspace directories. |
  498. | `STATE_DB` | `/var/lib/cloud-harness/state/cloud-harness.db` | Runner SQLite state-file path. |
  499. | `EXECUTOR_IMAGE` | `cloud-harness-executor:local` | Trusted executor image selected by the operator, never by MCP callers. |
  500. | `NETWORK_GUARD_IMAGE` | `cloud-harness-network-guard:local` | Trusted `NET_ADMIN`-only image used to attest the host firewall for `dependency-access`. |
  501. The maintained template contains every setting needed for the normal local
  502. Compose workflow. The following limits are optional; omit them to use their
  503. validated defaults.
  504. ### Resource and request limits
  505. | Variable | Default | Allowed value / purpose |
  506. |---|---:|---|
  507. | `REQUEST_TIMEOUT_MS` | `60000` | API-to-runner timeout; 1,000–300,000 ms. Keep client tool timeouts at least this long. |
  508. | `MAX_BODY_BYTES` | `1048576` | Maximum API JSON request size; 1,024–4,194,304 bytes. |
  509. | `MAX_OUTPUT_BYTES` | `262144` | Maximum bounded runner/worker result; 1,024–10,485,760 bytes. |
  510. | `MIN_FREE_BYTES` | `2147483648` | Minimum free host storage required to admit a workspace; at least 104,857,600 bytes. |
  511. | `MAX_WORKSPACE_BYTES` | `2147483648` | Soft workspace-size ceiling; at least 104,857,600 bytes. This is checked periodically, not enforced as a filesystem quota. |
  512. | `REAPER_INTERVAL_SECONDS` | `30` | Interval for lifecycle and storage cleanup checks; 10–3,600 seconds. |
  513. | `LOG_LEVEL` | `info` | Pino log level for API and runner processes, such as `debug`, `info`, `warn`, or `error`. |
  514. ### Optional private GitHub repositories
  515. Public repositories need no additional credential. For private clone, fetch,
  516. pull, or push, configure all three GitHub App values together:
  517. | Variable | Description |
  518. |---|---|
  519. | `GITHUB_APP_ID` | Numeric GitHub App ID. |
  520. | `GITHUB_APP_INSTALLATION_ID` | Numeric installation ID with access to the target repository. |
  521. | `GITHUB_APP_PRIVATE_KEY_FILE` | Preferred path to the mounted PEM private key. Use `GITHUB_APP_PRIVATE_KEY` only when a file mount is unavailable. |
  522. The App needs Contents read permission for clone, fetch, and pull; push needs
  523. Contents read and write. Production Compose mounts the root-owned host
  524. directory `/etc/cloud-harness-mcp` read-only at `/run/cloud-harness-secrets`,
  525. so the maintained container path is
  526. `/run/cloud-harness-secrets/github-app-private-key.pem`. Prefer the file form
  527. instead of placing a private key directly in an environment variable. Follow
  528. the [private GitHub repository setup guide](docs/github-app-private-repositories.md)
  529. for App creation, least-privilege permissions, installation, key handling,
  530. verification, troubleshooting, and rotation.
  531. ### Compose overrides
  532. | Variable | Default | Description |
  533. |---|---:|---|
  534. | `CLOUD_HARNESS_ENV_FILE` | local runtime file | Selects the Compose environment file. Production defaults to `/etc/cloud-harness-mcp/runtime.env`. |
  535. | `API_HOST_PORT` | `3100` | Loopback host port published by the credential-free ingress proxy. |
  536. | `HOST_JOBS_ROOT` | `/var/lib/cloud-harness/jobs` | Host directory mounted for workspace data. |
  537. | `HOST_STATE_ROOT` | `/var/lib/cloud-harness/state` | Host directory mounted for persistent runner state. |
  538. Compose fixes `API_HOST=0.0.0.0`, `API_PORT=3000`,
  539. `RUNNER_HOST=0.0.0.0`, `RUNNER_PORT=3001`, and
  540. `RUNNER_URL=http://runner:3001` on its private networks. Those variables are
  541. available when starting the Node.js processes directly, but changing them in
  542. the Compose runtime file has no effect because the service definition owns the
  543. wiring. Keep the API and runner private and publish only the loopback ingress.
  544. For production file ownership, key mounts, and TLS setup, use the
  545. [deployment guide](docs/deployment.md). Exact validation rules and defaults
  546. remain owned by [`packages/contracts/src/config.ts`](packages/contracts/src/config.ts),
  547. with operational rationale in the [configuration guide](docs/configuration.md).
  548. ## Documentation
  549. - [Installable cloudharness operating skill](.agents/skills/cloudharness/SKILL.md)
  550. - [Cloud Harness support](https://cloud-harness-mcp.pages.dev/support.html)
  551. - [Privacy policy](https://cloud-harness-mcp.pages.dev/privacy.html) and
  552. [terms of service](https://cloud-harness-mcp.pages.dev/terms.html)
  553. - [System architecture](docs/system-architecture.md)
  554. - [MCP usage and tool semantics](docs/mcp-api.md)
  555. - [Configuration](docs/configuration.md)
  556. - [GitHub App setup for private repositories](docs/github-app-private-repositories.md)
  557. - [Security model](docs/security-model.md)
  558. - [Development and testing](docs/development.md)
  559. - [Operations, backup, rollback, and cleanup](docs/operations.md)
  560. - [VPS deployment with nginx and Certbot](docs/deployment.md)
  561. - [Cloudflare Pages landing page](docs/cloudflare-pages.md)
  562. - [Troubleshooting](docs/troubleshooting.md)
  563. The repository is public at
  564. [bestagentkits/cloud-harness-mcp](https://github.com/bestagentkits/cloud-harness-mcp)
  565. and licensed under the [MIT License](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.