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

   

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

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

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.

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.

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

• 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. 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, and make it readable only by you:

touch ~/.agent-canvas.env
chmod 600 ~/.agent-canvas.env

Open the file in a text editor and add:

export MARS_WEB=1
export MARS_TOKEN="<your-digitalocean-token>"

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

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:

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:

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 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, add these lines to .env:

MARS_WEB=1
MARS_TOKEN=<your-digitalocean-token>

Then start Agent Canvas:

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. 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 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
• Manage LLM Profiles
• Cloud Backend
• DigitalOcean Harness Runtime documentation