---
title: How to Run an OpenHands Agent on DigitalOcean Harness Runtime (public)
description: Run the OpenHands Agent Server in a Harness Runtime sandbox, create agents from OpenHands Agent Canvas or the DigitalOcean API, and connect a model.
product: Managed Agents
url: https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/how-to/run-openhands-agent/
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).

# How to Run an OpenHands Agent on DigitalOcean Harness Runtime (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 runs the OpenHands Agent Server in an isolated sandbox, and you work with it from OpenHands Agent Canvas on your desktop or in a browser. Like the Hermes gateway, the Agent Server is a long-lived process. The sandbox template starts the unmodified upstream server once and supervises it, and Agent Canvas reaches it through a port-forward tunnel to the sandbox.

The OpenHands runtime uses the following components:

| Component | Value |
|---|---|
| Runtime adapter | `openhands` |
| Sandbox template | `openhands` |
| Agent Server | Upstream OpenHands Agent Server image, `ghcr.io/openhands/agent-server` |
| Agent Server port | `8000` inside the sandbox |

## Prerequisites

To run an OpenHands agent, you need the following:

- A [DigitalOcean personal access token](https://docs.digitalocean.com/reference/api/create-personal-access-token/index.html.md) to sign in from Agent Canvas and to call the API.
- An API key for the model the agent uses, either from an OpenAI-compatible provider or a [DigitalOcean model access key](https://docs.digitalocean.com/products/inference/how-to/manage-model-access-keys/index.html.md) for Serverless Inference.
- OpenHands Agent Canvas 1.27.0 or later, which includes the DigitalOcean backend.
- Optionally, [`doctl`](https://docs.digitalocean.com/reference/doctl/how-to/install/index.html.md) to check and remove sessions from the command line.

## Create an OpenHands Agent from Agent Canvas

Agent Canvas calls each [Environment Config](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/how-to/use-agent-configs/index.html.md) an agent. Creating an agent from Agent Canvas creates the config and starts its first session in one step:

1. In Agent Canvas, open **Manage Backends**, then click **Add Backend**.
2. Select the **DigitalOcean** tab and sign in with your personal access token. Agent Canvas lists your existing OpenHands agents, which are the Environment Configs whose spec sets `agent: openhands`.
3. Click **New Agent** and enter a name. Names are 1 to 64 characters long, can contain letters, digits, `.`, `_`, and `-`, and must start and end with a letter or digit.

Agent Canvas creates an Environment Config with `agent: openhands` and `template: openhands`, starts a session from it, and opens a port-forward tunnel to the Agent Server on port `8000`. Then [connect a model](#connect-a-model).

## Create an OpenHands Agent Using the API

To create an agent outside Agent Canvas, for example from a script, create an Environment Config with the DigitalOcean API, start a session from it, and then open the session in Agent Canvas.

An OpenHands spec needs only the adapter and template:

```yaml
agent: openhands
template: openhands
```

The spec uses the following fields:

- `agent`: `openhands`.
- `template`: `openhands`.

The API takes the spec as a YAML string in the `manifest_yaml` field of the request body. Export your token, then create the Environment Config:

```shell
export DIGITALOCEAN_TOKEN=<your-personal-access-token>

curl -sS -X POST "https://api.digitalocean.com/v2/agents/configs" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-openhands-agent", "manifest_yaml": "agent: openhands\ntemplate: openhands\n"}'
```

The response contains the new config under `config`. Note the value of `config.id`, then start a session from the config:

```shell
curl -sS -X POST "https://api.digitalocean.com/v2/agents/sessions" \
  -H "Authorization: Bearer $DIGITALOCEAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-openhands-session", "config_id": "<your-config-id>"}'
```

The response contains the session under `session`, including its `session_id`. The session is ready when its `status` is `SESSION_STATUS_READY`. To check the status, run `doctl harness-runtime show <session-id-or-name>`. To start more sessions from the same config, repeat the request with a new session name.

When the session is ready, [open it in Agent Canvas](#open-a-session-in-agent-canvas).

## Open a Session in Agent Canvas

With a DigitalOcean backend added, Agent Canvas lists your OpenHands agents and their sessions:

1. Expand an agent to see its sessions.
2. Click a session, or open the agent to connect to its latest running session.
3. Wait for Agent Canvas to connect. The backend host changes to a local tunnel address, such as `127.0.0.1:<port>` on desktop.

After Agent Canvas connects, start a new conversation before you send your first message.

## Connect a Model

The Agent Server sends model requests from the sandbox using the LLM profile you save in Agent Canvas:

1. Open **Settings**, then **LLM profiles**.
2. Keep the suggested model or choose another one, then paste your API key. To use DigitalOcean Serverless Inference, select OpenAI as the provider. Under **Advanced**, set the base URL to `https://inference.do-ai.run/v1`, enter a [model access key](https://docs.digitalocean.com/products/inference/how-to/manage-model-access-keys/index.html.md) as the API key, and enter the ID of a [Serverless Inference model](https://docs.digitalocean.com/products/inference/details/models/index.html.md).
3. Save the profile.
4. Send a short message to confirm that the agent responds.

## Manage OpenHands Sessions

Manage agents and sessions from Agent Canvas while a DigitalOcean backend is active:

| Action | Where |
|---|---|
| Switch to another agent or session | **Managed Agents** panel in the sidebar |
| View and manage all agents | **Manage Backends**, then **Managed Agents** |
| Stop a session | **Stop** on the session row. Stopping destroys the sandbox. |
| Delete an agent | **Delete** in the agent header. Available only when the agent has no running sessions. |

To remove a session and its sandbox from the command line, run:

```shell
doctl harness-runtime remove <session-id-or-name>
```

## Troubleshoot OpenHands Sessions

Use this table to diagnose common OpenHands errors:

| Symptom | Likely cause | What to do |
|---|---|---|
| The **DigitalOcean** tab is missing in Agent Canvas | The Agent Canvas version does not include the DigitalOcean backend. | Update Agent Canvas to 1.27.0 or later. |
| The agent name is rejected | The name breaks the naming rules. | Use 1 to 64 letters, digits, `.`, `_`, or `-`, starting and ending with a letter or digit. |
| Model requests fail with an authentication error | The LLM profile has no API key, or the key does not match the provider. | Save an LLM profile with a valid key. For Serverless Inference, use a model access key and a base URL that ends in `/v1`. |
| **Delete** is unavailable for an agent | The agent still has running sessions. | Stop each session, then delete the agent. |