Remote Agent Server

Run agents on remote servers with isolated workspaces for production deployments.

Remote Agent Servers package the Software Agent SDK into containers you can deploy anywhere—Kubernetes, VMs, on-prem, or any cloud—with strong isolation. The remote path uses the exact same SDK API as local; switching is just changing the workspace argument.

For technical architecture details (endpoints, authentication, component design), see the Agent Server Package section in the Architecture Overview.

Switching from Local to Remote

Your conversation code stays the same—just swap the workspace:

# Local → Docker
conversation = Conversation(agent=agent, workspace=os.getcwd())  
from openhands.workspace import DockerWorkspace  
with DockerWorkspace( 
    server_image="ghcr.io/openhands/agent-server:latest-python", 
) as workspace: 
    conversation = Conversation(agent=agent, workspace=workspace)  

Or connect to a hosted runtime API:

# Local → Remote API
conversation = Conversation(agent=agent, workspace=os.getcwd())  
from openhands.workspace import APIRemoteWorkspace  
with APIRemoteWorkspace( 
    runtime_api_url="https://runtime.eval.all-hands.dev",  
    runtime_api_key="YOUR_API_KEY", 
    server_image="ghcr.io/openhands/agent-server:latest-python", 
) as workspace: 
    conversation = Conversation(agent=agent, workspace=workspace)  

Or use OpenHands Cloud for fully managed sandboxes:

# Local → OpenHands Cloud
conversation = Conversation(agent=agent, workspace=os.getcwd())  
from openhands.workspace import OpenHandsCloudWorkspace  
with OpenHandsCloudWorkspace( 
    cloud_api_url="https://app.all-hands.dev",  
    cloud_api_key="YOUR_CLOUD_API_KEY", 
) as workspace: 
    conversation = Conversation(agent=agent, workspace=workspace)  

Workspace Types

Workspace	What It Does	Best For
DockerWorkspace	Spawns a Docker container with agent server	Local development with isolation, self-hosted deployments
APIRemoteWorkspace	Connects to a runtime API that provisions sandboxes	Custom runtime environments, CI/CD pipelines
OpenHandsCloudWorkspace	Connects to OpenHands Cloud for managed sandboxes	Production use, no infrastructure management
Local Server	Runs agent server in-process	Testing, development without Docker

How It Works

When you use a remote workspace, the SDK automatically:

1. Starts or connects to an agent server inside the workspace environment
2. Creates a RemoteConversation that communicates via HTTP/WebSocket
3. Streams events in real-time through WebSocket callbacks
4. Handles cleanup when the context manager exits

with DockerWorkspace(server_image="ghcr.io/openhands/agent-server:latest-python") as workspace:
    # Workspace spawns container with agent server
    
    conversation = Conversation(agent=agent, workspace=workspace, callbacks=[on_event])
    # SDK creates RemoteConversation, connects via WebSocket
    
    conversation.send_message("Create a hello.py file")
    conversation.run()
    # Agent executes inside container, events stream to callbacks
    
# Container automatically cleaned up

File and Command Operations

Workspaces provide file and command operations that work identically whether local or remote:

# Execute commands in the workspace
result = workspace.execute_command("ls -la")
print(result.stdout)

# Upload/download files
workspace.file_upload("local/file.txt", "/workspace/file.txt")
workspace.file_download("/workspace/output.txt", "local/output.txt")

These operations are proxied through the agent server API, keeping your code environment-agnostic.

Deployment Options

Self-Hosted (Docker)

Use DockerWorkspace to run agent servers in containers on your own infrastructure:

from openhands.workspace import DockerWorkspace

with DockerWorkspace(
    server_image="ghcr.io/openhands/agent-server:latest-python",
    host_port=8010,
) as workspace:
    conversation = Conversation(agent=agent, workspace=workspace)

See Docker Sandbox Guide for details.

Runtime API

Use APIRemoteWorkspace to connect to a runtime API service that provisions sandboxes:

from openhands.workspace import APIRemoteWorkspace

with APIRemoteWorkspace(
    runtime_api_url="https://runtime.eval.all-hands.dev",
    runtime_api_key=os.getenv("RUNTIME_API_KEY"),
    server_image="ghcr.io/openhands/agent-server:latest-python",
) as workspace:
    conversation = Conversation(agent=agent, workspace=workspace)

See API Sandbox Guide for details.

OpenHands Cloud

Use OpenHandsCloudWorkspace for fully managed sandbox environments:

from openhands.workspace import OpenHandsCloudWorkspace

with OpenHandsCloudWorkspace(
    cloud_api_url="https://app.all-hands.dev",
    cloud_api_key=os.getenv("OPENHANDS_CLOUD_API_KEY"),
) as workspace:
    conversation = Conversation(agent=agent, workspace=workspace)

See Cloud Workspace Guide for details.

Next Steps

Deployment Guides:

• Local Agent Server - Run server in-process for development
• Docker Sandbox - Isolated Docker containers
• API Sandbox - Runtime API integration
• Cloud Workspace - OpenHands Cloud managed sandboxes

Architecture:

• Architecture Overview - Technical details, endpoints, authentication
• Workspace Architecture - Workspace abstraction and implementations