diff --git a/sdk/arch/agent-server.mdx b/sdk/arch/agent-server.mdx
deleted file mode 100644
index 8ad7663c..00000000
--- a/sdk/arch/agent-server.mdx
+++ /dev/null
@@ -1,534 +0,0 @@
----
-title: Agent Server Package
-description: HTTP API server for remote agent execution with workspace isolation, container orchestration, and multi-user support.
----
-
-The Agent Server package (`openhands.agent_server`) provides an HTTP API server for remote agent execution. It enables building multi-user systems, SaaS products, and distributed agent platforms.
-
-**Source**: [`openhands/agent_server/`](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands/agent_server)
-
-## Purpose
-
-The Agent Server enables:
-- **Remote execution**: Clients interact with agents via HTTP API
-- **Multi-user isolation**: Each user gets isolated workspace
-- **Container orchestration**: Manages Docker containers for workspaces
-- **Centralized management**: Monitor and control all agents
-- **Scalability**: Horizontal scaling with multiple servers
-
-## Architecture Overview
-
-```mermaid
-graph TB
-    Client[Web/Mobile Client] -->|HTTPS| API[FastAPI Server]
-    
-    API --> Auth[Authentication]
-    API --> Router[API Router]
-    
-    Router --> WS[Workspace Manager]
-    Router --> Conv[Conversation Handler]
-    
-    WS --> Docker[Docker Manager]
-    Docker --> C1[Container 1<br/>User A]
-    Docker --> C2[Container 2<br/>User B]
-    Docker --> C3[Container 3<br/>User C]
-    
-    Conv --> Agent[Software Agent SDK]
-    Agent --> C1
-    Agent --> C2
-    Agent --> C3
-    
-    style Client fill:#e1f5fe
-    style API fill:#fff3e0
-    style WS fill:#e8f5e8
-    style Docker fill:#f3e5f5
-    style Agent fill:#fce4ec
-```
-
-### Key Components
-
-**1. FastAPI Server**
-- HTTP REST API endpoints
-- Authentication and authorization
-- Request validation
-- WebSocket support for streaming
-
-**2. Workspace Manager**
-- Creates and manages Docker containers
-- Isolates workspaces per user
-- Handles container lifecycle
-- Manages resource limits
-
-**3. Conversation Handler**
-- Routes requests to appropriate workspace
-- Manages conversation state
-- Handles concurrent requests
-- Supports streaming responses
-
-**4. Docker Manager**
-- Interfaces with Docker daemon
-- Builds and pulls images
-- Creates and destroys containers
-- Monitors container health
-
-## Design Decisions
-
-### Why HTTP API?
-
-Alternative approaches considered:
-- **gRPC**: More efficient but harder for web clients
-- **WebSockets only**: Good for streaming but not RESTful
-- **HTTP + WebSockets**: Best of both worlds
-
-**Decision**: HTTP REST for operations, WebSockets for streaming
-- ✅ Works from any client (web, mobile, CLI)
-- ✅ Easy to debug (curl, Postman)
-- ✅ Standard authentication (API keys, OAuth)
-- ✅ Streaming where needed
-
-### Why Container Per User?
-
-Alternative approaches:
-- **Shared container**: Multiple users in one container
-- **Container per session**: New container each conversation
-- **Container per user**: One container per user (chosen)
-
-**Decision**: Container per user
-- ✅ Strong isolation between users
-- ✅ Persistent workspace across sessions
-- ✅ Better resource management
-- ⚠️ More containers, but worth it for isolation
-
-### Why FastAPI?
-
-Alternative frameworks:
-- **Flask**: Simpler but less type-safe
-- **Django**: Too heavyweight
-- **FastAPI**: Modern, fast, type-safe (chosen)
-
-**Decision**: FastAPI
-- ✅ Automatic API documentation (OpenAPI)
-- ✅ Type validation with Pydantic
-- ✅ Async support for performance
-- ✅ WebSocket support built-in
-
-## API Design
-
-### Key Endpoints
-
-**Workspace Management**
-```
-POST   /workspaces              Create new workspace
-GET    /workspaces/{id}         Get workspace info
-DELETE /workspaces/{id}         Delete workspace
-POST   /workspaces/{id}/execute Execute command
-```
-
-**Conversation Management**
-```
-POST   /conversations                Create conversation
-GET    /conversations/{id}           Get conversation
-POST   /conversations/{id}/messages  Send message
-GET    /conversations/{id}/stream    Stream responses (WebSocket)
-```
-
-**Health & Monitoring**
-```
-GET    /health                   Server health check
-GET    /metrics                  Prometheus metrics
-```
-
-### Authentication
-
-**API Key Authentication**
-```bash
-curl -H "Authorization: Bearer YOUR_API_KEY" \
-     https://agent-server.example.com/conversations
-```
-
-**Per-user workspace isolation**
-- API key → user ID mapping
-- Each user gets separate workspace
-- Users can't access each other's workspaces
-
-### Streaming Responses
-
-**WebSocket for real-time updates**
-```python
-async with websocket_connect(url) as ws:
-    # Send message
-    await ws.send_json({"message": "Hello"})
-    
-    # Receive events
-    async for event in ws:
-        if event["type"] == "message":
-            print(event["content"])
-```
-
-**Why streaming?**
-- Real-time feedback to users
-- Show agent thinking process
-- Better UX for long-running tasks
-
-## Deployment Models
-
-### 1. Local Development
-
-Run server locally for testing:
-```bash
-# Start server
-openhands-agent-server --port 8000
-
-# Or with Docker
-docker run -p 8000:8000 \
-  -v /var/run/docker.sock:/var/run/docker.sock \
-  ghcr.io/all-hands-ai/agent-server:latest
-```
-
-**Use case**: Development and testing
-
-### 2. Single-Server Deployment
-
-Deploy on one server (VPS, EC2, etc.):
-```bash
-# Install
-pip install openhands-agent-server
-
-# Run with systemd/supervisor
-openhands-agent-server \
-  --host 0.0.0.0 \
-  --port 8000 \
-  --workers 4
-```
-
-**Use case**: Small deployments, prototypes, MVPs
-
-### 3. Multi-Server Deployment
-
-Scale horizontally with load balancer:
-```
-                 Load Balancer
-                       |
-        +-------------+-------------+
-        |             |             |
-   Server 1      Server 2      Server 3
-   (Agents)      (Agents)      (Agents)
-        |             |             |
-        +-------------+-------------+
-                       |
-              Shared State Store
-           (Database, Redis, etc.)
-```
-
-**Use case**: Production SaaS, high traffic, need redundancy
-
-### 4. Kubernetes Deployment
-
-Container orchestration with Kubernetes:
-```yaml
-apiVersion: apps/v1
-kind: Deployment
-metadata:
-  name: agent-server
-spec:
-  replicas: 3
-  template:
-    spec:
-      containers:
-      - name: agent-server
-        image: ghcr.io/all-hands-ai/agent-server:latest
-        ports:
-        - containerPort: 8000
-```
-
-**Use case**: Enterprise deployments, auto-scaling, high availability
-
-## Resource Management
-
-### Container Limits
-
-Set per-workspace resource limits:
-```python
-# In server configuration
-WORKSPACE_CONFIG = {
-    "resource_limits": {
-        "memory": "2g",      # 2GB RAM
-        "cpus": "2",         # 2 CPU cores
-        "disk": "10g"        # 10GB disk
-    },
-    "timeout": 300,          # 5 min timeout
-}
-```
-
-**Why limit resources?**
-- Prevent one user from consuming all resources
-- Fair usage across users
-- Protect server from runaway processes
-- Cost control
-
-### Cleanup & Garbage Collection
-
-**Container lifecycle**:
-- Containers created on first use
-- Kept alive between requests (warm)
-- Cleaned up after inactivity timeout
-- Force cleanup on server shutdown
-
-**Storage management**:
-- Old workspaces deleted automatically
-- Disk usage monitored
-- Alerts when approaching limits
-
-## Security Considerations
-
-### Multi-Tenant Isolation
-
-**Container isolation**:
-- Each user gets separate container
-- Containers can't communicate
-- Network isolation (optional)
-- File system isolation
-
-**API isolation**:
-- API keys mapped to users
-- Users can only access their workspaces
-- Server validates all permissions
-
-### Input Validation
-
-**Server validates**:
-- API request schemas
-- Command injection attempts
-- Path traversal attempts
-- File size limits
-
-**Defense in depth**:
-- API validation
-- Container validation
-- Docker security features
-- OS-level security
-
-### Network Security
-
-**Best practices**:
-- HTTPS only (TLS certificates)
-- Firewall rules (only port 443/8000)
-- Rate limiting
-- DDoS protection
-
-**Container networking**:
-```python
-# Disable network for workspace
-WORKSPACE_CONFIG = {
-    "network_mode": "none"  # No network access
-}
-
-# Or allow specific hosts
-WORKSPACE_CONFIG = {
-    "allowed_hosts": ["api.example.com"]
-}
-```
-
-## Monitoring & Observability
-
-### Health Checks
-
-```bash
-# Simple health check
-curl https://agent-server.example.com/health
-
-# Response
-{
-  "status": "healthy",
-  "docker": "connected",
-  "workspaces": 15,
-  "uptime": 86400
-}
-```
-
-### Metrics
-
-**Prometheus metrics**:
-- Request count and latency
-- Active workspaces
-- Container resource usage
-- Error rates
-
-**Logging**:
-- Structured JSON logs
-- Per-request tracing
-- Workspace events
-- Error tracking
-
-### Alerting
-
-**Alert on**:
-- Server down
-- High error rate
-- Resource exhaustion
-- Container failures
-
-## Client SDK
-
-Python SDK for interacting with Agent Server:
-
-```python
-from openhands.client import AgentServerClient
-
-client = AgentServerClient(
-    url="https://agent-server.example.com",
-    api_key="your-api-key"
-)
-
-# Create conversation
-conversation = client.create_conversation()
-
-# Send message
-response = client.send_message(
-    conversation_id=conversation.id,
-    message="Hello, agent!"
-)
-
-# Stream responses
-for event in client.stream_conversation(conversation.id):
-    if event.type == "message":
-        print(event.content)
-```
-
-**Client handles**:
-- Authentication
-- Request/response serialization
-- Error handling
-- Streaming
-- Retries
-
-## Cost Considerations
-
-### Server Costs
-
-**Compute**: CPU and memory for containers
-- Each active workspace = 1 container
-- Typically 1-2 GB RAM per workspace
-- 0.5-1 CPU core per workspace
-
-**Storage**: Workspace files and conversation state
-- ~1-10 GB per workspace (depends on usage)
-- Conversation history in database
-
-**Network**: API requests and responses
-- Minimal (mostly text)
-- Streaming adds bandwidth
-
-### Cost Optimization
-
-**1. Idle timeout**: Shutdown containers after inactivity
-```python
-WORKSPACE_CONFIG = {
-    "idle_timeout": 3600  # 1 hour
-}
-```
-
-**2. Resource limits**: Don't over-provision
-```python
-WORKSPACE_CONFIG = {
-    "resource_limits": {
-        "memory": "1g",    # Smaller limit
-        "cpus": "0.5"      # Fractional CPU
-    }
-}
-```
-
-**3. Shared resources**: Use single server for multiple low-traffic apps
-
-**4. Auto-scaling**: Scale servers based on demand
-
-## When to Use Agent Server
-
-### Use Agent Server When:
-
-✅ **Multi-user system**: Web app with many users  
-✅ **Remote clients**: Mobile app, web frontend  
-✅ **Centralized management**: Need to monitor all agents  
-✅ **Workspace isolation**: Users shouldn't interfere  
-✅ **SaaS product**: Building agent-as-a-service  
-✅ **Scaling**: Need to handle concurrent users
-
-**Examples**:
-- Chatbot platforms
-- Code assistant web apps
-- Agent marketplaces
-- Enterprise agent deployments
-
-### Use Standalone SDK When:
-
-✅ **Single-user**: Personal tool or script  
-✅ **Local execution**: Running on your machine  
-✅ **Full control**: Need programmatic access  
-✅ **Simpler deployment**: No server management  
-✅ **Lower latency**: No network overhead
-
-**Examples**:
-- CLI tools
-- Automation scripts
-- Local development
-- Desktop applications
-
-### Hybrid Approach
-
-Use SDK locally but RemoteAPIWorkspace for execution:
-- Agent logic in your Python code
-- Execution happens on remote server
-- Best of both worlds
-
-## Building Custom Agent Server
-
-The server is extensible for custom needs:
-
-**Custom authentication**:
-```python
-from openhands.agent_server import AgentServer
-
-class CustomAgentServer(AgentServer):
-    async def authenticate(self, request):
-        # Custom auth logic
-        return await oauth_verify(request)
-```
-
-**Custom workspace configuration**:
-```python
-server = AgentServer(
-    workspace_factory=lambda user: DockerWorkspace(
-        image=f"custom-image-{user.tier}",
-        resource_limits=user.resource_limits
-    )
-)
-```
-
-**Custom middleware**:
-```python
-@server.middleware
-async def logging_middleware(request, call_next):
-    # Custom logging
-    response = await call_next(request)
-    return response
-```
-
-## Next Steps
-
-### For Usage Examples
-
-- [Local Agent Server](/sdk/guides/agent-server/local-server) - Run locally
-- [Docker Sandboxed Server](/sdk/guides/agent-server/docker-sandbox) - Docker setup
-- [API Sandboxed Server](/sdk/guides/agent-server/api-sandbox) - Remote API
-- [Remote Agent Server Overview](/sdk/guides/agent-server/overview) - All options
-
-### For Related Architecture
-
-- [Workspace Architecture](/sdk/arch/workspace) - RemoteAPIWorkspace details
-- [SDK Architecture](/sdk/arch/sdk) - Core framework
-- [Architecture Overview](/sdk/arch/overview) - System design
-
-### For Implementation Details
-
-- [`openhands/agent_server/`](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands/agent_server) - Server source
-- [`examples/`](https://github.com/OpenHands/software-agent-sdk/tree/main/examples) - Working examples
diff --git a/sdk/arch/overview.mdx b/sdk/arch/overview.mdx
index a1dfdf64..09a5fba1 100644
--- a/sdk/arch/overview.mdx
+++ b/sdk/arch/overview.mdx
@@ -194,17 +194,94 @@ For full list of implemented workspaces, see the [source code](https://github.co
 
 **Purpose:** FastAPI-based HTTP/WebSocket server for remote agent execution.
 
-**Features:**
-- REST API & WebSocket endpoints for conversations, bash, files, events, desktop, and VSCode
-- Service management with isolated per-user sessions
-- API key authentication and health checking
+**Source:** [`openhands-agent-server/`](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-agent-server)
 
-**Deployment:** Runs inside containers (via `DockerWorkspace`) or as standalone process (connected via `RemoteWorkspace`).
+**Deployment:** Runs inside containers (via `DockerWorkspace`) or as standalone process (connected via `RemoteWorkspace`). The agent server itself does not manage containers—containerization and lifecycle are handled by [workspace implementations](/sdk/arch/workspace).
 
 **Use Cases:** Multi-user web apps, SaaS products, distributed systems.
 
+#### Architecture
+
+```mermaid
+%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 28, "rankSpacing": 40}} }%%
+flowchart TB
+    Client[Client / SDK] -->|HTTP/WS| API[FastAPI App]
+
+    subgraph Routers["Routers under /api"]
+        Conv[conversations]
+        Events[events]
+        Bash[bash]
+        File[file]
+        Git[git]
+        Tools[tools]
+    end
+
+    WS["WebSocket under /sockets"]
+
+    API --> Routers
+    API --> WS
+
+    subgraph Services[Services]
+        ConvSvc[ConversationService]
+        EventSvc[EventService]
+    end
+
+    Routers --> ConvSvc
+    Routers --> EventSvc
+    WS --> EventSvc
+
+    classDef primary fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px
+    classDef secondary fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px
+    classDef tertiary fill:#fff4df,stroke:#b7791f,stroke-width:2px
+
+    class API primary
+    class Routers,WS secondary
+    class Services tertiary
+```
+
+#### Key Components
+
+| Component | Purpose | Source |
+|-----------|---------|--------|
+| **FastAPI App** | Main application with lifespan management | [api.py](https://github.com/OpenHands/software-agent-sdk/blob/HEAD/openhands-agent-server/openhands/agent_server/api.py) |
+| **ConversationService** | Manages conversation state and execution | [conversation_service.py](https://github.com/OpenHands/software-agent-sdk/blob/HEAD/openhands-agent-server/openhands/agent_server/conversation_service.py) |
+| **EventService** | Handles event storage and streaming | [event_service.py](https://github.com/OpenHands/software-agent-sdk/blob/HEAD/openhands-agent-server/openhands/agent_server/event_service.py) |
+| **Request/Response Models** | Pydantic models for API payloads | [models.py](https://github.com/OpenHands/software-agent-sdk/blob/HEAD/openhands-agent-server/openhands/agent_server/models.py) |
+
+#### API Endpoints
+
+**REST Endpoints (`/api`):**
+
+| Router | Endpoint | Description |
+|--------|----------|-------------|
+| **Conversations** | `POST /api/conversations` | Start new conversation |
+| | `POST /api/conversations/{id}/run` | Run agent loop |
+| | `POST /api/conversations/{id}/events` | Send message (optionally with `run: true`) |
+| **Events** | `GET /api/conversations/{id}/events/search` | List events |
+| | `GET /api/conversations/{id}/events/{event_id}` | Get specific event |
+| **Bash** | `POST /api/bash/start_bash_command` | Start background command |
+| | `GET /api/bash/bash_events/search` | List bash events |
+| **Files** | `POST /api/file/upload/{path}` | Upload file |
+| | `GET /api/file/download/{path}` | Download file |
+| **Tools** | `GET /api/tools/` | List registered tools |
+| **Server** | `GET /server_info` | Get uptime and idle time |
+
+**WebSocket Endpoints (`/sockets`):**
+
+| Endpoint | Description |
+|----------|-------------|
+| `/sockets/events/{conversation_id}` | Stream conversation events |
+| `/sockets/bash-events` | Stream bash command events |
+
+#### Authentication
+
+| Method | Authentication | Source |
+|--------|---------------|--------|
+| **HTTP** | `X-Session-API-Key` header | [dependencies.py](https://github.com/OpenHands/software-agent-sdk/blob/HEAD/openhands-agent-server/openhands/agent_server/dependencies.py) |
+| **WebSocket** | `session_api_key` query parameter | [sockets.py](https://github.com/OpenHands/software-agent-sdk/blob/HEAD/openhands-agent-server/openhands/agent_server/sockets.py) |
+
 <Note>
-For implementation details, see the [source code](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-agent-server).
+For practical usage guides on deploying and connecting to agent servers, see the [Remote Agent Server Guide](/sdk/guides/agent-server/overview).
 </Note>
 
 ## How Components Work Together
diff --git a/sdk/arch/sdk.mdx b/sdk/arch/sdk.mdx
index a237f36a..58e66b30 100644
--- a/sdk/arch/sdk.mdx
+++ b/sdk/arch/sdk.mdx
@@ -455,7 +455,7 @@ Everything uses Pydantic models:
 
 - [Tool System](/sdk/arch/tool-system) - Built-in tool implementations
 - [Workspace Architecture](/sdk/arch/workspace) - Execution environments
-- [Agent Server Architecture](/sdk/arch/agent-server) - Remote execution
+- [Agent Server Architecture](/sdk/arch/overview#agent-server-package-openhandsagent_server) - Remote execution
 
 ### For Implementation Details
 
diff --git a/sdk/arch/security.mdx b/sdk/arch/security.mdx
index c8118fe6..50493b9c 100644
--- a/sdk/arch/security.mdx
+++ b/sdk/arch/security.mdx
@@ -5,7 +5,7 @@ description: High-level architecture of action security analysis and validation
 
 The **Security** system evaluates agent actions for potential risks before execution. It provides pluggable security analyzers that assess action risk levels and enforce confirmation policies based on security characteristics.
 
-**Source:** [`openhands-sdk/penhands/sdk/security/`](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-sdk/openhands/sdk/security)
+**Source:** [`openhands-sdk/openhands/sdk/security/`](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-sdk/openhands/sdk/security)
 
 ## Core Responsibilities
 
@@ -58,7 +58,7 @@ flowchart TB
     
     Check --> Mode
     Mode --> Decision
-    
+
     classDef primary fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px
     classDef secondary fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px
     classDef tertiary fill:#fff4df,stroke:#b7791f,stroke-width:2px
@@ -102,7 +102,8 @@ flowchart TB
     Analyze --> Medium
     Analyze --> High
     Analyze --> Unknown
-    
+
+
     style Low fill:#d1fae5,stroke:#10b981,stroke-width:2px
     style Medium fill:#fef3c7,stroke:#f59e0b,stroke-width:2px
     style High fill:#ffe8e8,stroke:#dc2626,stroke-width:2px
@@ -308,3 +309,8 @@ flowchart LR
 - **[Agent Architecture](/sdk/arch/agent)** - How agents use security analyzers
 - **[Tool System](/sdk/arch/tool-system)** - Tool annotations and metadata; includes MCP tool hints
 - **[Security Guide](/sdk/guides/security)** - Configuring security policies
+
+---
+Last updated: 2025-12-09 06:57 UTC  
+Source commit (software-agent-sdk): `93d405c9`
+
diff --git a/sdk/arch/workspace.mdx b/sdk/arch/workspace.mdx
index dbff538b..5b820294 100644
--- a/sdk/arch/workspace.mdx
+++ b/sdk/arch/workspace.mdx
@@ -203,5 +203,5 @@ flowchart LR
 ## See Also
 
 - **[Conversation Architecture](/sdk/arch/conversation)** - How workspace type determines conversation implementation
-- **[Agent Server](/sdk/arch/agent-server)** - Remote execution API
+- **[Agent Server](/sdk/arch/overview#agent-server-package-openhandsagent_server)** - Remote execution API
 - **[Tool System](/sdk/arch/tool-system)** - Tools that use workspace for execution
diff --git a/sdk/guides/agent-server/api-sandbox.mdx b/sdk/guides/agent-server/api-sandbox.mdx
index 4e9d8931..a378572a 100644
--- a/sdk/guides/agent-server/api-sandbox.mdx
+++ b/sdk/guides/agent-server/api-sandbox.mdx
@@ -194,7 +194,7 @@ All agent execution happens on the remote runtime infrastructure.
 
 ## Next Steps
 
-- **[Docker Sandboxed Server](/sdk/guides/agent-server/docker-sandbox)**
-- **[Local Agent Server](/sdk/guides/agent-server/local-server)**
-- **[Agent Server Overview](/sdk/guides/agent-server/overview)** - Architecture and implementation details
-- **[Agent Server Package Architecture](/sdk/arch/agent-server)** - Remote execution architecture
+- **[Docker Sandbox](/sdk/guides/agent-server/docker-sandbox)** - Run with DockerWorkspace
+- **[Local Agent Server](/sdk/guides/agent-server/local-server)** - Development without containers
+- **[Remote Agent Server Overview](/sdk/guides/agent-server/overview)** - Workspace types and deployment options
+- **[Agent Server Architecture](/sdk/arch/overview#agent-server-package-openhandsagent_server)** - Technical details, endpoints, authentication
diff --git a/sdk/guides/agent-server/cloud-workspace.mdx b/sdk/guides/agent-server/cloud-workspace.mdx
index eaf51bb4..a521e4ae 100644
--- a/sdk/guides/agent-server/cloud-workspace.mdx
+++ b/sdk/guides/agent-server/cloud-workspace.mdx
@@ -205,7 +205,8 @@ This verifies connectivity to the cloud sandbox and ensures the environment is r
 
 ## Next Steps
 
-- **[API-based Sandbox](/sdk/guides/agent-server/api-sandbox)** - Connect to Runtime API service
-- **[Docker Sandboxed Server](/sdk/guides/agent-server/docker-sandbox)** - Run locally with Docker
+- **[API Sandbox](/sdk/guides/agent-server/api-sandbox)** - Runtime API integration
+- **[Docker Sandbox](/sdk/guides/agent-server/docker-sandbox)** - Isolated Docker containers
 - **[Local Agent Server](/sdk/guides/agent-server/local-server)** - Development without containers
-- **[Agent Server Overview](/sdk/guides/agent-server/overview)** - Architecture and implementation details
+- **[Remote Agent Server Overview](/sdk/guides/agent-server/overview)** - Workspace types and deployment options
+- **[Agent Server Architecture](/sdk/arch/overview#agent-server-package-openhandsagent_server)** - Technical details, endpoints, authentication
diff --git a/sdk/guides/agent-server/docker-sandbox.mdx b/sdk/guides/agent-server/docker-sandbox.mdx
index 45ed82c4..2f16f1ad 100644
--- a/sdk/guides/agent-server/docker-sandbox.mdx
+++ b/sdk/guides/agent-server/docker-sandbox.mdx
@@ -602,7 +602,8 @@ http://localhost:8012/vnc.html?autoconnect=1&resize=remote
 
 ## Next Steps
 
-- **[Local Agent Server](/sdk/guides/agent-server/local-server)**
-- **[Agent Server Overview](/sdk/guides/agent-server/overview)** - Architecture and implementation details
-- **[API Sandboxed Server](/sdk/guides/agent-server/api-sandbox)** - Connect to hosted API service
-- **[Agent Server Package Architecture](/sdk/arch/agent-server)** - Remote execution architecture
+- **[Local Agent Server](/sdk/guides/agent-server/local-server)** - Development without containers
+- **[API Sandbox](/sdk/guides/agent-server/api-sandbox)** - Runtime API integration
+- **[Cloud Workspace](/sdk/guides/agent-server/cloud-workspace)** - OpenHands Cloud managed sandboxes
+- **[Remote Agent Server Overview](/sdk/guides/agent-server/overview)** - Workspace types and deployment options
+- **[Agent Server Architecture](/sdk/arch/overview#agent-server-package-openhandsagent_server)** - Technical details, endpoints, authentication
diff --git a/sdk/guides/agent-server/local-server.mdx b/sdk/guides/agent-server/local-server.mdx
index 1df1e2e8..c5a59e9c 100644
--- a/sdk/guides/agent-server/local-server.mdx
+++ b/sdk/guides/agent-server/local-server.mdx
@@ -359,7 +359,8 @@ This allows you to inspect the conversation history, analyze agent behavior, and
 
 ## Next Steps
 
-- **[Docker Sandboxed Server](/sdk/guides/agent-server/docker-sandbox)** - Run server in Docker for isolation
-- **[API Sandboxed Server](/sdk/guides/agent-server/api-sandbox)** - Connect to hosted API service
-- **[Agent Server Overview](/sdk/guides/agent-server/overview)** - Architecture and implementation details
-- **[Agent Server Package Architecture](/sdk/arch/agent-server)** - Remote execution architecture
+- **[Docker Sandbox](/sdk/guides/agent-server/docker-sandbox)** - Isolated Docker containers
+- **[API Sandbox](/sdk/guides/agent-server/api-sandbox)** - Runtime API integration
+- **[Cloud Workspace](/sdk/guides/agent-server/cloud-workspace)** - OpenHands Cloud managed sandboxes
+- **[Remote Agent Server Overview](/sdk/guides/agent-server/overview)** - Workspace types and deployment options
+- **[Agent Server Architecture](/sdk/arch/overview#agent-server-package-openhandsagent_server)** - Technical details, endpoints, authentication
diff --git a/sdk/guides/agent-server/overview.mdx b/sdk/guides/agent-server/overview.mdx
index 14970832..795dfbed 100644
--- a/sdk/guides/agent-server/overview.mdx
+++ b/sdk/guides/agent-server/overview.mdx
@@ -1,12 +1,17 @@
 ---
-title: Overview
+title: Remote Agent Server
 description: 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, any cloud) with strong isolation. The remote path uses the exact same SDK API as local—switching is just changing the workspace argument; your Conversation code stays the same.
+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.
 
+<Note>
+For technical architecture details (endpoints, authentication, component design), see the [Agent Server Package section](/sdk/arch/overview#agent-server-package-openhandsagent_server) in the Architecture Overview.
+</Note>
 
-For example, switching from a local workspace to a Docker‑based remote agent server:
+## Switching from Local to Remote
+
+Your conversation code stays the same—just swap the workspace:
 
 ```python lines
 # Local → Docker
@@ -18,9 +23,7 @@ with DockerWorkspace( # [!code ++]
     conversation = Conversation(agent=agent, workspace=workspace)  # [!code ++]
 ```
 
-Use `DockerWorkspace` with the pre-built agent server image for the fastest startup. When you need to build from a custom base image, switch to [`DockerDevWorkspace`](/sdk/guides/agent-server/docker-sandbox).
-
-Or switching to an API‑based remote workspace (via [OpenHands Runtime API](https://runtime.all-hands.dev/)):
+Or connect to a hosted runtime API:
 
 ```python lines
 # Local → Remote API
@@ -34,125 +37,126 @@ with APIRemoteWorkspace( # [!code ++]
     conversation = Conversation(agent=agent, workspace=workspace)  # [!code ++]
 ```
 
+Or use OpenHands Cloud for fully managed sandboxes:
 
-## What is a Remote Agent Server?
+```python lines
+# Local → OpenHands Cloud
+conversation = Conversation(agent=agent, workspace=os.getcwd())  # [!code --]
+from openhands.workspace import OpenHandsCloudWorkspace  # [!code ++]
+with OpenHandsCloudWorkspace( # [!code ++]
+    cloud_api_url="https://app.all-hands.dev",  # [!code ++]
+    cloud_api_key="YOUR_CLOUD_API_KEY", # [!code ++]
+) as workspace: # [!code ++]
+    conversation = Conversation(agent=agent, workspace=workspace)  # [!code ++]
+```
 
-A Remote Agent Server is an HTTP/WebSocket server that:
-- **Package the Software Agent SDK into containers** and deploy on your own infrastructure (Kubernetes, VMs, on-prem, or cloud)
-- **Runs agents** on dedicated infrastructure
-- **Manages workspaces** (Docker containers or remote sandboxes)
-- **Streams events** to clients via WebSocket
-- **Handles command and file operations** (execute command, upload, download), check [base class](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/workspace/base.py) for more details
-- **Provides isolation** between different agent executions
+## Workspace Types
 
-Think of it as the "backend" for your agent, while your Python code acts as the "frontend" client.
+| Workspace | What It Does | Best For |
+|-----------|-------------|----------|
+| [**DockerWorkspace**](/sdk/guides/agent-server/docker-sandbox) | Spawns a Docker container with agent server | Local development with isolation, self-hosted deployments |
+| [**APIRemoteWorkspace**](/sdk/guides/agent-server/api-sandbox) | Connects to a runtime API that provisions sandboxes | Custom runtime environments, CI/CD pipelines |
+| [**OpenHandsCloudWorkspace**](/sdk/guides/agent-server/cloud-workspace) | Connects to OpenHands Cloud for managed sandboxes | Production use, no infrastructure management |
+| [**Local Server**](/sdk/guides/agent-server/local-server) | Runs agent server in-process | Testing, development without Docker |
 
-{/* 
-Same interfaces as local: 
-[BaseConversation](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/conversation/base.py), 
-[ConversationStateProtocol](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/conversation/base.py), 
-[EventsListBase](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/conversation/events_list_base.py). Server-backed impl: 
-[RemoteConversation](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/conversation/impl/remote_conversation.py).
- */}
+## How It Works
 
+When you use a remote workspace, the SDK automatically:
 
-## Architecture Overview
+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
 
-Remote Agent Servers follow a simple three-part architecture:
+```python
+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
+```
 
-```mermaid
-graph TD
-    Client[Client Code] -->|HTTP / WebSocket| Server[Agent Server]
-    Server --> Workspace[Workspace]
+### File and Command Operations
 
-    subgraph Workspace Types
-        Workspace --> Local[Local Folder]
-        Workspace --> Docker[Docker Container]
-        Workspace --> API[Remote Sandbox via API]
-    end
+Workspaces provide file and command operations that work identically whether local or remote:
 
-    Local --> Files[File System]
-    Docker --> Container[Isolated Runtime]
-    API --> Cloud[Cloud Infrastructure]
+```python
+# Execute commands in the workspace
+result = workspace.execute_command("ls -la")
+print(result.stdout)
 
-    style Client fill:#e1f5fe
-    style Server fill:#fff3e0
-    style Workspace fill:#e8f5e8
+# Upload/download files
+workspace.file_upload("local/file.txt", "/workspace/file.txt")
+workspace.file_download("/workspace/output.txt", "local/output.txt")
 ```
 
-1. **Client (Python SDK)** — Your application creates and controls conversations using the SDK.  
-2. **Agent Server** — A lightweight HTTP/WebSocket service that runs the agent and manages workspace execution.  
-3. **Workspace** — An isolated environment (local, Docker, or remote VM) where the agent code runs.
-
-The same SDK API works across all three workspace types—you just switch which workspace the conversation connects to.
-
-## How Remote Conversations Work
+These operations are proxied through the agent server API, keeping your code environment-agnostic.
 
-Each step in the diagram maps directly to how the SDK and server interact:
+## Deployment Options
 
-### 1. Workspace Connection → *(Client → Server)*
+### Self-Hosted (Docker)
 
-When you create a conversation with a remote workspace (e.g., `DockerWorkspace` or `APIRemoteWorkspace`), the SDK automatically starts or connects to an agent server inside that workspace:
+Use `DockerWorkspace` to run agent servers in containers on your own infrastructure:
 
 ```python
-with DockerWorkspace(server_image="ghcr.io/openhands/agent-server:latest") as workspace:
+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)
 ```
 
-This turns the local `Conversation` into a **[RemoteConversation](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/conversation/impl/remote_conversation.py)** that speaks to the agent server over HTTP/WebSocket.
-
-
-### 2. Server Initialization → *(Server → Workspace)*
-
-Once the workspace starts:
-- It launches the agent server process.
-- Waits for it to be ready.
-- Shares the server URL with the SDK client.
+See [Docker Sandbox Guide](/sdk/guides/agent-server/docker-sandbox) for details.
 
-You don’t need to manage this manually—the workspace context handles startup and teardown automatically.
+### Runtime API
 
-### 3. Event Streaming → *(Bidirectional WebSocket)*
-
-The client and agent server maintain a live WebSocket connection for streaming events:
+Use `APIRemoteWorkspace` to connect to a runtime API service that provisions sandboxes:
 
 ```python
-def on_event(event):
-    print(f"Received: {type(event).__name__}")
+from openhands.workspace import APIRemoteWorkspace
 
-conversation = Conversation(agent=agent, workspace=workspace, callbacks=[on_event])
+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)
 ```
 
-This allows you to see real-time updates from the running agent as it executes tasks inside the workspace.
+See [API Sandbox Guide](/sdk/guides/agent-server/api-sandbox) for details.
 
-### 4. Workspace Supports File and Command Operations → *(Server ↔ Workspace)*
+### OpenHands Cloud
 
-Workspace supports file and command operations via the agent server API ([base class](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/workspace/base.py)), ensuring isolation and consistent behavior:
+Use `OpenHandsCloudWorkspace` for fully managed sandbox environments:
 
 ```python
-workspace.file_upload(local_path, remote_path)
-workspace.file_download(remote_path, local_path)
-result = workspace.execute_command("ls -la")
-print(result.stdout)
-```
-
-These commands are proxied through the agent server, whether it’s a Docker container or a remote VM, keeping your client code environment-agnostic.
-
-### Summary
+from openhands.workspace import OpenHandsCloudWorkspace
 
-The architecture makes remote execution seamless:
-- Your **client code** stays the same.
-- The **agent server** manages execution and streaming.
-- The **workspace** provides secure, isolated runtime environments.
+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)
+```
 
-Switching from local to remote is just a matter of swapping the workspace class—no code rewrites needed.
+See [Cloud Workspace Guide](/sdk/guides/agent-server/cloud-workspace) for details.
 
 ## Next Steps
 
-Explore different deployment options:
-
-- **[Local Agent Server](/sdk/guides/agent-server/local-server)** - Run agent server in the same process
-- **[Docker Sandboxed Server](/sdk/guides/agent-server/docker-sandbox)** - Run agent server in isolated Docker containers
-- **[API Sandboxed Server](/sdk/guides/agent-server/api-sandbox)** - Connect to hosted agent server via API
+**Deployment Guides:**
+- [Local Agent Server](/sdk/guides/agent-server/local-server) - Run server in-process for development
+- [Docker Sandbox](/sdk/guides/agent-server/docker-sandbox) - Isolated Docker containers
+- [API Sandbox](/sdk/guides/agent-server/api-sandbox) - Runtime API integration
+- [Cloud Workspace](/sdk/guides/agent-server/cloud-workspace) - OpenHands Cloud managed sandboxes
 
-For architectural details:
-- **[Agent Server Package Architecture](/sdk/arch/agent-server)** - Remote execution architecture and deployment
+**Architecture:**
+- [Architecture Overview](/sdk/arch/overview#agent-server-package-openhandsagent_server) - Technical details, endpoints, authentication
+- [Workspace Architecture](/sdk/arch/workspace) - Workspace abstraction and implementations