openhands-agent-server

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 on this page — 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

openhands-agent-server on PyPI

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

Evidence: openhands_agent_server-1.42.1-py3-none-any.whl

Tags

More Application Frameworks packages

Further reading