--- title: DigitalOcean Harness Runtime Overview (public) description: Harness Runtime provides managed microVM sandboxes to run agent harnesses and execute code, with session lifecycle controls, Workspace, connections, … product: Managed Agents url: https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/concepts/overview/ last_updated: "2026-09-28" --- > **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). # DigitalOcean Harness Runtime Overview (public) DigitalOcean Harness Runtime provides managed, hardware-isolated microVM sandboxes with built-in tools such as Chromium to run harnesses and execute arbitrary code. Rich lifecycle APIs preserve conversational history and working state across sessions, letting you pause, resume, and fork work to control costs and adapt to the nonlinear nature of agentic workflows. Scale complete agents such as Claude Code or use sandboxes independently for code execution, all through the same service. See [What You Can Build](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/details/what-you-can-build/index.html.md) for example use cases. DigitalOcean Harness Runtime provides managed, hardware-isolated microVM sandboxes with built-in tools such as Chromium to run agent harnesses and execute arbitrary code. Rich lifecycle APIs preserve conversational history and working state across sessions, letting you pause, resume, and fork work to control costs and adapt to the nonlinear nature of agentic workflows. Scale complete agents such as Claude Code or use sandboxes independently for code execution, all through the same service. Workspace (beta) keeps files on a separate mounted drive that persists independently of the session lifecycle. Connections provide authenticated port forwarding so you can preview applications and reach services running inside a sandbox. Together, these capabilities let you manage execution, retain useful work, and inspect results through the same service. See [What You Can Build](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/details/what-you-can-build/index.html.md) for examples. ## How It Works Start by defining an [environment](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/concepts/environments/index.html.md): a reusable configuration manifest file for your sandbox, including its sandbox size, adapter, skills, credentials, permissions, and tools. Create it in the Control Panel or describe it in a YAML spec. Starting a [session](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/concepts/sessions/index.html.md) from an environment provisions a sandbox and starts the configured software. You can then interact with the agent, execute commands, transfer files, and connect to services inside the sandbox. Pause the session when it is idle, resume it when work continues, and remove it when it is no longer needed. Files saved to a Workspace drive persist independently of those session operations. ## When to Use Harness Runtime Use Harness Runtime to: - Run agents in the cloud instead of on a laptop or a self-managed server. - Execute agent-generated code, run tests, process datasets, or automate browser tasks in isolated sandboxes. - Pause and resume work, or fork supported sessions to explore different approaches in parallel. - Preview applications and access dashboards through authenticated local connections. - Control agent actions with permission policies, human approvals, and network restrictions. - Connect agents to external tools and services through [Action Gateway](https://docs.digitalocean.com/products/managed-agents/action-gateway/index.html.md). ## Core Components ### Environments An *environment* defines the sandbox configuration and capabilities available to a workload. It brings together the sandbox size, agent harness adapter, environment variables, credentials, skills, permissions, and tools. One environment can create many sessions. Define an environment in the Control Panel or submit a YAML spec with `doctl`. See the [Environment Spec Reference](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/reference/environment-spec/index.html.md) for supported fields. ### Sandboxes and Templates A *sandbox* is the hardware-isolated Linux microVM where code executes. It provides compute, memory, a filesystem, and networking for the workload. A *template* defines the software and dependencies available when the sandbox starts. Use a provided template or register a team-owned OCI image with Bring-Your-Own-Template (BYOT). The environment combines that starting software with the resources and access your workload needs. ### Sessions and Runs A *session* is an instance of an environment with its own sandbox and lifecycle. For supported adapters, it also maintains the agent’s conversation history and activity records. A *run* is one agent turn within a session: the agent receives input, performs work, and completes or fails. Pausing suspends compute while preserving the sandbox’s memory and filesystem state. Resuming continues from that state, and automatic idle pausing helps control compute costs between tasks. Removing a session releases its sandbox; files saved to a separate Workspace drive remain available. Interact with sessions through `doctl` or the Control Panel. See [Sessions](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/concepts/sessions/index.html.md) for lifecycle details. ### Workspace (Beta) A *Workspace* provides a separate drive mounted inside the sandbox. Its lifecycle is independent of the session, so files written to the drive persist after the session is removed. Use Workspace for repositories, datasets, and generated artifacts that need to outlive the execution that produced them. For example, an agent can analyze uploaded documents and save a report to the Workspace drive, allowing you to remove the session while retaining the source material and results. ### Connections (Port Forwarding) *Connections* let you access applications and services running inside a sandbox from your local machine. Use them to preview a web application, open an agent dashboard, or test an API. If a service is listening on port `3000` inside the sandbox, run: ```shell doctl harness-runtime port-forward 3000 ``` Open `http://127.0.0.1:3000` to reach it. To map a different local port to the service, use `8080:3000`. The command creates an authenticated tunnel and listens on your machine’s loopback address by default. It does not publish the sandbox’s port to the internet. The connection remains available while the command runs; press `Ctrl+C` to close it. A paused session resumes before the tunnel opens. See [Forward Sandbox Ports](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/how-to/forward-ports/index.html.md). ### Commands and Files Work directly with the sandbox to run scripts, install dependencies, execute tests, and inspect results. Upload input files with `doctl harness-runtime upload` and retrieve outputs with `doctl harness-runtime download`. These operations support workflows where an agent runs inside the sandbox as well as workflows where an external application uses the sandbox for code execution. See [Transfer Files](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/how-to/transfer-files/index.html.md). ### Checkpoints and Forks A *checkpoint* saves a session’s machine state at a point in time. A *fork* creates a separate session from the current state or a checkpoint, so you can explore alternative approaches while retaining the original session. A *rollback* restores a checkpoint in the original session. Support varies by adapter, and each fork starts a fresh transcript. See [Checkpoint, Fork, and Roll Back Sessions](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/how-to/checkpoint-fork-rollback-sessions/index.html.md) for supported workflows. ### Permissions and Network Access A [permission policy](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/concepts/permissions/index.html.md) controls whether supported agent actions are allowed, denied, or require human approval. For example, an agent can read a repository while requiring approval before pushing changes. [Network egress controls](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/concepts/egress/index.html.md) separately restrict which hosts the sandbox can reach. Outbound access is unrestricted unless you configure an egress allowlist. Use Connections to access services inside the sandbox through authenticated port forwarding. ### Action Gateway [Action Gateway](https://docs.digitalocean.com/products/managed-agents/action-gateway/index.html.md) provides optional access to tools, APIs, and SaaS connectors through a managed MCP endpoint. Configure tools in the Control Panel or environment spec, organize them into versioned [Toolbelts](https://docs.digitalocean.com/products/managed-agents/action-gateway/concepts/toolbelts/index.html.md), and control their permissions. You can also use Action Gateway independently from Harness Runtime through an MCP client or its Python and TypeScript SDKs. ### Adapters and Feature Availability An *adapter* connects a coding agent or framework to Harness Runtime and determines which platform features the session supports. With adapters such as `codex`, DigitalOcean runs the agent inside the sandbox and observes its activity to support event streams, permission policies, and approvals. With `codex-agentapi`, OpenAI runs the agent loop and DigitalOcean provides the execution sandbox. DigitalOcean’s agent event stream, permission policies, approvals, checkpoints, forks, and rollback are unavailable for that adapter. See [Agent Adapters](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/concepts/agent-adapters/index.html.md) for the full comparison.