> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openhands.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# DigitalOcean Managed Agents

> Run Agent Canvas conversations in isolated DigitalOcean sandboxes using Managed Agents as a backend.

You can connect Agent Canvas to [DigitalOcean Managed Agents](https://www.digitalocean.com/products/managed-agents) as a backend. Agent Canvas stays on your machine while each conversation runs in a DigitalOcean sandbox: a dedicated microVM with its own disk, terminal, and browser tools.

> [!NOTE]
>
> DigitalOcean Managed Agents is in public preview, and DigitalOcean bills sandbox usage to your DigitalOcean account. Your LLM provider bills model usage separately.

## When to Use It

A DigitalOcean backend is a good fit when you want to:

* Run agents in isolated cloud sandboxes without managing a VM, Docker host, or Kubernetes cluster
* Pay only while a sandbox is working: idle sessions pause automatically and stop compute charges
* Keep separate, disposable environments for separate tasks
* Keep using the Agent Canvas desktop app on your own machine

## Prerequisites

* The Agent Canvas [desktop app](https://docs.openhands.dev/openhands/usage/agent-canvas/setup.md#desktop-app-preview-build), version 1.27.0 or later. To use the browser version instead, see [Use It From the Web Build](#use-it-from-the-web-build).
* A [DigitalOcean account](https://cloud.digitalocean.com/registrations/new) with a payment method and funds in at least one balance.
* A DigitalOcean personal access token for the team you want to use. See [Create a Token](#1-create-a-token).
* An API key for your LLM provider. You add it after connecting.

## 1. Create a Token

1. Sign in to the [DigitalOcean control panel](https://cloud.digitalocean.com) and switch to the team you want Agent Canvas to use.
2. Open **API** → [**Tokens**](https://cloud.digitalocean.com/account/api/tokens) and select **Generate New Token**.
3. Give the token a name and an expiration, and grant it **Full Access**.
4. Copy the token. DigitalOcean only shows it once.

A token belongs to one DigitalOcean team. To connect a different team, create a token in that team and add it as another connection.

## 2. Connect Agent Canvas

1. Open the backend switcher in the top bar and choose **Manage Backends** → **Add Backend**.

2. Under **Choose how you want to connect**, select the **Providers** tab, then **DigitalOcean**.

   ![Agent Canvas Choose how you want to connect dialog with the Providers tab selected, showing the DigitalOcean provider and the note that more providers are coming soon.](https://mintcdn.com/allhandsai/1uzhRlzzDlTSUu_N/openhands/static/img/agent-canvas-add-backend-providers.png?fit=max\&auto=format\&n=1uzhRlzzDlTSUu_N\&q=85\&s=052fae2b0d38888d1f6a3635d3fc0278)

3. Paste the token into **Personal access token** and select **Connect with token**.

If you have not created a token yet, the **Create a token** link next to the field opens the DigitalOcean tokens page.

The desktop app encrypts the token with your operating system's keychain, so you stay signed in after restarting the app. If no keychain is available, Agent Canvas warns that the connection lasts only until you quit.

## 3. Create an Agent

A DigitalOcean **agent** is a saved setup for OpenHands sessions. Each **session** you launch from it is a separate sandbox with its own disk and conversations.

After you sign in, the DigitalOcean panel lists your team's **OpenHands agents**. Each row shows the agent's latest session status, and the footer shows the connection you signed in with and a **Sign out** button.

![Agent Canvas DigitalOcean panel listing three OpenHands agents: one with no sessions yet, one waiting for the agent server, and one with a paused session. New Agent and refresh buttons sit above the list, and the footer shows the DigitalOcean token connection with Sign out.](https://mintcdn.com/allhandsai/1uzhRlzzDlTSUu_N/openhands/static/img/agent-canvas-digitalocean-agents.png?fit=max\&auto=format\&n=1uzhRlzzDlTSUu_N\&q=85\&s=63302e582fedb28b849133710f0c5da8)

1. In the **OpenHands agents** list, select **New Agent**.
2. Enter an **Agent name**: up to 64 letters, numbers, `-`, `.`, or `_`, starting and ending with a letter or number.
3. Choose a **Sandbox size**, or keep **Default (DigitalOcean picks)**. Each option shows its vCPUs, memory, and monthly price.
4. Select **Create and launch**.

> [!NOTE]
>
> Sandbox size applies to every session of an agent and cannot be changed later. To use a different size, create another agent.

Agent Canvas lists only agents that run OpenHands. Agents you created in the DigitalOcean control panel for other harnesses, such as Claude Code or Codex, do not appear here.

## 4. Wait for the Session to Start

Agent Canvas launches the agent's first session and connects to it. The status moves through **Waking the session…**, **Connecting to the session…**, and **Waiting for the agent server…**. A new sandbox can take a few minutes to start; resuming a paused session is faster.

When the session is ready, Agent Canvas adds it as a backend named after the session, selects it, and opens a new conversation.

## 5. Set Up Your Model

Each session has its own agent-server, so it starts without an LLM configured.

1. Open **Settings → LLM**.
2. Add an [LLM profile](https://docs.openhands.dev/openhands/usage/agent-canvas/llm-profiles.md) with your provider, model, and API key.
3. Start a conversation.

To keep model usage on DigitalOcean too, choose the `digitalocean` provider in the LLM profile and enter a DigitalOcean model access key. See [DigitalOcean Inference](https://docs.openhands.dev/openhands/usage/llms/digitalocean.md).

Your LLM key is stored inside the session's sandbox, not in the DigitalOcean agent. Every new session needs its own LLM setup.

## Work With Agents and Sessions

While a DigitalOcean backend is selected, the sidebar shows the agent's sessions instead of the usual conversation list. The current session expands to show its conversations.

* Select **+** in the sidebar header to launch a **New session** for the same agent.
* Open the agent menu to **Switch agent** or **Manage agents**.
* **Manage agents** opens the full DigitalOcean view, where you can search, filter, and act on every agent and session.

To open an agent from **Add Backend** later, select it in the **Providers** list. Agent Canvas resumes its most recent session, or launches one if it has none. Expand the agent to choose a specific session.

### Session Status

| Status | Meaning |
| - | - |
| **Running** | The sandbox is up and ready for conversations. |
| **Starting** | The sandbox is booting. |
| **Paused** | Compute is stopped. Files, installed tools, and conversations are kept. |
| **Failed** | The sandbox did not start. Launch a new session. |
| **Ended** | The session was stopped and its sandbox deleted. |

### Session and Agent Actions

| Action | What it does | Can you undo it? |
| - | - | - |
| **Connect** / **Open** | Opens the session as your active backend. | — |
| **Resume & connect** | Wakes a paused session, then connects. | — |
| **Pause session** | Stops compute charges and keeps the session's files and conversations. | Yes, resume it |
| **Stop session** | Ends the session and deletes its sandbox, files, and conversations. | No |
| **Delete agent** | Deletes the agent so no new sessions can launch from it. Available only after all of its sessions are stopped. Paused sessions must be stopped too. | No |

### Disconnecting vs. Stopping

When you remove a DigitalOcean backend in **Manage Backends**, Agent Canvas asks what to do:

* **Disconnect only** removes the backend from Agent Canvas. The session keeps running, and billing, until it pauses on its own. You can reconnect from **Manage agents**.
* **Stop session** ends the session and deletes its sandbox, then removes the backend.

> [!WARNING]
>
> Stopping a session permanently deletes its sandbox, including any files the agent created. Push work you want to keep, for example to a Git remote, before you stop a session.

### Reconnecting After a Restart

The desktop app keeps the backend entry when you quit, but the connection to the sandbox closes. When you reopen the app, Agent Canvas reconnects to the selected DigitalOcean backend automatically. A DigitalOcean backend can show as disconnected in **Manage Backends** while it is not selected. Select it to reconnect.

> [!NOTE]
>
> In the web build or Docker, the token is not kept across restarts, even with a persistent settings volume. To stay signed in, load `MARS_TOKEN` from an env file each time you start the server or container. See [Store Your Token in an Env File](#store-your-token-in-an-env-file).

## Costs

DigitalOcean bills each session for the CPU it actually uses, its peak memory, and its storage. See [Harness Runtime pricing](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/details/pricing/) for current rates and sandbox sizes.

To keep costs down:

* **Let idle sessions pause.** DigitalOcean pauses a session after 15 minutes without activity. A paused session stops compute charges but still pays for storage.
* **Switch away when you are done.** Agent Canvas checks only the selected backend, so a session you are not using can go idle and pause.
* **Stop sessions you no longer need.** Stopping deletes the sandbox and its storage charges.
* **Pick the smallest size that works.** The default size suits most coding tasks.

Sessions pause when all of your DigitalOcean balances reach \$0, and stay paused until you add funds. Each team can have a limited number of sessions at once; paused sessions count toward that limit until you stop them.

## Security

* In the desktop app, your DigitalOcean token stays in the desktop process and is never sent to the web page. Revoke the token in DigitalOcean to disconnect Agent Canvas.
* In the web build, anyone who can read your env file can use your DigitalOcean account. Keep the file readable only by you (`chmod 600`) and out of version control. Revoke the token in DigitalOcean if the file is exposed.
* Each session runs in its own microVM, separate from your machine and from other sessions.
* Secrets and API keys you add in a session's settings are stored in that sandbox. The agent can read them while it works, as with any backend.
* Sessions can reach the public internet. They cannot reach private DigitalOcean VPC resources.
* Everyone on a DigitalOcean team can see that team's OpenHands agents and sessions.

## Use It From the Web Build

The DigitalOcean option appears in the browser version of Agent Canvas only when the server that hosts it opts in. Set these environment variables on that server, not in the browser:

| Variable | Purpose |
| - | - |
| `MARS_WEB=1` | Turns on the DigitalOcean integration for the web build. |
| `MARS_TOKEN` | Optional. A personal access token to sign in with when the server starts. |
| `MARS_WEB_KEY` | Optional. Authentication key for the DigitalOcean bridge. Falls back to the server's session API key if omitted. |
| `LOCAL_BACKEND_API_KEY` | Optional. Sets the Docker stack's session API key, which the bridge uses when `MARS_WEB_KEY` is not set. If omitted, the image generates a key and saves it in the settings volume. This is not your DigitalOcean token. |

The web build, including Docker, uses personal access tokens and does not offer OAuth sign-in. Tokens entered in the UI stay in server memory, not in the settings volume. After each container or server restart, enter the token again unless you supply `MARS_TOKEN` at startup.

For Docker, explicitly set `MARS_WEB=1`. Images that require opt-in leave the integration disabled without it. Because Docker binds to a non-loopback address inside the container, the bridge requires an authentication key and refuses to start without one. The official image always supplies one: if you set neither `LOCAL_BACKEND_API_KEY` nor `MARS_WEB_KEY`, it generates a session key on first start, as described in [Environment Variables](https://docs.openhands.dev/openhands/usage/agent-canvas/setup.md#environment-variables). The Docker example below sets `LOCAL_BACKEND_API_KEY` so you know the key's value and the bridge and local backend share it.

For CLI and source launches, the launcher can supply the session key.

### Store Your Token in an Env File

Keep `MARS_TOKEN` in an env file rather than typing it into commands. A token typed into a command is saved in your shell history and can show up in process listings. With an env file, every start uses the same values, and Agent Canvas signs in to DigitalOcean automatically.

**Installed CLI or npx**

The installed CLI does not read env files on its own. Create `~/.agent-canvas.env`, the same file used in [VM / Self-Hosted Installation](https://docs.openhands.dev/openhands/usage/agent-canvas/backend-setup/vm.md), and make it readable only by you:

```bash theme={null}
touch ~/.agent-canvas.env
chmod 600 ~/.agent-canvas.env
```

Open the file in a text editor and add:

```bash theme={null}
export MARS_WEB=1
export MARS_TOKEN="<your-digitalocean-token>"
```

Load the file in the same command that starts Agent Canvas:

```bash theme={null}
source ~/.agent-canvas.env && agent-canvas
```

For `npx`, replace `agent-canvas` with `npx @openhands/agent-canvas`.

**Docker**

Use the same `~/.agent-canvas.env` file as the Installed CLI tab. Add a local backend key to it once:

```bash theme={null}
echo "export LOCAL_BACKEND_API_KEY=\"$(openssl rand -hex 32)\"" >> ~/.agent-canvas.env
```

Load the file, then pass each variable to the container by name. With `-e NAME` and no value, Docker copies the value from your shell, so the token never appears in the command:

```bash theme={null}
source ~/.agent-canvas.env
mkdir -p ~/projects

docker run -it --rm \
  -p 127.0.0.1:8000:8000 \
  -e MARS_WEB \
  -e MARS_TOKEN \
  -e LOCAL_BACKEND_API_KEY \
  -v openhands-data:/home/openhands/.openhands \
  -v ~/projects:/projects \
  ghcr.io/openhands/agent-canvas:latest
```

Open `http://localhost:8000/canvas`. If you add this server as a backend in **Manage Backends**, enter the `LOCAL_BACKEND_API_KEY` value from `~/.agent-canvas.env` in the **API Key** field.

This example mounts the named volume `openhands-data`, which Docker creates on first use and keeps after the container exits. On Linux, a named volume prevents the UID ownership mismatch between your host user and the container user that can cause `unable to open database file`. See [Install Agent Canvas](https://docs.openhands.dev/openhands/usage/agent-canvas/setup.md#install-and-run) for more Docker setup details and Windows commands.

**From source (npm run dev)**

`npm run dev` reads a `.env` file in the repository root automatically. In your clone of the [OpenHands repository](https://github.com/OpenHands/OpenHands), add these lines to `.env`:

```ini theme={null}
MARS_WEB=1
MARS_TOKEN=<your-digitalocean-token>
```

Then start Agent Canvas:

```bash theme={null}
npm install
npm run dev
```

The repository's `.gitignore` excludes `.env`. Do not commit it or copy the token into `.env.sample`.

Then open Agent Canvas in your browser and go to **Manage Backends** → **Add Backend** → **Providers**.

### Persist Sign-In Across Restarts

The bridge does not save your DigitalOcean token to disk. A token you enter in the UI lasts only until the server or container stops. To stay signed in, load your env file every time you start Agent Canvas, as shown in [Store Your Token in an Env File](#store-your-token-in-an-env-file). For Docker, that includes each time you recreate the container.

When the token expires or you revoke it, replace `MARS_TOKEN` in the env file and restart Agent Canvas.

## Troubleshooting

| Message or symptom | What to do |
| - | - |
| **No Providers tab in Add Backend** | Use the desktop app, or set `MARS_WEB=1` on the server that hosts the web build. |
| **Docker logs report a missing bridge authentication key** | Set `LOCAL_BACKEND_API_KEY` or `MARS_WEB_KEY` along with `MARS_WEB=1`, then recreate the container. |
| **Linux: unable to open database file** | Use the named settings volume in the Docker example instead of binding `~/.openhands`. |
| **Asked for a DigitalOcean token after restarting Docker** | This is expected because UI-entered tokens are held in memory only. Enter the token again, or [load `MARS_TOKEN` from an env file](#store-your-token-in-an-env-file) at startup. OAuth is not available in the web build. |
| **Could not connect to DigitalOcean.** | Copy the token again and check that it has not expired. If you load it from an env file, check that the value has no extra spaces and that the file is loaded before Agent Canvas starts. |
| **DigitalOcean refused the connection.** | Create a new token with **Full Access**, and confirm your team can use Managed Agents. |
| **This DigitalOcean sign-in has expired.** | Create a new token and sign in again. |
| **This team has no OpenHands agents yet.** | Select **New Agent**. Agents for other harnesses are hidden. |
| **This session isn't running an OpenHands agent server…** | The session was not started from an OpenHands agent. Launch a session from an agent created in Agent Canvas. |
| **Could not launch a new session.** | Stop sessions you no longer need, and check that your DigitalOcean balance is above \$0. |
| **A session stays on Waking the session…** | Add funds to your DigitalOcean account. Sessions stay paused at a \$0 balance. |
| **Your system keychain is unavailable…** | Unlock or install a keychain (common on Linux), or sign in again each time you open the app. |
| **Conversations fail right after connecting** | Add an LLM profile in **Settings → LLM**, then try again. |

## Related Guides

* [Connect and Manage Backends](https://docs.openhands.dev/openhands/usage/agent-canvas/backends.md)
* [Manage LLM Profiles](https://docs.openhands.dev/openhands/usage/agent-canvas/llm-profiles.md)
* [Cloud Backend](https://docs.openhands.dev/openhands/usage/agent-canvas/backend-setup/cloud.md)
* [DigitalOcean Harness Runtime documentation](https://docs.digitalocean.com/products/managed-agents/agent-harness-runtime/)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.