OpenHands SDK: Build Agents That Run Terminal Commands

The OpenHands project logs 2,013 commits while powering a modular SDK for code-centric AI agents. This toolkit serves as the fundamental engine for the OpenHands CLI and OpenHands Cloud, offering a clean architecture for developers who need more than simple chat completions. Engineers can now construct production agents using set Python and REST APIs that handle everything from dependency updates to complex repository refactors.

The OpenHands Software Agent SDK enables both local machine workspaces and ephemeral execution environments via Docker or Kubernetes. Running tasks on a local setup differs fundamentally from deploying to remote servers for scalable, multi-agent operations.

This guide moves beyond theory to show concrete implementation steps, including the specific imports required to initialize an LLM model like gpt-5.5 within a conversation loop. By using this MIT-licensed framework, teams can build custom developer experiences that execute routine maintenance or substantial rewrites without manual intervention. This analysis provides the technical clarity needed to transition from experimental prompts to reliable, automated coding workflows.

The Role of the OpenHands SDK in Modern AI Agent Development

OpenHands SDK Definition: Python-First Agent Architecture

The OpenHands Software Agent SDK applies a collection of Python and REST APIs designed to define autonomous coding agents directly within source code. The software-agent-sdk repository is public and written primarily in Python 98.7%. Unlike static code completion tools, the framework implements a full agentic loop that integrates terminal command execution, web browsing, and GitHub pull request management into a single operational cycle. This architectural shift supports higher autonomy, allowing agents to resolve complex engineering tasks rather than generating isolated text snippets.

Skill definitions within this system extend beyond simple function calling to include flexible activation of public capabilities for modern package tooling, such as uv and deno. Evaluations of these agents occur across 13 challenging tasks, covering domains such as software engineering via SWE-Bench and web navigation through WebArena. The SDK scales from local execution to running thousands of agents simultaneously in cloud environments. The project achieved its milestone of over 64,000 stars within a rapid timeframe of just 18 months since its inception. The core codebase is released under the permissive MIT license, facilitating broad adoption and modification by the community.

Executing Agentic Loops: Terminal, Browsing, and Pull Requests

OpenHands executes full agentic loops by chaining terminal commands, web browsing, and pull request submissions into single autonomous workflows. The AI coding environment is shifting to cloud coding agents capable of full agentic loops, including terminal execution, web browsing, and pull request management. Basic coding assistants generate static text, yet this framework enables agents to interact dynamically with the development environment. Safety remains a priority through sandboxed Docker environments as agents receive powerful permissions. This architecture allows the agent to read a task, write code, run tests, browse documentation, and submit changes without human intervention.

Transitioning from local scripts to cloud coding agents uses strong containment mechanisms to prevent unauthorized system access. Restricting operations to ephemeral workspaces mitigates risks associated with autonomous command execution. The platform supports a composable SDK approach where agents are set in code, offering a programmatic control plane that differs from conversational-only interfaces. The broadened scope of AI coding agents means they perform complex actions like terminal command execution and GitHub PR creation, distinguishing them from tools that only offer code completion.

Builders enabling web browsing allow agents to access documentation and external resources as part of their workflow. The platform provides the flexibility to run locally on a user's machine or scale to thousands of agents in the cloud, a hybrid deployment model. Operational focus shifts toward defining precise workflows and using tools like TerminalTool, FileEditorTool, and TaskTrackerTool within the workspace boundaries.

Model-Agnostic SDKs vs Rigid Pre-Packaged Coding Solutions

Developers apply composable SDKs to define custom workflows rather than relying on rigid, pre-packaged solutions. This architectural shift enables the construction of model-agnostic agents capable of interfacing with various large language models, allowing users to switch between different LLMs without being locked into a specific vendor's system. Demand grows for model-agnostic platforms that prevent vendor lock-in. Proprietary systems bind users to specific ecosystems, whereas this approach allows operators to optimize costs by switching LLM providers dynamically. Flexibility extends to deployment, supporting hybrid models where agents run locally or scale to thousands of instances in the cloud.

The open-source nature of the project enables community contributions and transparency that closed-source alternatives lack. The core software is available under the MIT license, while enterprise offerings or components may have different licensing structures, distinguishing between community and commercial tiers. Market trends toward model-agnostic platforms reflect a preference for avoiding single-vendor dependency. Operators gain full control over the agentic loop, ensuring that critical development tasks remain portable across infrastructure changes. Portability maintains continuity in production environments where provider outages or policy shifts could otherwise halt operations entirely.

