Install, run, and secure the OpenHands Agent Server for remote agent execution.
The Agent Server package (openhands-agent-server) runs the OpenHands Software Agent SDK behind an HTTP and WebSocket API. Use it when another service, such as an Agent Canvas backend, needs to start conversations, stream events, and run file or command operations in a workspace without embedding the SDK directly in the same process.
When to Use It
Use the Agent Server when you need:
A backend process that clients can reach over HTTP/WebSocket.
A long-running service for conversations and workspace files.
A server API that can be protected with a session API key.
A clean boundary between your application backend and the agent runtime.
For a single local script, the standalone SDK is usually simpler. For a backend service, web UI, automation system, or Agent Canvas-style deployment, run an Agent Server and connect to it from the client service.
Install
Install the server package and its SDK dependencies into a Python environment:
If you are working from the SDK repository, run the module through uv instead:
uv run python -m openhands.agent_server --host 127.0.0.1 --port 8000
Check that the server is alive:
curl http://127.0.0.1:8000/health
The interactive API docs are available at:
http://127.0.0.1:8000/docs
If SESSION_API_KEY (legacy alias) or OH_SESSION_API_KEYS_* is already set in your shell, the server will require that key for /api/* requests. Unset those variables for unauthenticated local-only testing.
Secure the Server
By default, the Agent Server starts without API authentication. Before exposing it to another process, container, host, or user, set at least one session API key.
OH_SECRET_KEY encrypts sensitive values stored with conversations, including LLM API keys and secrets. Keep it stable across restarts. If it changes, previously encrypted values cannot be restored.
Connect From Python
Pass the server URL and API key to Workspace. The SDK sends the key as X-Session-API-Key and uses remote HTTP/WebSocket calls for workspace and conversation operations.
import osfrom pydantic import SecretStrfrom openhands.sdk import Conversation, LLM, Workspacefrom openhands.tools.preset.default import get_default_agentllm = LLM( model=os.environ.get("LLM_MODEL", "anthropic/claude-sonnet-4-5-20250929"), api_key=SecretStr(os.environ["LLM_API_KEY"]),)agent = get_default_agent(llm=llm, cli_mode=True) # disable browser-automation toolsworkspace = Workspace( host="http://127.0.0.1:8000", api_key=os.environ["OH_SESSION_API_KEYS_0"], working_dir="workspace/project",)conversation = Conversation(agent=agent, workspace=workspace)conversation.send_message("Create a NOTES.md file with three facts about this project.")conversation.run()conversation.close()
If the server was started without OH_SESSION_API_KEYS_0, remove the api_key=... argument.
Expose It Safely
If another service runs on the same machine, keep the server bound to 127.0.0.1 and let that service connect locally.If another host must connect to the server:
Set OH_SESSION_API_KEYS_0 and OH_SECRET_KEY.
Bind the server to a reachable interface, for example --host 0.0.0.0.
Put the server behind TLS, a private network, or a trusted reverse proxy.
Restrict firewall access to only the services that need it.
Configure CORS only for browser clients that must call the server directly.