> ## 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.
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](/openhands/usage/agent-canvas/setup#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**.
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.
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**.
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](/openhands/usage/agent-canvas/llm-profiles) 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](/openhands/usage/llms/digitalocean).
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.
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
Agent Canvas 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.
## 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
* Your DigitalOcean token stays in the Agent Canvas desktop process and is never sent to the web page. Revoke the token in DigitalOcean to disconnect Agent Canvas.
* 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. The key the browser must present to use the integration. Defaults to the server's session API key. |
In the web build, the token is held in the server's memory only, so restarting the server signs you out unless `MARS_TOKEN` is set.
Set `MARS_WEB=1` in the same command that starts Agent Canvas.
```bash theme={null}
MARS_WEB=1 agent-canvas
```
From a clone of the [OpenHands repository](https://github.com/OpenHands/OpenHands):
```bash theme={null}
npm install
MARS_WEB=1 npm run dev
```
`npm run dev` also reads a `.env` file in the repository root, so you can add `MARS_WEB=1` there instead of setting it on each run.
To sign in automatically when the server starts, add your token to the same command:
```bash theme={null}
MARS_WEB=1 MARS_TOKEN= agent-canvas
```
Then open Agent Canvas in your browser and go to **Manage Backends** → **Add Backend** → **Providers**.
## 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. |
| **Could not connect to DigitalOcean.** | Copy the token again and check that it has not expired. |
| **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](/openhands/usage/agent-canvas/backends)
* [Manage LLM Profiles](/openhands/usage/agent-canvas/llm-profiles)
* [Cloud Backend](/openhands/usage/agent-canvas/backend-setup/cloud)
* [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.