OpenHands Agent Canvas: Self-Hosted Developer Control Center

OpenHands Agent Canvas: The Self-Hosted Developer Control Center for Coding Agents and Automations

In a world where software development is increasingly powered by intelligent agents, OpenHands Agent Canvas positions itself as a self-hosted control center for engineers. It is designed to host, manage, and orchestrate coding agents and automations across a spectrum of environments — from your laptop to Docker containers, virtual machines, private data centers, and cloud infrastructures. The goal is clear: keep your engineering teams powered by always-on agents that can start conversations, perform routine tasks, and automate repetitive work without compromising security or control.

What is OpenHands Agent Canvas?

Agent Canvas is the heart of OpenHands’ developer tooling for coding agents. It turns your pool of coding agents into a self-hosted, always-on engineering team. Think of it as a command center that lets you kick off conversations with agents, assign tasks, and automate day-to-day workflows. It works locally by default but designed to connect to multiple “agent backends,” whether those agents run on your private servers, in Docker containers, on virtual machines, or in the cloud. You can opt to run agents on OpenHands Cloud or OpenHands Enterprise infrastructure as well.

The beauty of Agent Canvas lies in its flexibility. The system is built to work with a wide range of agents, including the OpenHands agent out-of-the-box, as well as third-party agents like Claude Code, Codex, and others that adhere to the Agent-Client Protocol (ACP). This interoperability means you can switch between engines, scale across environments, and still keep a single, coherent control surface in your frontend.

Key capabilities at a glance

Self-host your way: Run agents locally, in Docker, on virtual machines, or anywhere you can host an agent server backend. The architecture is designed so you don’t lose focus when you switch backends.
Switch between backends: Move between local, remote, and cloud agents without reconfiguring your workflows. The Agent Canvas frontend remains the same while the underlying agent servers can be changed as needed.
Create automations: Build workflows that automate routine tasks, such as generating reports that publish to Slack or decomposing GitHub issues into actionable tasks. Automations can operate on schedules or in response to webhook events.
Integrate with your tools: Agent Canvas connects to a broad ecosystem — Slack, GitHub, Notion, and more — to automate end-to-end workflows across your toolchain.
Bring your own model: Use with any LLM. The platform is designed to be model-agnostic so you can plug in the large language model (LLM) you prefer.
Use with any agent: The system supports OpenHands agents, Claude Code, Codex, Gemini, and other ACP-compliant agents. If you have questions or feedback, you can open a GitHub issue or join the Slack channel referenced in the docs.

In addition to the core capabilities, the project emphasizes self-hosting as a core value proposition. You stay in control of the code, the data, and the runtime environment. The architecture is designed to let teams share an Agent Server among teammates for collaborative code reviews and dependency updates, while personal agents can continue running on individual laptops.

Agent Canvas automation preview

Why self-host, and how does it fit into a modern engineering workflow?

Self-hosting gives you tangible security and governance advantages. By running Agent Canvas on premises, on private clouds, or in a controlled cloud environment, you preserve control over sensitive data, code, secrets, and access patterns. This openness makes it feasible to create enterprise-grade automations that ride on top of your existing infrastructure, CI/CD pipelines, issue trackers, and notification channels.

Agent Canvas is designed to be the central brain for a distributed set of agents. It can connect to multiple agent backends and flip between them on demand, without losing track of your ongoing conversations, tasks, or automation state. The architecture supports a scalable model where the agent server handles the execution and concurrency while the frontend supplies the orchestration layer and visualization. Paired with an Automation Server, which schedules tasks or fires them in response to events, you have a robust automation ecosystem with clear boundaries and responsibilities.

A closer look at the quickstart options

OpenHands provides several pathways to get started, depending on your needs, hardware, and security posture. Here are three common routes:

Option 1: Without a Sandbox (direct agent-server deployment)

Prerequisites: Node.js 22.12.x or later, uv (for running certain components)
Installation: npm install -g @openhands/agent-canvas agent-canvas
Start: The agent-canvas command boots the full local stack by default
Notes: This option runs the agent-server directly on the machine, so the agent will have full access to your filesystem. It’s best for development or trusted environments where you control the machine and the data.
Optional splitting: You can run components separately, for example:
agent-canvas --frontend-only (static frontend + ingress only)
agent-canvas --backend-only (agent server + automation backend + ingress only)

