OpenHands: An Introduction to the AI Developer Control Center

What it is

OpenHands is an open-source project and community centered on artificial intelligence-driven software development. Its central interface is Agent Canvas, a self-hosted developer control center created to manage autonomous software engineering agents and automate common programming workflows.

Rather than acting as a single rigid program, the OpenHands architecture is divided into modular components distributed across several repositories:

• Agent Canvas: The browser-based visual control center where developers start conversations with agents, review their actions, and configure automations.
• Software Agent SDK: A composable Python library that provides the core framework for constructing software agents, managing workspaces, and handling conversations and events.
• OpenHands Agent Server: A dedicated service providing REST and WebSocket Application Programming Interfaces (APIs). These interfaces allow the system to execute agents, interact with tools, and run workspaces across local or remote machines.
• Automation Server: A background engine responsible for scheduling automated tasks, receiving webhooks (automated event signals sent from other platforms), keeping track of run histories, and dispatching tasks to the agent runtime.
• Sandbox Server: A standalone control plane designed to set up and manage isolated computing environments (sandboxes) where the Agent Server can safely operate.

OpenHands works with its own built-in agent out of the box, but it is also designed to operate with a wide range of external coding agents. Compatible agents include Claude Code, Codex, Gemini CLI, Pi, and OpenCode, as well as any agent that communicates using the Agent-Client Protocol (ACP). The Agent-Client Protocol serves as a shared communication bridge, allowing different autonomous agent implementations to work directly with control centers like Agent Canvas.

The platform provides flexible hosting options. It can be installed locally on a developer workstation, set up on a dedicated machine like a Mac Mini, deployed within virtual machines (VMs) in private company networks, or executed inside Docker containers. For teams that prefer fully managed infrastructure without managing their own servers, the project also offers commercial solutions through OpenHands Cloud and OpenHands Enterprise.

What it can do

OpenHands turns coding agents into an always-on engineering assistant capable of performing both interactive programming tasks and background automations.

Key features and capabilities highlighted across the project documentation include:

• Interactive Coding Sessions: Developers can collaborate with agents through a web interface. The agent can examine repository files, create and edit code, execute commands in dedicated workspaces, and complete multi-step software tasks.
• Multi-Backend Switching: Users can connect an Agent Canvas frontend to several Agent Servers located in different environments. A developer can maintain their primary focus in the interface while switching between a personal local agent on a laptop and a shared remote server running automated tasks on cloud infrastructure.
• Automated Workflows and Scheduling: Using the Automation Server, teams can set up agents that run on regular schedules or respond to incoming webhook events triggered by third-party services.
• Third-Party Tool Integrations: OpenHands connects with commonly used development and productivity tools, including GitHub, Slack, Linear, Notion, and Datadog. For example, agents can automatically break down newly filed GitHub issues into structured engineering tasks, or generate progress reports and deliver them straight to a Slack channel.
• Model Context Protocol (MCP) and Custom Skills: The platform supports the Model Context Protocol, which enables agents to connect to external data sources and tools using an open standard. Users can further extend agent behavior using custom skills, hooks, plugins, packages, and repository-specific configuration settings.
• Custom Model Profiles: OpenHands allows users to bring their own language models. Developers can configure custom Large Language Model (LLM) profiles to connect the platform to their chosen model endpoints.
• Support for Diverse Development Tasks: According to the official documentation, OpenHands can be applied across numerous software development lifecycle (SDLC) activities, such as:
  • Vulnerability Remediation: Detecting and patching security weaknesses in software projects.
  • Automated Code Review: Evaluating code submissions and offering technical feedback.
  • Automated QA Testing: Generating and executing tests to verify that applications behave as intended.
  • Incident Triage: Diagnosing alerts and assisting engineering teams with technical investigations.
  • Dependency Upgrades: Checking project dependencies and managing routine library updates.
  • Legacy Modernization: Aiding in complex legacy system migrations, such as COBOL modernization projects and Apache Spark transitions.
  • Software Factories and Daily Routines: Supporting continuous automated development workflows as well as regular daily engineering tasks.

How to get started

OpenHands provides several installation and deployment options. According to the project documentation, running OpenHands on a dedicated machine or cloud server allows agents to continue working in the background even when a local laptop is closed.

Option 1: Without a Sandbox

This option runs the Agent Server directly on your local operating system without container isolation, meaning the agent will have direct access to your local filesystem.

Prerequisites: Node.js version 24 or later, and uv (a fast Python package manager and tool runner).

To install and run the full local stack globally:

npm install -g @openhands/agent-canvas
agent-canvas

If you prefer to run the components independently, you can split the startup process using dedicated command flags:

agent-canvas --frontend-only  # static frontend + ingress only
agent-canvas --backend-only   # agent server + automation backend + ingress only

Option 2: With a Docker Sandbox

Running OpenHands inside a Docker container isolates the agent and restricts its access to designated project folders.

