---
title: Harness Runtime
description: Discover and manage Hosted Agents (Harness Runtime).
product: Reference
url: https://docs.digitalocean.com/reference/mcp/harness-runtime-mcp-tools/
last_updated: "2026-10-12"
---

> **For AI agents:** The documentation index is at [https://docs.digitalocean.com/llms.txt](https://docs.digitalocean.com/llms.txt). Markdown versions of pages use the same URL with `index.html.md` in place of the HTML page (for example, append `index.html.md` to the directory path instead of opening the HTML document).

# Harness Runtime

Generated on 6 Nov 2026

> This content is automatically generated from [https://github.com/digitalocean-labs/mcp-digitalocean/blob/main/pkg/registry/harness-runtime/README.md](https://github.com/digitalocean-labs/mcp-digitalocean/blob/main/pkg/registry/harness-runtime/README.md).

## Harness Runtime MCP Tools

Tools for discovering and managing Hosted Agents (Harness Runtime), backed by the public `/v2/harness-runtime/*` API.

Enable these tools with service name **`harness-runtime`** . Hosted URL: `https://harness-runtime.mcp.digitalocean.com/mcp`.

* * *

## Supported Tools

### Agent Configs (Environments)

> **Product name:** In the DigitalOcean Console and documentation, Agent Configs are called **Environments**. The API path and field names still use “config”, but the concepts are identical — an “Environment” *is* an Agent Config. All five tools below work for both names interchangeably.

- **`harness-runtime-list-agent-configs`** — List the active agent configs (Environments) for the team (id, name, content hash, creator, timestamps). Supports `PageSize` (1-200, default 50), `PageToken` (cursor from `next_page_token`) and `Search` (case-insensitive name substring, max 64 chars). Manifests are not returned.
- **`harness-runtime-get-agent-config`** — Get one agent config (Environment) by `ConfigID` (UUID), including its sanitized manifest and redacted credential slot metadata. Secret values are never returned.
- **`harness-runtime-create-agent-config`** — Create a new agent config (Environment) from a `Name` (required, 1-64 chars) and `Manifest` (required, JSON object or YAML string with the agent environment spec — e.g. `agent`, `size`, `env`, `permissions`, `egress`, `secrets`). Optionally set `ManageModelAccessKey` to have the platform provision a serverless-inference key. Configs are immutable after creation. Returns the created config with its assigned UUID. **SECURITY:** any values under the manifest’s top-level `secrets` map are write-only — extracted into Secrets Manager and never persisted or echoed back by this or any other tool. Never commit real secret values to files/source control; prefer environment variables or the DO Console over pasting them into a terminal that logs history.
- **`harness-runtime-delete-agent-config`** — Permanently delete an agent config (Environment) by `ConfigID` (UUID). **Destructive.** Existing sessions that reference this config are retained.
- **`harness-runtime-list-config-sessions`** — List all sessions created from a specific agent config (Environment) by `ConfigID`. Supports `PageSize`, `PageToken`, and `Status` filter.

### Sessions

- **`harness-runtime-create-session`** — Provision a new session from an existing Agent Config (`ConfigID` + `Name` required). Returns the session row immediately; sandbox boot completes asynchronously. Optional: `ResumeOnTopoff` (auto-resume consent), `WorkspaceID` (persistent workspace).
- **`harness-runtime-get-session`** — Get the current snapshot of a session by `SessionID` (UUID), including status, agent kind, sandbox id, and lineage.
- **`harness-runtime-list-sessions`** — List sessions for the team (newest first). By default omits destroyed and failed sessions; pass `Status=SESSION_STATUS_ALL` to include every session. Supports `PageSize`, `PageToken`, `Status`, `Name` (exact-match filter), and `Search` (substring filter).
- **`harness-runtime-destroy-session`** — Permanently tear down a session’s sandbox. **Destructive.** Workspace contents are retained per tenant policy.
- **`harness-runtime-send-input`** — Deliver a user message into a READY or DETACHED session. Requires `SessionID` and at least one of `Text` (string) or `Inputs` (structured dict). Returns the `run_id`.
- **`harness-runtime-pause-session`** — Freeze a READY/DETACHED session’s microVM sandbox. microvm-substrate only.
- **`harness-runtime-resume-session`** — Explicitly thaw a PAUSED session’s sandbox. Returns synchronously once ready.
- **`harness-runtime-patch-session`** — Update session-scoped settings. Currently supports `ResumeOnTopoff` (auto-resume consent toggle). Returns the updated session snapshot.
- **`harness-runtime-resolve-hitl`** — Record the user’s decision on a pending HITL request. `Outcome` must be one of `HITL_OUTCOME_APPROVE`, `HITL_OUTCOME_REJECT`, or `HITL_OUTCOME_DEFER`. Optional: `Reason` (audit trail text), `Content` (structured form answer).
- **`harness-runtime-fork-session`** — Create 1-4 child sessions from a checkpoint of an existing session. `SessionID` required; `FromCheckpointID` (READY checkpoint UUID to fork from — omit to capture an implicit checkpoint of “now”) and `Count` (1-4, default 1) are optional. Returns the created child sessions with `parent_session_id` and `fork_id` set.
- **`harness-runtime-exec-in-sandbox`** — Run a one-shot command inside a session’s sandbox. `SessionID` and `Argv` (non-empty string array) required. Optional: `Workdir` (default `/workspace`), `Stdin` (base64-encoded), `TimeoutSeconds` (max 240, server-enforced). Returns `exit_code`, `stdout`, `stderr`, and `duration_ms`. A non-zero exit code is still a successful HTTP response — check the field.
- **`harness-runtime-get-ingress-url`** — Get (or provision on first call) the public HTTPS ingress URL for the session’s sandbox port 8000 (OpenHands Agent Server). Idempotent while the session runs; revoked on pause/lock/rollback — re-fetch after those operations. Poll until `state` is `INGRESS_URL_STATE_READY`. Only OpenHands sessions support ingress.
- **`harness-runtime-cancel-turn`** — Stop the turn currently running in a session (the Ctrl-C / Esc equivalent) and leave the session alive and idle. `SessionID` required; `RunID` optional (from `send-input`’s response — names the specific turn to cancel; omit to cancel whatever is in flight). The outcome field tells you what happened: `acked`, `no_turn`, or `unsupported`.

### Checkpoints

- **`harness-runtime-list-checkpoints`** — List a session’s checkpoints newest first. `SessionID` required. Supports `PageSize` (1-200) and `PageToken` cursor.
- **`harness-runtime-get-checkpoint`** — Get the current snapshot of a checkpoint by `SessionID` and `CheckpointID`. Poll until `status` is `READY` before forking or rolling back.
- **`harness-runtime-create-checkpoint`** — Capture a session’s live sandbox state as a durable checkpoint. `SessionID` required; optional `Label`. Synchronous — blocks until the checkpoint is READY and returns it directly. The session must not have an active turn in flight (409 if busy). Returns 501 for agents/substrates that do not support checkpoints.
- **`harness-runtime-delete-checkpoint`** — Delete a checkpoint and its underlying machine-state capture. `SessionID` and `CheckpointID` required. **Destructive.** Idempotent: deleting an already-gone checkpoint still returns success.
- **`harness-runtime-rollback-checkpoint`** — Rewind a session to a READY checkpoint. `SessionID` and `CheckpointID` required. **Destructive.** In-place restore — same `session_id`, new `sandbox_id`. The session must not have a workspace attached. The ingress URL is revoked — re-fetch after the session is READY.

### Sandbox

- **`harness-runtime-list-sandbox-sizes`** — List the available sandbox compute sizes (slug, vCPUs, memory, hourly and monthly pricing). The returned slugs are valid values for sandbox size fields in manifests.
- **`harness-runtime-validate-policy`** — Stateless preflight: check a manifest’s tool-permission policy against the agent’s capabilities without creating a session. Takes `Manifest` (same JSON object as create-agent-config, must include a `permissions` block). Returns per-rule verdicts (`exact`, `degraded`, `unsupported`, `unverified`); `ok=false` means CreateSession would reject this policy.

### Templates

Custom sandbox templates let you layer an OCI image on a base template for a customized agent environment.

- **`harness-runtime-list-templates`** — List the team’s custom sandbox templates (id, name, status, spec, timestamps). Keyset-paginated. Only READY templates can be referenced in agent configs.
- **`harness-runtime-get-template`** — Get a single custom sandbox template by `TemplateID` (UUID), including its spec (base template + OCI image source) and status.
- **`harness-runtime-create-template`** — Register a new custom sandbox template. Requires `Name`, `BaseTemplate` (key like `codex-base`, `opencode-base`, `claude-code-base`, `hermes-base`, `hermes-byoa-base`, `langgraph-base`, `coding-base`, `crewai`), and `SourceOCIRef` (OCI image reference). The platform builds it asynchronously — poll until `TEMPLATE_STATUS_READY`.
- **`harness-runtime-update-template`** — Update a template’s `SourceOCIRef` and/or `BaseTemplate` key. Triggers a new build; poll until READY. Returns the updated template.
- **`harness-runtime-delete-template`** — Permanently delete a custom sandbox template by `TemplateID` (UUID). **Destructive.** Agent configs referencing this template can no longer create sessions.
- **`harness-runtime-list-template-builds`** — List builds for a template (newest first). `TemplateID` required. Supports `PageSize` and `PageToken` cursor.
- **`harness-runtime-get-template-build`** — Get a single build by `TemplateID` and `BuildID` (both UUIDs). Includes status (PENDING, BUILDING, SUCCEEDED, FAILED), error message on failure, and the spec.

### Workspaces

Persistent workspaces are virtual disk volumes that survive across sessions.

- **`harness-runtime-create-workspace`** — Provision a new persistent workspace. `SizeGibibytes` (1-100, integer) required. Optional `Name` label. Size is fixed at creation.
- **`harness-runtime-list-workspaces`** — List the team’s workspaces. Supports `PageSize`, `PageToken`, and `State` filter (`AVAILABLE`, `ATTACHING`, `ATTACHED`, `RELEASING`, `FAILED`, `DELETING`).
- **`harness-runtime-get-workspace`** — Get a single workspace by `WorkspaceID` (UUID), including state, attached session, size, bytes used, and timestamps.
- **`harness-runtime-delete-workspace`** — Permanently delete a workspace by `WorkspaceID`. **Destructive.** Must not be attached (409 if attached). All data is lost.

### Workspace Transfers

Bulk file transfer to/from a session’s attached workspace via multipart upload or async download.

- **`harness-runtime-create-workspace-transfer`** — Initiate a transfer (`SessionID` + `Direction` = `upload` | `download`). Uploads return `transfer_id`, `upload_id`, `part_size`, `expires_at`. Downloads return `transfer_id` — poll until completed.
- **`harness-runtime-get-workspace-transfer`** — Get transfer status. For downloads, poll until `completed` to get `download_url` and `sha256`. For uploads, check `bytes_written`.
- **`harness-runtime-cancel-workspace-transfer`** — Abort an active transfer. Idempotent.
- **`harness-runtime-commit-workspace-upload`** — Finalize a multipart upload after all parts are PUT. Returns `size_bytes`.
- **`harness-runtime-create-workspace-part-urls`** — Get presigned PUT URLs for a set of part numbers. `PartNumbers` (array of positive integers) required. URLs expire at `expires_at`.

### Connections

Connections link external provider accounts (GitHub, GitLab) to the team so agents can access repos.

- **`harness-runtime-list-connections`** — List the team’s connections for an external provider. `Provider` (`github` or `gitlab`) required. Supports `ActorID`, `Status`, `Page`, and `PerPage` (1-100, default 20).
- **`harness-runtime-create-connection`** — Create (or resume) a connection binding an actor to an external provider. `Provider` and `ActorID` required. A still-pending connection comes back with an Authorization the user must complete in a browser. Optional: `Scopes` (omit for the provider’s full configured scope set).
- **`harness-runtime-get-connection`** — Get one connection by `Provider` and `ConnectionID`, including its status and any pending authorization.
- **`harness-runtime-delete-connection`** — Revoke and delete one connection by `Provider` and `ConnectionID`. **Destructive.** Connections with `deletion_protected=true` (referenced by an active environment) will be refused.

### Provider Auth

OAuth device-flow to connect the team to an external provider. The user opens the `connect_url` in a browser, enters the `verification_code`, and polls until the authorization is complete.

- **`harness-runtime-start-provider-auth`** — Begin (or resume) the OAuth device-flow connect for an external provider. `Provider` (`github` or `gitlab`) required. Returns `connect_url`, `verification_code`, and `poll_url`. Status is `pending` when the user must still authorize, or `success` when already connected.
- **`harness-runtime-poll-provider-auth`** — Check whether a pending provider authorization has been completed. `Provider` and `PollURL` (from `start-provider-auth`) required. Call repeatedly until status is `success`.

### Triggers

Triggers automate agent session launches on a schedule (cron) or via webhook.

- **`harness-runtime-list-triggers`** — List the team’s triggers. Supports `PageSize`, `PageToken`, and optional `ConfigID` filter.
- **`harness-runtime-create-trigger`** — Create a new trigger. `Name`, `Kind` (`webhook` or `cron`), `SessionMode` (`fresh` or `reuse`), and `PromptTemplate` required. Webhook triggers return a webhook URL and signing secret. Fresh mode requires `SessionTemplate`; reuse mode requires `BoundSessionID`. Optional: `CronExpr`, `Timezone`, `OutputMode` (`none`/`email`/`slack`), `MaxConcurrency`.
- **`harness-runtime-get-trigger`** — Get a trigger by `TriggerID` (UUID).
- **`harness-runtime-update-trigger`** — Update a trigger’s mutable fields (name, prompt, session mode, schedule, output, etc.). At least one field required. Returns the updated trigger.
- **`harness-runtime-delete-trigger`** — Permanently delete a trigger. **Destructive.**
- **`harness-runtime-pause-trigger`** — Pause an active trigger. In-flight executions continue to completion.
- **`harness-runtime-resume-trigger`** — Resume a paused trigger.
- **`harness-runtime-rotate-trigger-secret`** — Rotate the webhook signing secret for a webhook trigger. The old secret is immediately invalidated.
- **`harness-runtime-list-trigger-executions`** — List executions for a trigger. Supports `PageSize` and `PageToken`.
- **`harness-runtime-get-trigger-execution`** — Get a single execution by `TriggerID` and `ExecutionID`.
- **`harness-runtime-cancel-execution`** — Cancel a running trigger execution. `TriggerID` and `ExecutionID` required.
- **`harness-runtime-get-trigger-by-session`** — Look up the trigger associated with a given session by `SessionID`.
- **`harness-runtime-list-reusable-sessions`** — List paused sessions available for reuse binding. Supports `PageSize` and `PageToken`.

### Webhook Providers

- **`harness-runtime-list-webhook-providers`** — List the supported webhook providers for trigger creation. Returns a static catalog (e.g. GitHub, GitLab, Custom) with display names, documentation URLs, paste hints, and signature verification schemes. No pagination.

Requires the `agent_harness_session:read` scope (read tools) and `agent_harness_session:create` / `agent_harness_session:delete` (write tools).

* * *

## Example queries

- List my hosted agent configs.
- Show me the manifest of agent config 019fb39c-14d9-7080-933e-b9b90e25acda.
- Find the agent config named “support” so I can run a simulation against it.
- Create a new agent config from this manifest JSON.
- Delete agent config 019fb39c-14d9-7080-933e-b9b90e25acda.
- List all sessions created from config 019fb39c-14d9-7080-933e-b9b90e25acda.
- Create a new session from config 019fb39c-14d9-7080-933e-b9b90e25acda named “test-run-1”.
- List all my active sessions.
- What is the status of session 029ab39c-14d9-7080-933e-b9b90e25acda?
- Send a message to my session: “Summarize the latest GitHub issues.”
- Pause session 029ab39c-14d9-7080-933e-b9b90e25acda.
- Resume the paused session.
- Approve the HITL request on session 029ab39c-14d9-7080-933e-b9b90e25acda.
- Enable auto-resume on session 029ab39c-14d9-7080-933e-b9b90e25acda so it restarts automatically when the balance is restored.
- Destroy session 029ab39c-14d9-7080-933e-b9b90e25acda.
- Fork session 029ab39c-14d9-7080-933e-b9b90e25acda into 3 child sessions.
- Fork from checkpoint cp_9f2c1a4b of session 029ab39c-14d9-7080-933e-b9b90e25acda.
- Run `ls /workspace` in session 029ab39c-14d9-7080-933e-b9b90e25acda.
- Get the ingress URL for session 029ab39c-14d9-7080-933e-b9b90e25acda.
- Cancel the current turn in session 029ab39c-14d9-7080-933e-b9b90e25acda.
- List all checkpoints for session 029ab39c-14d9-7080-933e-b9b90e25acda.
- Create a checkpoint of session 029ab39c-14d9-7080-933e-b9b90e25acda labeled “before-refactor”.
- Roll back session 029ab39c-14d9-7080-933e-b9b90e25acda to checkpoint cp_9f2c1a4b.
- Delete checkpoint cp_9f2c1a4b from session 029ab39c-14d9-7080-933e-b9b90e25acda.
- What sandbox sizes are available?
- Validate this policy against session 029ab39c-14d9-7080-933e-b9b90e25acda.
- List my custom sandbox templates.
- Show me template 049fb39c-14d9-7080-933e-b9b90e25acdc.
- Create a new template “my-python-env” from codex-base with my OCI image.
- Update template 049fb39c-14d9-7080-933e-b9b90e25acdc to use a new image tag.
- Delete template 049fb39c-14d9-7080-933e-b9b90e25acdc.
- List builds for template 049fb39c-14d9-7080-933e-b9b90e25acdc.
- Show build details for template 049fb39c-14d9-7080-933e-b9b90e25acdc build 059fb39c-14d9-7080-933e-b9b90e25acdd.
- Create a 10 GiB workspace named “project-data”.
- List my workspaces.
- What’s the status of workspace 069fb39c-14d9-7080-933e-b9b90e25acde?
- Delete workspace 069fb39c-14d9-7080-933e-b9b90e25acde.
- Start an upload transfer on session 029ab39c-14d9-7080-933e-b9b90e25acda.
- Check the status of transfer xfer-abc123 on session 029ab39c-14d9-7080-933e-b9b90e25acda.
- Get upload URLs for parts 1, 2, and 3 of transfer xfer-abc123 on session 029ab39c-14d9-7080-933e-b9b90e25acda.
- Commit transfer xfer-abc123 on session 029ab39c-14d9-7080-933e-b9b90e25acda.
- Cancel transfer xfer-abc123 on session 029ab39c-14d9-7080-933e-b9b90e25acda.
- List my GitHub connections.
- Create a GitHub connection for actor user-123.
- Show connection conn-abc123 for GitHub.
- Delete GitLab connection conn-abc123.
- Connect my team to GitHub (start the OAuth device flow).
- Check if the GitHub authorization is complete (poll the auth flow).
- What webhook providers are supported for triggers?
- List my triggers.
- Create a webhook trigger named “pr-review” that sends “Review this PR” to a fresh codex session.
- Create a cron trigger that runs daily at 9 AM Eastern.
- Pause trigger 079fb39c-14d9-7080-933e-b9b90e25acdf.
- Resume trigger 079fb39c-14d9-7080-933e-b9b90e25acdf.
- Rotate the webhook secret for trigger 079fb39c-14d9-7080-933e-b9b90e25acdf.
- List executions for trigger 079fb39c-14d9-7080-933e-b9b90e25acdf.
- Cancel execution 089fb39c-14d9-7080-933e-b9b90e25ace0 on trigger 079fb39c-14d9-7080-933e-b9b90e25acdf.
- Which trigger launched session 029ab39c-14d9-7080-933e-b9b90e25acda?
- List reusable sessions I can bind to a trigger.
- List my environments (agent configs).