---
id: openhands-agent-server
version: "1.42.1"
license: unclear
license_treatment: unclear
maintenance: active
---

# openhands-agent-server — OpenHands Agent Server - REST/WebSocket interface for OpenHands AI Agent

License: unclear · Maintenance: active · Downloads: 1.4M/mo

## What it is and what it does

OpenHands Agent Server is a Python package that exposes AI agents capable of working with code through REST and WebSocket APIs. It builds on the openhands-sdk to let you run agents remotely, either on the local machine or in ephemeral Docker/Kubernetes workspaces. The server handles agent lifecycle, tool execution (file editing, terminal commands, task tracking), and workspace management.

You use it to automate code-related tasks—writing documentation, updating dependencies, refactoring—by sending natural-language instructions to an agent that can read files, run commands, and track progress. The package includes fastapi for the HTTP layer, sqlalchemy for state persistence, and integrates with openai for LLM inference. It's designed both as a standalone service and as the backbone for higher-level tools like the OpenHands CLI and Cloud platform.

Use it for:

- Run an AI agent as a remote service to handle one-off code tasks like generating README files or documentation
- Automate routine maintenance workflows such as dependency updates across multiple repositories
- Execute complex multi-agent refactoring or rewrite tasks in isolated, ephemeral Docker containers
- Build custom developer tools or CI/CD integrations that delegate code work to AI agents via REST
- Deploy agents in Kubernetes for scalable, on-demand code automation in production environments

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

Provides a REST and WebSocket API server for running OpenHands AI agents that can work with code, either locally or in ephemeral containerized workspaces.

Yes, if you need a production-ready agent server for code automation. The package is actively maintained, has low install friction, and sits in the top 5000 PyPI packages by download volume. The main caveat is the unclear license—verify it matches your use case before committing. Requires Python 3.12 or later.

## Install

pip install openhands-agent-server
uv add openhands-agent-server
poetry add openhands-agent-server

## Installing openhands-agent-server

Before you install: Low friction: pure Python wheel with 11 runtime dependencies including fastapi, sqlalchemy, and docker. Active maintenance with a release 2 days old and recent commits. Requires Python 3.12 or later.

License in practice: License status is unclear—no SPDX identifier or raw license text is available in the package metadata. Verify the actual license before using in proprietary or restricted contexts.

Quickstart:

pip install openhands-agent-server

from openhands.sdk import LLM, Agent, Conversation, Tool
from openhands.tools.terminal import TerminalTool

llm = LLM(model="gpt-5.5", api_key="your-key")
agent = Agent(llm=llm, tools=[Tool(name=TerminalTool.name)])
conversation = Conversation(agent=agent, workspace=".")
conversation.send_message("List files in the current directory")
conversation.run()

Requires Python 3.12 or later. Docker is a runtime dependency if you plan to use containerized workspaces.

Verify before relying:

- Whether the package can be used standalone or requires additional OpenHands components to function
- Specific LLM models and API providers supported beyond the example
- Performance characteristics and scalability limits for concurrent agent sessions
- Whether public skills marketplace requires network access or authentication

## Package facts

- License: not declared (unclear)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 1.4M/month (top 5,000 on PyPI)
- Known vulnerabilities: none known

## Tags

ai agent server for code tasks, remote agent execution api, code-working ai agent framework, agent server rest websocket, openhands agent deployment, automated code maintenance agent, ai agent workspace server, ai-agent, code-automation, agent-server

[View on SkillFed](https://skillfed.io/packages/openhands-agent-server) · [View on PyPI](https://pypi.org/project/openhands-agent-server/)