Skip to main content
You can connect Agent Canvas to DigitalOcean 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, version 1.27.0 or later. To use the browser version instead, see Use It From the Web Build.
  • A DigitalOcean account 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.
  • An API key for your LLM provider. You add it after connecting.

​
1. Create a Token

  1. Sign in to the DigitalOcean control panel and switch to the team you want Agent Canvas to use.
  2. Open 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.
  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.
  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 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. 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

​
Session and Agent Actions

​
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 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: 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.
To sign in automatically when the server starts, add your token to the same command:
Then open Agent Canvas in your browser and go to Manage Backends → Add Backend → Providers.

​
Troubleshooting