Inside the Agent Architecture: Workspaces, Tools, and Skills

OpenHands Agent Workspace and Public Skills Architecture

The agent workspace operates as an isolated execution environment where code operations occur, supporting both local directories and ephemeral containers. This separation keeps file edits and terminal commands contained within set boundaries, preventing unintended system-wide changes. Developers define this scope explicitly when initializing a conversation, anchoring the agent to a specific working directory or remote volume. Public capabilities extend beyond basic file editing through an extensions marketplace, which supplies pre-built skills for modern tooling. Enabling specific context configurations allows agents to automatically detect repository markers and apply appropriate package management logic. Such a mechanism reduces boilerplate configuration by dynamically loading proficiency for various ecosystems based on detected files. Recent data suggests the project has surpassed 65,000 GitHub stars.

Tension exists between immediate skill availability and environment purity. Loading public skills simplifies onboarding but introduces external dependencies into the agent's runtime context, potentially conflicting with strict security policies in regulated enterprises. Builders must weigh the convenience of auto-detected behaviors against the need for fully auditable, static toolsets in production pipelines.

Activating Public Skills with AgentContext and Package Markers

Enabling the public skills flag grants agents immediate access to specialized logic for modern package managers. This configuration triggers an automatic scan for specific file markers within the target workspace. Upon detection, the agent retrieves the execution patterns from the marketplace without requiring manual tool definition. Builders should deploy this feature when managing repositories that rely on complex or frequently updated dependency chains. The SDK's composable architecture supports this flexible loading, allowing developers to construct custom agentic workflows rather than depending on rigid, pre-packaged solutions. Agents then adhere to current best practices set by the underlying package system.

The SDK automatically picks up current package-management guidance for repositories that use these markers. Engineers can reference the standalone SDK demonstrations for a minimal implementation example. Thorough API references and further architectural details remain available in the official documentation. Proper activation reduces the need for explicit tool declarations in the agent definition block.

Validating Tool Initialization and Skill Loading Paths

This procedural check ensures the SDK retrieves the correct execution patterns from the marketplace rather than relying on generic command execution. Explicitly testing this loading path isolates configuration errors from model reasoning failures. Documentation for these verification steps resides in the guides section, which details core concepts for tools and workspaces.

Deploying Agents: Local Docker Setup Versus Remote Server Execution

Local Docker Setup vs Remote Server Execution Definitions

Local execution binds the Agent lifecycle to the host machine, whereas remote deployment decouples runtime persistence from the developer's local environment. The SDK allows creation of agents using specific tools such as TerminalTool, FileEditorTool, and TaskTrackerTool to interact with codebases. In a local configuration, these tools operate within the user's immediate filesystem, limiting concurrency and risking host contamination if sandboxing is not strictly enforced. Conversely, deploying on cloud servers enables agents to continue running tasks even when local laptops are shut down, providing a persistent execution environment.

The factory `Workspace(…)` resolves to local when only `working_dir` is provided and to remote when host parameters are present, ensuring the agent code remains unchanged across environments. This architectural flexibility supports a shift toward cloud coding agents where the primary value proposition is autonomous execution rather than local assistance.

Builders must recognize that local development often masks latency issues inherent in networked tool calls, which become apparent only upon scaling to remote clusters. While local setups offer rapid iteration for debugging Conversation flows, production workloads require the isolation of sandboxed Docker environments to safely execute terminal commands. The added complexity of managing remote state and securing API keys outside the local perimeter is the price of scale.

Deploying Agents with TerminalTool and FileEditorTool Locally

Local installation begins by executing `make build` to configure workspace dependencies and pre-commit hooks. Developers define an Agent instance using `TerminalTool` and `FileEditorTool` while supplying API keys via environment variables. The provided reference implementation configures the LLM model to `gpt-5.5` for code generation tasks. This setup uses sandboxed execution within Docker containers to isolate terminal commands from the host system.

The table contrasts local constraints with cloud capabilities found in hybrid deployment models. A critical limitation involves resource contention; running multiple heavy agents locally saturates CPU threads, whereas remote clusters distribute this load. Consequently, local testing validates logic quickly but fails to reproduce concurrency bugs present in production. Engineers should restrict local runs to single-agent validation before scaling to cloud coding agents for extensive refactors. This approach ensures the local environment remains stable while verifying that Tool interactions function correctly prior to distributed execution.