Prerequisites: Docker Desktop (on macOS or Windows) or Docker Engine / Docker Desktop (on Linux), along with a directory containing the project repositories you wish to make available.

On macOS or Linux, start the container using the following commands:

export PROJECTS_PATH="$HOME/projects"  # directory containing your project folders
mkdir -p "$PROJECTS_PATH" "$HOME/.openhands"

docker run -it --rm \
  -p 127.0.0.1:8000:8000 \
  -e AGENT_CANVAS_ALLOW_LAN_SESSION_KEY=true \
  -v "$HOME/.openhands:/home/openhands/.openhands" \
  -v "${PROJECTS_PATH}:/projects" \
  ghcr.io/openhands/agent-canvas:1.27.1 # x-release-please-version

Under this setup, the agent can only interact with projects placed within the path specified by PROJECTS_PATH.

Option 3: With Multiple Docker Sandboxes

For concurrent agent workflows, OpenHands can launch each new conversation inside an individual Docker container with its own isolated Agent Server and tooling. The Canvas interface and outer server run on your host machine and route conversation tasks to their corresponding containers.

Prerequisites: Node.js version 24 or later, uv, and a running Docker daemon accessible to the user running the command.

On macOS or Linux, launch the multi-sandbox runtime with:

npm install -g @openhands/agent-canvas
OH_CONVERSATION_RUNTIME=docker agent-canvas

Each container mounts its conversation workspace and persisted state, ensuring that workspace files and historical records remain intact even if containers are replaced.

Option 4: From Source

Developers interested in modifying the platform or running the latest development build can run OpenHands directly from source. Like Option 1, this runs directly on the host machine with full access to the local filesystem.

Prerequisites: Node.js version 24 or later, npm, and uv.

To clone and launch the project:

git clone https://github.com/OpenHands/OpenHands.git
cd OpenHands
npm install
npm run dev

Accessing the Web Interface and Network Security

After starting OpenHands, the interface can be reached in a web browser at http://localhost:8000 (or http://localhost:8000/canvas when using the single Docker container).

By default, local npm and source development launchers bind strictly to the loopback interface (127.0.0.1), ensuring that auto-injected session keys are not exposed across the local network. If you need to make the server accessible across other network interfaces, you can pass --host 0.0.0.0 or set the OH_BIND_HOST environment variable, which disables automatic key injection and prompts for an API key in the web interface.

Pricing and requirements

OpenHands is an open-source software project. According to the metadata of the main GitHub repository, the OpenHands/OpenHands repository is licensed under the MIT license. The official documentation also notes that the ecosystem spans multiple public repositories, with each repository maintaining its own individual license file.

Beyond community self-hosting, the project includes commercial managed offerings:

• OpenHands Cloud: A commercial hosted service that provides execution infrastructure, collaboration capabilities, access controls, third-party integrations, usage tracking, and budget controls without requiring teams to host their own backends.
• OpenHands Enterprise: A commercial offering tailored for organizations that need licensed self-hosting or managed deployment environments backed by dedicated enterprise support.

Specific pricing and plan details are subject to the official OpenHands website and the OpenHands Enterprise page.

System Requirements

Depending on the chosen installation path, self-hosting OpenHands requires the following prerequisites:

• Node.js: Version 24 or later for running Agent Canvas via npm, multi-container setups, or building from source.
• Python Utilities: The uv package manager for executing and managing Python-based Agent Server components.
• Docker: Docker Desktop or Docker Engine when utilizing sandboxed containers or isolated multi-conversation environments.
• Language Model Credentials: API keys or endpoint access for the models you configure within your OpenHands LLM profiles.

Who it is for

OpenHands is built for a variety of technical users and organizations:

• Software Engineers: Developers who want an interactive, browser-accessible command center to collaborate with autonomous AI agents on daily programming, debugging, and code refactoring.
• Engineering Teams: Teams seeking to automate recurring development tasks, such as triaging incoming issues, conducting automated pull request reviews, and updating dependencies.
• DevOps and Site Reliability Specialists: Operators who want to connect observability platforms like Datadog to automated triage workflows that can analyze alerts and report findings to communication channels like Slack.
• Organizations with Strict Security Needs: Companies that need to keep their source code and agent execution within self-hosted infrastructure, utilizing virtual machines, private cloud servers, or Docker containers.
• Teams Handling Legacy Systems: Organizations carrying out complex codebase transitions, such as modernizing COBOL systems or executing Spark data migrations.
• Agent Developers and Researchers: Engineers looking to experiment with foundation models or build custom agents using standardized interfaces like the Agent-Client Protocol (ACP) and Model Context Protocol (MCP).

Alternatives

SWE-agent is an open-source system that enables language models to interact with software repositories to address engineering problems.

Aider is an open-source command-line tool that allows developers to pair program with artificial intelligence inside their local codebases.

Sources

• OpenHands GitHub Repository
• OpenHands Documentation
• SWE-agent GitHub Repository
• Aider GitHub Repository