Option 2: With a Docker Sandbox

Prerequisites: Docker Desktop (macOS/Windows) or Docker Engine on Linux, plus a host directory for PROJECTS_PATH to contain your project folders
Example (macOS/Linux):
export PROJECTS_PATH="$HOME/projects"
mkdir -p "$PROJECTS_PATH"
docker run -it --rm -p 8000:8000 -v "$HOME/.openhands:/home/openhands/.openhands" -v "${PROJECTS_PATH}:/projects" ghcr.io/openhands/agent-canvas:1.0.0-rc.11
Windows: See the provided README.windows.md for equivalent commands
Outcome: The agent will be able to access any project under PROJECTS_PATH
Why Docker: The sandbox isolates the runtime, provides reproducibility, and simplifies deployment across teams

Option 3: From Source

Prerequisites: Node.js 22.12.x or later, npm, uv
Commands:
git clone https://github.com/OpenHands/agent-canvas.git
cd agent-canvas
npm install
npm run dev
Access: UI available at http://localhost:8000
Backends: You can add additional backends directly from the UI
Warning: This also runs the agent-server directly on the machine, with full filesystem access

Architecture and how the pieces fit together

Agent Canvas is powered by the OpenHands Agent Server, a REST API designed to run multiple agents on a single host. Each Agent Server binds to its own host/port, and the Agent Canvas frontend can connect to several such servers. This design enables a highly modular setup where:

You can run an Agent Server on your laptop for personal experimentation, on a Mac Mini for a small team, on a VM in the cloud for scalable workloads, or inside OpenHands Cloud for a managed experience.
The Agent Server is often paired with an Automation Server, which orchestrates scheduled tasks and event-driven actions. This pairing helps you implement workflows that run automatically without manual initiation.

Here is the flow in more practical terms:

The Agent Canvas frontend provides the user interface, showing conversations, tasks, automations, and the state of each agent.
The Agent Server executes the logic for a single or a cluster of agents, handling prompts, tool calls, and long-running operations.
The Automation Server (when used) manages time-based or event-driven triggers, enabling workflows to run on a schedule or in response to system events.
You can switch between multiple Agent Servers from the same frontend, enabling a multi-backend architecture without losing continuity.

cb6de6f5-ac30-4d04-a76a-b5c259f0c163

Images and what they illustrate

The OpenHands logo reinforces the branding and web presence of the project.
The automation preview image demonstrates what a typical Agent Canvas workflow might look like in action, including how automations can be visualized in the UI and how tasks flow through agents and backends.
The third image (cb6de6f5-ac30-4d04-a76a-b5c259f0c163) can serve as a conceptual snapshot, illustrating the architecture or a sample interaction. Use this image to convey the idea of interconnected backends, agents, and automation logic.

Getting started: a practical path to productivity

The quickest way to begin is to decide how you want to run your agents and then proceed with the corresponding setup:

Local development on a laptop: Use the without-sandbox option to quickly stand up a local stack and start experimenting with conversations and simple automations. This is ideal for tinkering and prototyping.
Team experiments with shared backends: Use Docker to run a sandboxed agent server that multiple teammates can access. This keeps personal work separate from shared organizational workflows while still offering a central control plane.
Full production-like environment: Run from source or deploy on a cloud VM or private infrastructure. In this scenario, you can tailor security policies, access controls, and network topology to your organization’s standards, while taking advantage of the integration capabilities and automation features.

A step-by-step outline for a typical setup

Install the frontend and backend stack (choose your preferred method from the Quickstart options).
Start an Agent Server and, if desired, pair it with an Automation Server.
In the Agent Canvas frontend, add or connect to your Agent Server(s).
Create an automation that integrates with Slack (for notifications), GitHub (for issue management), Notion (for documentation), or any other supported service.
Bring in your preferred LLM or use the default OpenHands agent, ensuring ACP compatibility if you plan to use third-party agents.
Define tasks and triggers: schedule, webhooks, or event-based triggers to keep your engineering workflows responsive and reliable.
Test your automations in a safe environment, then roll them out to production with appropriate access controls and auditing.

Notes on security and governance