Local Docker Versus Remote Server Scaling Decision Framework

Choose remote server execution when agent tasks must persist beyond local laptop uptime or require third-party triggers from Slack and GitHub. Local Docker setups bind Agent lifecycles to the developer's machine, creating a hard dependency on host availability and network stability. In contrast, cloud deployments allow agents to continue running indefinitely, supporting long-duration engineering loops that exceed typical work hours.

The decision matrix below contrasts operational characteristics for single-developer versus enterprise-scale requirements:

Architecturally, the SDK scales from single local instances to thousands of concurrent agents in cloud environments, enabling parallel processing impossible on restricted local hardware. This shift supports the industry transition toward cloud coding agents that execute full agentic loops without human supervision. However, remote scaling introduces latency in file I/O operations compared to direct local filesystem access via TerminalTool.

Operators must weigh the convenience of local debugging against the reliability of remote persistence. While local execution offers immediate feedback for tool development, it fails to support the asynchronous workflows required for automated maintenance tasks. The limitation is clear: local environments cannot sustain the Conversation state required for multi-day refactoring projects if the host device disconnects. Enterprise procurement now favors remote configurations that guarantee service continuity regardless of individual developer connectivity status.

Building and Extending AI Agents with Custom Skills and Plugins

Defining the OpenHands SDK Import Structure and Core Classes

Production agents begin by importing LLM, Agent, Conversation, and Tool from `openhands.sdk`. This specific import sequence establishes the programmatic control plane necessary to define agents directly within code, separating the framework from conversational-only interfaces found in consumer-grade AI coding tools. The structure supports a composable Python library approach where developers instantiate capabilities like the TerminalTool, FileEditorTool, and TaskTrackerTool alongside a configured language model.

Scaling from local execution to running thousands of agents simultaneously in cloud environments happens without altering core agent definition logic. Local setups offer rapid iteration, yet the SDK architecture explicitly separates workspace implementations to support ephemeral Docker or Kubernetes environments for production safety. The initial import statement acts as the single point of abstraction enabling portability across diverse integration scenarios. Developers accessing the composable Python library maintain unchanged agent code whether the target workspace resolves to a local directory or a remote host.

Implementing GitHub Workflows and Remote Agent Server Scenarios

The `examples/` directory provides concrete templates for GitHub Workflows and remote server deployment. Execution shifts from local laptops to persistent cloud environments where agents operate independently.

Developers configure WebSocket connections to maintain stateful sessions even when local devices disconnect. This architecture supports long-running engineering tasks that exceed typical interactive session limits. The repository documents client-server patterns enabling third-party services to trigger coding agents automatically. Such integration allows CI/CD pipelines to initiate refactors or dependency updates without manual intervention.

Immediate local feedback competes with the reliability of remote orchestration. Local execution offers low latency but fails if the host machine sleeps or loses network access. Remote servers provide persistent execution but introduce complexity in managing network boundaries and secrets.

The cost structure favors running agents on dedicated infrastructure rather than proprietary cloud-only solutions. Teams gain control over runtime environments while avoiding vendor lock-in for compute resources. Adopting this model requires managing server health and scaling logic that local-only tools abstract away. Builders must implement monitoring for agent lifecycles that desktop applications typically handle implicitly. This constraint defines the boundary between prototype scripts and production-grade autonomous systems.

Checklist for Resolving Workspace Dependencies via Make Build

Execute `make build` to install workspace dependencies and configure pre-commit hooks before agent initialization. This single command resolves local pathing errors that frequently interrupt agent workspace operations during the first run. Developers building custom interfaces must complete this step to guarantee file system access matches sandbox expectations. The repository history spans 2,013 commits, indicating a mature codebase where dependency versions shift often without explicit version pinning in every example. Skipping this validation often leads to missing TerminalTool binaries or failed FileEditorTool permissions.

Operators scaling to thousands of agents in the cloud require this local fidelity to prevent remote deployment failures. A missing hook configuration here manifests as silent permission denials when the Agent attempts to write to disk later. Mirroring the local environment to openhands-workspace constraints reduces drift between development and production execution contexts. This alignment is mandatory for relying on automatic package management detection for markers like `uv.lock`.

References

• The OpenHands Software Agent SDK: A Composable and Extensible
• OpenHands - Features, Pricing & Review [AI Agent (Coding)]
• OpenCode 2026: Setup Guide for the Top Open-Source AI