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. OpenHands is one of the coding harnesses you can pick in the Control Panel, so you can create an environment and start a session without writing a spec file. 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 Harness Runtime connects to that process rather than spawning an agent per turn.

Harness Runtime displays prompts, streamed replies, and tool calls in the Control Panel and in doctl like any other adapter. You can also reach the Agent Server directly from OpenHands Agent Canvas through a port-forward tunnel.

The OpenHands runtime uses the following components:

Prerequisites

To run an OpenHands agent, you need the following:

• A DigitalOcean personal access token to call the API, to use doctl, or to sign in from Agent Canvas.
• An API key for the model the agent uses, either a DigitalOcean model access key for Serverless Inference or a key for another OpenAI-compatible provider.
• Optionally, doctl to create sessions, attach to them, and forward ports from the command line.
• Optionally, OpenHands Agent Canvas 1.27.0 or later, which includes the DigitalOcean backend.

Create an OpenHands Environment in the Control Panel

An environment, also called an Environment Config, is the reusable definition you start sessions from. To create one for OpenHands:

1. Go to the Harness Runtime page and click Create Environment.
2. Under Select a Harness, choose OpenHands.
3. Under Model, choose Serverless Inference, select the model, and provide a model access key.
4. Under Configure, choose a sandbox size and set Outbound Network Access to Unrestricted or Restricted.
5. Enter a Name for the environment, then click Create Environment.

The environment appears in the Environments tab with harness: openhands in its spec. Click Create Session to start a session from it, then send a request from the session page. For the full Create Environment form, including tools, skills, and GitHub access, see Create an Environment Using a Coding Adapter.

Create an OpenHands Environment Using a Spec File

To create the same environment from the command line, write a spec that names the adapter and the model. Create openhands-agent.yaml:

name: my-openhands-agent
harness: openhands
size: mars-2vcpu-4gb
env:
  HARNESS_INFERENCE_MODEL: <your-model-name>
secrets:
  HARNESS_INFERENCE_API_KEY: ${HARNESS_INFERENCE_API_KEY}

Export the inference API key so doctl can expand ${HARNESS_INFERENCE_API_KEY}:

export HARNESS_INFERENCE_API_KEY=<your-inference-api-key>

The spec uses the following fields:

• harness (required): Must be openhands. agent is the original name of this field and is still accepted, but do not set both.
• template (optional): Leave unset. The platform derives the openhands sandbox template from the adapter.
• HARNESS_INFERENCE_MODEL (required): Model name to request. Non-secret, so declare it under env.
• HARNESS_INFERENCE_API_KEY (required): API key for the inference endpoint. Declare it under secrets, never under env.
• size, name, keep_warm, repos, and egress (optional): Same as the other coding adapters. See the environment spec reference.

Check the spec client-side before you run it:

doctl harness-runtime validate --spec ./openhands-agent.yaml

Then create the sandbox, start the agent, and attach your terminal in one step:

doctl harness-runtime launch ./openhands-agent.yaml

When the session is ready, launch attaches it to your terminal, where tool calls, reasoning output, and streamed replies appear as the agent works. Detach with Ctrl+D, and reattach with doctl harness-runtime launch <session-id-or-name>. To send one headless turn instead, run:

doctl harness-runtime prompt <session-id-or-name> "summarize the files in the workspace"

Create an OpenHands Agent Using the API

To create an agent from a script, or to create one that Agent Canvas can open, create an Environment Config with the DigitalOcean API and start a session from it.

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": "harness: 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.

Connect a Model

For the conversations Harness Runtime starts, the Agent Server holds no model configuration of its own in the sandbox. Harness Runtime supplies the model, base URL, and API key on each of those conversations, reading them from the session’s environment in the following order:

1. OPENHANDS_LLM_API_KEY, OPENHANDS_LLM_BASE_URL, and OPENHANDS_LLM_MODEL, the adapter’s native variables.
2. HARNESS_INFERENCE_API_KEY, HARNESS_INFERENCE_BASE_URL, and HARNESS_INFERENCE_MODEL, the platform defaults.

Declare each API key under secrets and the model name under env. For DigitalOcean Serverless Inference, a model access key and the ID of a Serverless Inference model are enough, because the platform supplies the endpoint. A spec may still carry HARNESS_INFERENCE_BASE_URL, but session create replaces it with the platform endpoint, so it cannot point the agent at a different one. Use OPENHANDS_LLM_BASE_URL for that, as shown below.

Conversations you start from Agent Canvas do not use any of this. They carry the LLM profile saved in Agent Canvas instead. See Use OpenHands Agent Canvas.

To use a different OpenAI-compatible provider, declare the native variables instead and include the /v1 suffix in the base URL:

env:
  OPENHANDS_LLM_BASE_URL: https://api.example.com/v1
  OPENHANDS_LLM_MODEL: <your-model-name>
secrets:
  OPENHANDS_LLM_API_KEY: ${OPENHANDS_LLM_API_KEY}

A session with no resolvable key reaches SESSION_STATUS_READY and then fails on its first turn, because the Agent Server needs a model on every conversation it creates.

Use OpenHands Agent Canvas

Agent Canvas works against the same Environment Configs and sessions. It calls each Environment Config an agent, and reaches the Agent Server through a port-forward tunnel to port 8000 in the sandbox rather than through the DigitalOcean event stream.

To add the backend and create an agent:

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 harness: 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 the Environment Config, starts a session from it, and opens the tunnel. To open a session you created elsewhere, expand an agent to see its sessions and click one, or open the agent to connect to its latest running session. Wait for Agent Canvas to connect: the backend host changes to a local tunnel address, such as 127.0.0.1:<port> on desktop. Start a new conversation before you send your first message.

Agent Canvas sends model requests from the sandbox using the LLM profile you save in it, which takes the place of the spec’s model settings on this path:

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 environments and sessions from the Harness Runtime page, the same way as any other adapter. See Work with Sessions.

While a DigitalOcean backend is active, you can also manage them from Agent Canvas:

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

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

To cancel only the agent’s current turn and keep the session and its sandbox, open the session in the Control Panel and click Stop while a turn is running, or run the following command. Unlike Stop in Agent Canvas, cancelling does not destroy the sandbox. For details, see Cancel a Run.

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

Troubleshoot OpenHands Sessions

Use this table to diagnose common OpenHands errors: