docs: add workspace types guide and local_agent_server_mode documentation

docs.json

@@ -289,11 +289,17 @@
                 "group": "Remote Agent Server",
                 "pages": [
                   "sdk/guides/agent-server/overview",
-                  "sdk/guides/agent-server/local-server",
-                  "sdk/guides/agent-server/docker-sandbox",
-                  "sdk/guides/agent-server/apptainer-sandbox",
-                  "sdk/guides/agent-server/api-sandbox",
-                  "sdk/guides/agent-server/cloud-workspace",
+                  {
+                    "group": "Workspaces",
+                    "pages": [
+                      "sdk/guides/agent-server/workspace-types",
+                      "sdk/guides/agent-server/local-server",
+                      "sdk/guides/agent-server/docker-sandbox",
+                      "sdk/guides/agent-server/apptainer-sandbox",
+                      "sdk/guides/agent-server/api-sandbox",
+                      "sdk/guides/agent-server/cloud-workspace"
+                    ]
+                  },
                   "sdk/guides/agent-server/custom-tools",
                   {
                     "group": "API Reference",
@@ -454,7 +460,8 @@
     {
       "tag": "link",
       "attributes": {
-        "rel": "stylesheet"
+        "rel": "stylesheet",
+        "href": "/style.css"
       }
     }
   ],

sdk/guides/agent-server/cloud-workspace.mdx

@@ -5,7 +5,7 @@
 
 > A ready-to-run example is available [here](#ready-to-run-example)!
 
 The `OpenHandsCloudWorkspace` demonstrates how to use the [OpenHands Cloud](https://app.all-hands.dev) to provision and manage sandboxed environments for agent execution. This provides a seamless experience with automatic sandbox provisioning, monitoring, and secure execution without managing your own infrastructure.
 
 ## Key Concepts
 
@@ -71,7 +71,7 @@
 
 ```python icon="python" focus={1-3}
 result = workspace.execute_command(
     "echo 'Hello from OpenHands Cloud sandbox!' && pwd"
 )
 logger.info(f"Command completed: {result.exit_code}, {result.stdout}")
 ```
@@ -383,6 +383,121 @@
 uv run python examples/02_remote_agent_server/10_cloud_workspace_share_credentials.py
 ```
 
+## Local Agent Server Mode
+
+Use `local_agent_server_mode=True` when your SDK script is **already running inside** an OpenHands Cloud sandbox — for example, as part of an automation workflow deployed to the cloud.
+
+### When to Use This Mode
+
+| Scenario | Normal Mode | Local Agent Server Mode |
+|----------|-------------|-------------------------|
+| Script runs on your local machine | ✅ | ❌ |
+| Script runs in CI (GitHub Actions runner) | ✅ | ❌ |
+| Script deployed to run inside Cloud sandbox | ❌ | ✅ |
+| Automation service executes your script | ❌ | ✅ |
+
+### How It Differs from Normal Mode
+
+In **normal mode**, `OpenHandsCloudWorkspace` provisions a new sandbox via the Cloud API:
+
+<Frame>
+  <img src="/sdk/guides/agent-server/images/normal-mode.svg" alt="Normal mode: Your machine communicates with OpenHands Cloud via API" />
+</Frame>
+
+In **local agent server mode**, your script is already inside the sandbox and connects to the local agent-server:
+
+<Frame>
+  <img src="/sdk/guides/agent-server/images/local-agent-server-mode-simple.svg" alt="Local agent server mode: Script runs inside Cloud sandbox" />
+</Frame>
+
+Key differences:
+- **No sandbox provisioning** — skips create/wait/delete lifecycle
+- **Connects to localhost** — talks to the agent-server already running in the sandbox
+- **Cloud credentials still work** — `get_llm()` and `get_secrets()` call the Cloud API
+
+### Configuration
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `local_agent_server_mode` | `bool` | `False` | Skip sandbox provisioning, connect to localhost |
+| `agent_server_port` | `int` | `60000` | Port of the local agent-server |
+
+### Environment Variables
+
+When running inside a Cloud sandbox, these environment variables are set automatically:
+
+| Variable | Description |
+|----------|-------------|
+| `SANDBOX_ID` | Sandbox identifier for `get_llm()` / `get_secrets()` |
+| `SESSION_API_KEY` | Session auth key (fallback: `OH_SESSION_API_KEYS_0`) |
+| `AGENT_SERVER_PORT` | Port override (optional) |
+| `AUTOMATION_CALLBACK_URL` | URL to POST completion status on exit (optional) |
+| `AUTOMATION_RUN_ID` | ID included in callback payload (optional) |
+
+### Example: Automation Script Inside a Cloud Sandbox
+
+This script is designed to be uploaded and executed inside an OpenHands Cloud sandbox:
+
+```python icon="python"
+# my_automation.py — runs INSIDE a Cloud sandbox
+import os
+from openhands.workspace import OpenHandsCloudWorkspace
+from openhands.sdk import Conversation
+from openhands.tools.preset.default import get_default_agent
+
+with OpenHandsCloudWorkspace(
+    local_agent_server_mode=True,
+    cloud_api_url="https://app.all-hands.dev",
+    cloud_api_key=os.environ["OPENHANDS_API_KEY"],
+) as workspace:
+    # No sandbox created — connects to local agent-server at localhost:60000
+
+    # Cloud credentials still work
+    llm = workspace.get_llm()
+    secrets = workspace.get_secrets()
+
+    agent = get_default_agent(llm=llm, cli_mode=True)
+    conversation = Conversation(agent=agent, workspace=workspace)
+
+    if secrets:
+        conversation.update_secrets(secrets)
+
+    conversation.send_message("Perform the automation task")
+    conversation.run()
+    conversation.close()
+
+# On exit: completion callback sent automatically (if AUTOMATION_CALLBACK_URL is set)
+```
+
+### Orchestration Pattern
+
+To deploy an automation script that uses local agent server mode:
+
+1. **Create a sandbox** using normal mode (from your local machine or CI):
+   ```python
+   with OpenHandsCloudWorkspace(
+       cloud_api_url="https://app.all-hands.dev",
+       cloud_api_key=api_key,
+       keep_alive=True,  # Don't delete after setup
+   ) as workspace:
+       workspace.file_upload("my_automation.py", "/workspace/my_automation.py")
+   ```
+
+2. **Execute the script** inside the sandbox:
+   ```python
+   workspace.execute_command("python /workspace/my_automation.py")
+   ```
+
+3. The script uses `local_agent_server_mode=True` to connect to the local agent-server
+
+4. **Receive callback** when the script completes (optional)
+
+This pattern enables fire-and-forget automation where your orchestrator doesn't need to maintain a connection for the entire agent session.
+
+<Note>
+Local agent server mode is primarily used by the OpenHands automation service. For most SDK users, normal mode with `get_llm()` and `get_secrets()` provides a simpler experience.
+</Note>
+
 ## Next Steps
 
 - **[API-based Sandbox](/sdk/guides/agent-server/api-sandbox)** - Connect to Runtime API service