For AI agents: The documentation index is at 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 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 for examples.

How It Works

Start by defining an environment: 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 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.

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 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 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:

doctl harness-runtime port-forward <session> 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.

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.

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 for supported workflows.

Permissions and Network Access

A permission policy 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 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 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, 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 for the full comparison.