The “Without a Sandbox” option grants broad filesystem access to the agent server. Use it only in trusted environments or during early development.
The Docker Sandbox option provides a safer runtime boundary, isolating processes and reducing the risk of unintended access.
When deploying in a team or enterprise setting, consider isolating agents by project, team, or data classification, and use role-based access control (RBAC) for the Agent Canvas UI and the underlying agent servers.
Regularly review automation logs, prompts, and tool usage to ensure compliance with company policies and data handling standards.

Documentation and learning resources

OpenHands provides a comprehensive set of resources to help you unlock the full potential of Agent Canvas:

Documentation index: A centralized entry point for guides, tutorials, and reference material (https://docs.openhands.dev/overview/introduction)
Architecture overview: A high-level diagram and explanation of the system’s components and how they interact
Development guide: Practical instructions for building and contributing to the project
Self-hosting guide: Step-by-step instructions for securely running the stack in your environment (https://docs.openhands.dev/openhands/usage/agent-canvas/backend-setup/vm)
Backends and ACP agents: Details on how to configure and switch between backends and the supported agent types
Prebuilt automations: Ready-to-use automation templates that integrate with popular services (Slack, GitHub, and more)

Community and collaboration

If you have questions, feedback, or ideas, you can:

Open a GitHub issue in the OpenHands repositories
Join the #proj-agent-canvas channel on Slack
Explore further examples and use cases in the documentation

Architectural diagram and deeper dive

For teams that want a deeper understanding of how Agent Canvas maps to real-world deployments, the following concepts are useful:

The separation of concerns between the frontend (UI, orchestration), the Agent Server (execution of tasks, prompts, and tool calls), and the Automation Server (scheduling and event-driven triggers)
The ability to host multiple Agent Servers on a single machine or across a distributed infrastructure, enabling scalable, fault-tolerant agent ecosystems
The interplay between local, remote, and cloud backends, allowing you to route conversations and tasks to the most appropriate execution environment
The ease of swapping backends without losing state, ensuring smooth transitions during scaling or governance migrations

A quick tour of the ecosystem

Core framework: OpenHands Agent Server, a REST API that runs multiple agents in a cohesive, parallelizable fashion
Frontend: Agent Canvas, the control center that provides visibility into agent conversations, automations, and task progression
Automation layer: A separate server that handles time-based or event-driven tasks, enabling robust automation workflows
ACP compatibility: The ability to work with OpenHands’ own agents or third-party agents that adhere to the ACP interface
Modules and namespaces: The architecture supports modular backends and project-specific automations, enabling teams to compartmentalize duties and responsibilities

Putting it all together: benefits in practice

Rapid iteration: Developers can test prompts, tool calls, and workflows quickly, without risking disruption to core systems
Consistent workflow orchestration: A single UI to manage conversations, tasks, and automations across multiple agent backends
Scalable automation: Automations can be scheduled or event-driven, and can coordinate actions across Slack, GitHub, Notion, and more
Flexible deployment: From a single laptop to a distributed cloud deployment, Agent Canvas adapts to your infrastructure
Model and agent agnosticism: Bring your preferred LLMs and ACP-compatible agents, preserving autonomy over your tooling choices

Closing thoughts

OpenHands Agent Canvas embodies a pragmatic approach to modern software engineering: empower engineers with autonomous agents while preserving control, security, and flexibility. By providing the tools to run agents wherever you want, to switch backends on the fly, and to connect to a broad set of services, Agent Canvas becomes a concrete solution for teams seeking to automate routine tasks, augment their code review processes, and generate insights without sacrificing governance.

If you’re curious to explore more, take the next steps with the Quickstart options, browse the documentation, and consider engaging with the community through Slack or GitHub. The project is designed to evolve, with ongoing transitions and improvements. See the Agent Canvas transition FAQ for the latest guidance, and stay connected with the broader OpenHands ecosystem as you build your self-hosted, agent-powered engineering pipeline.

Images referenced in this post

OpenHands logo: https://assets.openhands.dev/logo-whitebackground.png
Agent Canvas automation preview: https://assets.openhands.dev/screenshot/automation-preview.png
Architecture/diagram image: https://github.com/user-attachments/assets/cb6de6f5-ac30-4d04-a76a-b5c259f0c163