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

Prerequisites

To run an OpenHands agent, you need the following:

• A DigitalOcean personal access token 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 for Serverless Inference.
• OpenHands Agent Canvas 1.27.0 or later, which includes the DigitalOcean backend.
• Optionally, doctl to check and remove sessions from the command line.

Create an OpenHands Agent from Agent Canvas

Agent Canvas calls each Environment Config 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.

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:

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:

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:

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

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 as the API key, and enter the ID of a Serverless Inference model.
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:

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

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

Troubleshoot OpenHands Sessions

Use this table to diagnose common OpenHands errors: