From 7591e23a2f8d26f2f2f4051fe0e10bcb2b7ce601 Mon Sep 17 00:00:00 2001 From: John-Mason Shackelford Date: Mon, 23 Mar 2026 14:13:40 -0400 Subject: [PATCH 01/14] docs: add workspace types guide and saas_runtime_mode documentation - Add new workspace-types.mdx page with comparison table and decision guide - Add SaaS Runtime Mode section to cloud-workspace.mdx explaining: - When to use saas_runtime_mode (scripts running inside Cloud sandboxes) - Configuration options and environment variables - Example automation script - Orchestration pattern for deploying automation scripts - Update docs.json navigation to include new workspace-types page This documentation supports the saas_runtime_mode feature added in software-agent-sdk PR #2490. Co-authored-by: openhands --- docs.json | 1 + sdk/guides/agent-server/cloud-workspace.mdx | 127 +++++++++++++++++ sdk/guides/agent-server/workspace-types.mdx | 145 ++++++++++++++++++++ 3 files changed, 273 insertions(+) create mode 100644 sdk/guides/agent-server/workspace-types.mdx diff --git a/docs.json b/docs.json index 9269398f..ed624ff5 100644 --- a/docs.json +++ b/docs.json @@ -286,6 +286,7 @@ "group": "Remote Agent Server", "pages": [ "sdk/guides/agent-server/overview", + "sdk/guides/agent-server/workspace-types", "sdk/guides/agent-server/local-server", "sdk/guides/agent-server/docker-sandbox", "sdk/guides/agent-server/apptainer-sandbox", diff --git a/sdk/guides/agent-server/cloud-workspace.mdx b/sdk/guides/agent-server/cloud-workspace.mdx index 43cc07e9..c288ebfe 100644 --- a/sdk/guides/agent-server/cloud-workspace.mdx +++ b/sdk/guides/agent-server/cloud-workspace.mdx @@ -383,6 +383,133 @@ cd agent-sdk uv run python examples/02_remote_agent_server/10_cloud_workspace_share_credentials.py ``` +## SaaS Runtime Mode + +Use `saas_runtime_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 | SaaS Runtime 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: + +``` +┌─────────────────┐ ┌─────────────────────────┐ +│ Your Machine │ ←───→ │ OpenHands Cloud │ +│ (SDK script) │ API │ (provisions sandbox) │ +└─────────────────┘ └─────────────────────────┘ +``` + +In **SaaS runtime mode**, your script is already inside the sandbox and connects to the local agent-server: + +``` +┌─────────────────────────────────────────────────────┐ +│ OpenHands Cloud Sandbox │ +│ ┌───────────────────────────────────────────────┐ │ +│ │ Your SDK script (saas_runtime_mode=True) │ │ +│ │ └── connects to localhost:60000 │ │ +│ │ └── agent-server already running here │ │ +│ └───────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────┘ +``` + +Key differences: +- **No sandbox provisioning** — skips create/wait/delete lifecycle +- **Connects to localhost** — talks to the agent-server already running in the sandbox +- **SaaS credentials still work** — `get_llm()` and `get_secrets()` call the Cloud API + +### Configuration + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `saas_runtime_mode` | `bool` | `False` | Skip sandbox provisioning, connect to localhost | +| `agent_server_port` | `int` | `60000` | Port of the local agent-server | +| `automation_callback_url` | `str \| None` | `None` | URL to POST completion status on exit | +| `automation_run_id` | `str \| None` | `None` | ID included in callback payload | + +### 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) | + +### 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( + saas_runtime_mode=True, + cloud_api_url="https://app.all-hands.dev", + cloud_api_key=os.environ["OPENHANDS_API_KEY"], + automation_callback_url=os.environ.get("CALLBACK_URL"), + automation_run_id=os.environ.get("RUN_ID"), +) as workspace: + # No sandbox created — connects to local agent-server at localhost:60000 + + # SaaS 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 callback URL configured) +``` + +### Orchestration Pattern + +To deploy an automation script that uses SaaS runtime 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 `saas_runtime_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. + + +SaaS runtime 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. + + ## Next Steps - **[API-based Sandbox](/sdk/guides/agent-server/api-sandbox)** - Connect to Runtime API service diff --git a/sdk/guides/agent-server/workspace-types.mdx b/sdk/guides/agent-server/workspace-types.mdx new file mode 100644 index 00000000..c92e86b7 --- /dev/null +++ b/sdk/guides/agent-server/workspace-types.mdx @@ -0,0 +1,145 @@ +--- +title: Workspace Types +description: Choose the right workspace for your use case — from local development to fully managed cloud execution. +--- + +The SDK supports multiple workspace types, each suited to different deployment scenarios. All workspaces share the same API — switching between them requires only changing the workspace argument to `Conversation`. + +## Quick Comparison + +| Workspace | Best For | Infrastructure | Isolation | SaaS Credentials | +|-----------|----------|----------------|-----------|------------------| +| Path / `LocalWorkspace` | Local development, testing | None | ❌ | ❌ | +| `DockerWorkspace` | Local isolation, CI/CD | Local Docker | ✅ | ❌ | +| `ApptainerWorkspace` | HPC clusters, shared compute | Apptainer/Singularity | ✅ | ❌ | +| `APIRemoteWorkspace` | Self-managed infrastructure | Runtime API | ✅ | ❌ | +| `OpenHandsCloudWorkspace` | Production, managed service | OpenHands Cloud | ✅ | ✅ | + +## Decision Guide + +```mermaid +graph TD + Start[Need to run an agent?] --> Local{Local development?} + Local -->|Yes| NeedIsolation{Need isolation?} + NeedIsolation -->|No| UsePath[Use path string] + NeedIsolation -->|Yes| UseDocker[Use DockerWorkspace] + Local -->|No| Managed{Want managed infra?} + Managed -->|Yes| UseCloud[Use OpenHandsCloudWorkspace] + Managed -->|No| HPC{HPC environment?} + HPC -->|Yes| UseApptainer[Use ApptainerWorkspace] + HPC -->|No| UseAPI[Use APIRemoteWorkspace] + + style UseCloud fill:#e8f5e8 + style UsePath fill:#e1f5fe + style UseDocker fill:#fff3e0 +``` + +### Use a Path String or `LocalWorkspace` When... +- You're developing and testing locally +- You don't need isolation between agent and host +- You want the fastest startup time + +```python +conversation = Conversation(agent=agent, workspace="./my-project") +``` + +### Use `DockerWorkspace` When... +- You need isolation on your local machine +- You're running in CI/CD pipelines +- You want reproducible environments + +```python +from openhands.workspace import DockerWorkspace + +with DockerWorkspace( + server_image="ghcr.io/openhands/agent-server:latest-python", +) as workspace: + conversation = Conversation(agent=agent, workspace=workspace) +``` + +### Use `OpenHandsCloudWorkspace` When... +- You want fully managed infrastructure +- You need to inherit LLM config and secrets from your OpenHands Cloud account +- You're building production applications + +```python +from openhands.workspace import OpenHandsCloudWorkspace + +with OpenHandsCloudWorkspace( + cloud_api_url="https://app.all-hands.dev", + cloud_api_key=os.environ["OPENHANDS_CLOUD_API_KEY"], +) as workspace: + llm = workspace.get_llm() # Inherit from your SaaS account + secrets = workspace.get_secrets() + conversation = Conversation(agent=agent, workspace=workspace) +``` + +### Use `APIRemoteWorkspace` When... +- You have access to a Runtime API deployment +- You want to manage your own infrastructure +- You need specific container images or resource configurations + +```python +from openhands.workspace import APIRemoteWorkspace + +with APIRemoteWorkspace( + runtime_api_url="https://runtime.example.com", + runtime_api_key=os.environ["RUNTIME_API_KEY"], + server_image="ghcr.io/openhands/agent-server:latest-python", +) as workspace: + conversation = Conversation(agent=agent, workspace=workspace) +``` + +### Use `ApptainerWorkspace` When... +- You're running on HPC clusters or shared compute environments +- Your infrastructure uses Singularity/Apptainer instead of Docker +- You need rootless container execution + +```python +from openhands.workspace import ApptainerWorkspace + +with ApptainerWorkspace( + server_image="ghcr.io/openhands/agent-server:latest-python", +) as workspace: + conversation = Conversation(agent=agent, workspace=workspace) +``` + +## How Workspaces Relate to Conversations + +The `Conversation` factory automatically selects the appropriate implementation based on your workspace: + +| Workspace Type | Conversation Type | Where Agent Runs | +|----------------|-------------------|------------------| +| Path / `LocalWorkspace` | `LocalConversation` | Your Python process | +| Any `RemoteWorkspace` | `RemoteConversation` | On the agent server | + +You don't need to specify the conversation type — it's chosen automatically: + +```python +# LocalConversation (agent runs in your process) +conversation = Conversation(agent=agent, workspace="./project") + +# RemoteConversation (agent runs on agent server) +with DockerWorkspace(...) as workspace: + conversation = Conversation(agent=agent, workspace=workspace) +``` + +## Feature Comparison + +| Feature | Local | Docker | Cloud | API | Apptainer | +|---------|-------|--------|-------|-----|-----------| +| No setup required | ✅ | Docker needed | ✅ | Runtime API access | Apptainer needed | +| File isolation | ❌ | ✅ | ✅ | ✅ | ✅ | +| Network isolation | ❌ | ✅ | ✅ | ✅ | ✅ | +| `get_llm()` | ❌ | ❌ | ✅ | ❌ | ❌ | +| `get_secrets()` | ❌ | ❌ | ✅ | ❌ | ❌ | +| Pause/Resume | ❌ | ❌ | ❌ | ✅ | ❌ | +| Custom images | N/A | ✅ | Via specs | ✅ | ✅ | + +## Next Steps + +- **[Local Server](/sdk/guides/agent-server/local-server)** — Run without isolation +- **[Docker Sandbox](/sdk/guides/agent-server/docker-sandbox)** — Local Docker containers +- **[Cloud Workspace](/sdk/guides/agent-server/cloud-workspace)** — OpenHands Cloud managed service +- **[API Sandbox](/sdk/guides/agent-server/api-sandbox)** — Self-managed Runtime API +- **[Apptainer Sandbox](/sdk/guides/agent-server/apptainer-sandbox)** — HPC environments From ada6d424921ef598086bcbe918160336daf92f6d Mon Sep 17 00:00:00 2001 From: John-Mason Shackelford Date: Mon, 23 Mar 2026 14:27:43 -0400 Subject: [PATCH 02/14] docs: nest workspace pages under Workspace Types group Co-authored-by: openhands --- docs.json | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/docs.json b/docs.json index ed624ff5..59e09cc5 100644 --- a/docs.json +++ b/docs.json @@ -286,12 +286,17 @@ "group": "Remote Agent Server", "pages": [ "sdk/guides/agent-server/overview", - "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", + { + "group": "Workspace Types", + "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", From b9db0eaebe356894781f5217333a9c2d413078ad Mon Sep 17 00:00:00 2001 From: John-Mason Shackelford Date: Mon, 23 Mar 2026 14:34:33 -0400 Subject: [PATCH 03/14] docs: rename group to Workspaces, page to Overview Co-authored-by: openhands --- docs.json | 2 +- sdk/guides/agent-server/workspace-types.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs.json b/docs.json index 59e09cc5..3a6d837a 100644 --- a/docs.json +++ b/docs.json @@ -287,7 +287,7 @@ "pages": [ "sdk/guides/agent-server/overview", { - "group": "Workspace Types", + "group": "Workspaces", "pages": [ "sdk/guides/agent-server/workspace-types", "sdk/guides/agent-server/local-server", diff --git a/sdk/guides/agent-server/workspace-types.mdx b/sdk/guides/agent-server/workspace-types.mdx index c92e86b7..be8beabe 100644 --- a/sdk/guides/agent-server/workspace-types.mdx +++ b/sdk/guides/agent-server/workspace-types.mdx @@ -1,5 +1,5 @@ --- -title: Workspace Types +title: Overview description: Choose the right workspace for your use case — from local development to fully managed cloud execution. --- From aaf30a2ade4764f69a81df4eeb5a52932c7e25bc Mon Sep 17 00:00:00 2001 From: John-Mason Shackelford Date: Mon, 23 Mar 2026 14:36:42 -0400 Subject: [PATCH 04/14] docs: simplify quick comparison table for better column widths - Shorten workspace names and headers - Use line break in SaaS Creds header - Center checkmark columns Co-authored-by: openhands --- sdk/guides/agent-server/workspace-types.mdx | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/sdk/guides/agent-server/workspace-types.mdx b/sdk/guides/agent-server/workspace-types.mdx index be8beabe..09c579d4 100644 --- a/sdk/guides/agent-server/workspace-types.mdx +++ b/sdk/guides/agent-server/workspace-types.mdx @@ -7,13 +7,13 @@ The SDK supports multiple workspace types, each suited to different deployment s ## Quick Comparison -| Workspace | Best For | Infrastructure | Isolation | SaaS Credentials | -|-----------|----------|----------------|-----------|------------------| -| Path / `LocalWorkspace` | Local development, testing | None | ❌ | ❌ | -| `DockerWorkspace` | Local isolation, CI/CD | Local Docker | ✅ | ❌ | -| `ApptainerWorkspace` | HPC clusters, shared compute | Apptainer/Singularity | ✅ | ❌ | -| `APIRemoteWorkspace` | Self-managed infrastructure | Runtime API | ✅ | ❌ | -| `OpenHandsCloudWorkspace` | Production, managed service | OpenHands Cloud | ✅ | ✅ | +| Workspace | Best For | Infrastructure | Isolation | SaaS
Creds | +|-----------|----------|----------------|:---------:|:--------------:| +| Local / Path | Development, testing | None | ❌ | ❌ | +| Docker | Local isolation, CI/CD | Local Docker | ✅ | ❌ | +| Apptainer | HPC, shared compute | Singularity | ✅ | ❌ | +| API | Self-managed infra | Runtime API | ✅ | ❌ | +| Cloud | Production, managed | OpenHands Cloud | ✅ | ✅ | ## Decision Guide From bbbb8cdb4c7370bb54931c0e5b4042d0184efafc Mon Sep 17 00:00:00 2001 From: John-Mason Shackelford Date: Mon, 23 Mar 2026 14:39:47 -0400 Subject: [PATCH 05/14] docs: use full class names with hyperlinks in comparison table - Full workspace class names (e.g., OpenHandsCloudWorkspace) - Add hyperlinks to detail pages - Change header to 'SaaS Auth' Co-authored-by: openhands --- sdk/guides/agent-server/workspace-types.mdx | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/sdk/guides/agent-server/workspace-types.mdx b/sdk/guides/agent-server/workspace-types.mdx index 09c579d4..34a7b828 100644 --- a/sdk/guides/agent-server/workspace-types.mdx +++ b/sdk/guides/agent-server/workspace-types.mdx @@ -7,13 +7,13 @@ The SDK supports multiple workspace types, each suited to different deployment s ## Quick Comparison -| Workspace | Best For | Infrastructure | Isolation | SaaS
Creds | -|-----------|----------|----------------|:---------:|:--------------:| -| Local / Path | Development, testing | None | ❌ | ❌ | -| Docker | Local isolation, CI/CD | Local Docker | ✅ | ❌ | -| Apptainer | HPC, shared compute | Singularity | ✅ | ❌ | -| API | Self-managed infra | Runtime API | ✅ | ❌ | -| Cloud | Production, managed | OpenHands Cloud | ✅ | ✅ | +| Workspace | Best For | Infrastructure | Isolation | SaaS
Auth | +|-----------|----------|----------------|:---------:|:-------------:| +| [LocalWorkspace](/sdk/guides/agent-server/local-server) | Development, testing | None | ❌ | ❌ | +| [DockerWorkspace](/sdk/guides/agent-server/docker-sandbox) | Local isolation, CI/CD | Local Docker | ✅ | ❌ | +| [ApptainerWorkspace](/sdk/guides/agent-server/apptainer-sandbox) | HPC, shared compute | Singularity | ✅ | ❌ | +| [APIRemoteWorkspace](/sdk/guides/agent-server/api-sandbox) | Self-managed infra | Runtime API | ✅ | ❌ | +| [OpenHandsCloudWorkspace](/sdk/guides/agent-server/cloud-workspace) | Production, managed | OpenHands Cloud | ✅ | ✅ | ## Decision Guide From b2e9a137fb42263894a80f7b316e650b59da9fe1 Mon Sep 17 00:00:00 2001 From: John-Mason Shackelford Date: Mon, 23 Mar 2026 14:43:16 -0400 Subject: [PATCH 06/14] docs: clarify APIRemoteWorkspace is for Enterprise with responsibilities - Indicate it's for OpenHands Enterprise users - Add Warning block listing what you become responsible for - Update table to say 'Enterprise, low-level control' Co-authored-by: openhands --- sdk/guides/agent-server/workspace-types.mdx | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/sdk/guides/agent-server/workspace-types.mdx b/sdk/guides/agent-server/workspace-types.mdx index 34a7b828..039ded16 100644 --- a/sdk/guides/agent-server/workspace-types.mdx +++ b/sdk/guides/agent-server/workspace-types.mdx @@ -12,7 +12,7 @@ The SDK supports multiple workspace types, each suited to different deployment s | [LocalWorkspace](/sdk/guides/agent-server/local-server) | Development, testing | None | ❌ | ❌ | | [DockerWorkspace](/sdk/guides/agent-server/docker-sandbox) | Local isolation, CI/CD | Local Docker | ✅ | ❌ | | [ApptainerWorkspace](/sdk/guides/agent-server/apptainer-sandbox) | HPC, shared compute | Singularity | ✅ | ❌ | -| [APIRemoteWorkspace](/sdk/guides/agent-server/api-sandbox) | Self-managed infra | Runtime API | ✅ | ❌ | +| [APIRemoteWorkspace](/sdk/guides/agent-server/api-sandbox) | Enterprise, low-level control | Runtime API | ✅ | ❌ | | [OpenHandsCloudWorkspace](/sdk/guides/agent-server/cloud-workspace) | Production, managed | OpenHands Cloud | ✅ | ✅ | ## Decision Guide @@ -75,9 +75,19 @@ with OpenHandsCloudWorkspace( ``` ### Use `APIRemoteWorkspace` When... -- You have access to a Runtime API deployment -- You want to manage your own infrastructure -- You need specific container images or resource configurations +- You're running OpenHands Enterprise and need low-level control over runtime allocation +- You need fine-grained resource management (pause/resume, scaling) +- You want to specify exact container images and runtime configurations + + +With `APIRemoteWorkspace`, you are responsible for: +- Managing Runtime API credentials and access +- Container image selection and updates +- Resource allocation and scaling decisions +- LLM and secret configuration (no SaaS credential inheritance) + +For most use cases, `OpenHandsCloudWorkspace` provides a simpler experience with managed infrastructure. + ```python from openhands.workspace import APIRemoteWorkspace From de1f9d5e60fff4f9de776878e37ae5d38afede62 Mon Sep 17 00:00:00 2001 From: John-Mason Shackelford Date: Mon, 23 Mar 2026 14:46:40 -0400 Subject: [PATCH 07/14] docs: compact table columns to avoid horizontal scroll - Shorter headers: 'Isolated' and 'SaaS' - Use simple checkmark only (empty for false) - Remove center alignment Co-authored-by: openhands --- sdk/guides/agent-server/workspace-types.mdx | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/sdk/guides/agent-server/workspace-types.mdx b/sdk/guides/agent-server/workspace-types.mdx index 039ded16..4647269e 100644 --- a/sdk/guides/agent-server/workspace-types.mdx +++ b/sdk/guides/agent-server/workspace-types.mdx @@ -7,13 +7,13 @@ The SDK supports multiple workspace types, each suited to different deployment s ## Quick Comparison -| Workspace | Best For | Infrastructure | Isolation | SaaS
Auth | -|-----------|----------|----------------|:---------:|:-------------:| -| [LocalWorkspace](/sdk/guides/agent-server/local-server) | Development, testing | None | ❌ | ❌ | -| [DockerWorkspace](/sdk/guides/agent-server/docker-sandbox) | Local isolation, CI/CD | Local Docker | ✅ | ❌ | -| [ApptainerWorkspace](/sdk/guides/agent-server/apptainer-sandbox) | HPC, shared compute | Singularity | ✅ | ❌ | -| [APIRemoteWorkspace](/sdk/guides/agent-server/api-sandbox) | Enterprise, low-level control | Runtime API | ✅ | ❌ | -| [OpenHandsCloudWorkspace](/sdk/guides/agent-server/cloud-workspace) | Production, managed | OpenHands Cloud | ✅ | ✅ | +| Workspace | Best For | Infrastructure | Isolated | SaaS | +|-----------|----------|----------------|----------|------| +| [LocalWorkspace](/sdk/guides/agent-server/local-server) | Development, testing | None | | | +| [DockerWorkspace](/sdk/guides/agent-server/docker-sandbox) | Local isolation, CI/CD | Local Docker | ✓ | | +| [ApptainerWorkspace](/sdk/guides/agent-server/apptainer-sandbox) | HPC, shared compute | Singularity | ✓ | | +| [APIRemoteWorkspace](/sdk/guides/agent-server/api-sandbox) | Enterprise, low-level control | Runtime API | ✓ | | +| [OpenHandsCloudWorkspace](/sdk/guides/agent-server/cloud-workspace) | Production, managed | OpenHands Cloud | ✓ | ✓ | ## Decision Guide From 7667853885495331d4b0ae8b5465c457924f9cbd Mon Sep 17 00:00:00 2001 From: John-Mason Shackelford Date: Mon, 23 Mar 2026 14:49:04 -0400 Subject: [PATCH 08/14] docs: add table CSS to reduce column widths Override default min-width to allow columns to shrink based on content. Co-authored-by: openhands --- style.css | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/style.css b/style.css index b5da77d4..9e56dc93 100644 --- a/style.css +++ b/style.css @@ -2,3 +2,10 @@ /* Default banner showed white text on yellow in our theme */ color: rgb(67, 66, 64); } + +/* Reduce minimum column width for tables to avoid horizontal scroll */ +table td, +table th { + min-width: auto; + white-space: normal; +} From 3eced6eb7251a1a65547ede27fe882309870a9b9 Mon Sep 17 00:00:00 2001 From: John-Mason Shackelford Date: Mon, 23 Mar 2026 14:49:38 -0400 Subject: [PATCH 09/14] fix: add missing href to stylesheet link in docs.json The stylesheet was not being loaded because the href attribute was missing. Co-authored-by: openhands --- docs.json | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs.json b/docs.json index 3a6d837a..ad779afa 100644 --- a/docs.json +++ b/docs.json @@ -456,7 +456,8 @@ { "tag": "link", "attributes": { - "rel": "stylesheet" + "rel": "stylesheet", + "href": "/style.css" } } ], From 7cd08c3c03fef1dd1abf88aa702d54c6102f3d92 Mon Sep 17 00:00:00 2001 From: John-Mason Shackelford Date: Mon, 23 Mar 2026 14:51:43 -0400 Subject: [PATCH 10/14] docs: use checkbox emoji style consistent with Feature Comparison table Co-authored-by: openhands --- sdk/guides/agent-server/workspace-types.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/sdk/guides/agent-server/workspace-types.mdx b/sdk/guides/agent-server/workspace-types.mdx index 4647269e..d1669fe5 100644 --- a/sdk/guides/agent-server/workspace-types.mdx +++ b/sdk/guides/agent-server/workspace-types.mdx @@ -9,11 +9,11 @@ The SDK supports multiple workspace types, each suited to different deployment s | Workspace | Best For | Infrastructure | Isolated | SaaS | |-----------|----------|----------------|----------|------| -| [LocalWorkspace](/sdk/guides/agent-server/local-server) | Development, testing | None | | | -| [DockerWorkspace](/sdk/guides/agent-server/docker-sandbox) | Local isolation, CI/CD | Local Docker | ✓ | | -| [ApptainerWorkspace](/sdk/guides/agent-server/apptainer-sandbox) | HPC, shared compute | Singularity | ✓ | | -| [APIRemoteWorkspace](/sdk/guides/agent-server/api-sandbox) | Enterprise, low-level control | Runtime API | ✓ | | -| [OpenHandsCloudWorkspace](/sdk/guides/agent-server/cloud-workspace) | Production, managed | OpenHands Cloud | ✓ | ✓ | +| [LocalWorkspace](/sdk/guides/agent-server/local-server) | Development, testing | None | ❌ | ❌ | +| [DockerWorkspace](/sdk/guides/agent-server/docker-sandbox) | Local isolation, CI/CD | Local Docker | ✅ | ❌ | +| [ApptainerWorkspace](/sdk/guides/agent-server/apptainer-sandbox) | HPC, shared compute | Singularity | ✅ | ❌ | +| [APIRemoteWorkspace](/sdk/guides/agent-server/api-sandbox) | Enterprise, low-level control | Runtime API | ✅ | ❌ | +| [OpenHandsCloudWorkspace](/sdk/guides/agent-server/cloud-workspace) | Production, managed | OpenHands Cloud | ✅ | ✅ | ## Decision Guide From e0767d0836d9cb5006f4899d299ca5d21de0fd2b Mon Sep 17 00:00:00 2001 From: John-Mason Shackelford Date: Mon, 23 Mar 2026 14:58:51 -0400 Subject: [PATCH 11/14] docs: restructure workspace overview into Local vs Remote scenarios - Local Scenarios: Development/testing, Local with isolation - Remote & Integration Scenarios: - Building applications with OpenHands Cloud - CI/CD pipeline integration (comparison table) - Running SDK scripts inside Cloud sandboxes (saas_runtime_mode) - Enterprise self-managed infrastructure - Move reference tables to end of document - Add architectural diagram for nested execution pattern Co-authored-by: openhands --- sdk/guides/agent-server/workspace-types.mdx | 199 ++++++++++++-------- 1 file changed, 123 insertions(+), 76 deletions(-) diff --git a/sdk/guides/agent-server/workspace-types.mdx b/sdk/guides/agent-server/workspace-types.mdx index d1669fe5..d1888da2 100644 --- a/sdk/guides/agent-server/workspace-types.mdx +++ b/sdk/guides/agent-server/workspace-types.mdx @@ -1,52 +1,29 @@ --- title: Overview -description: Choose the right workspace for your use case — from local development to fully managed cloud execution. +description: Choose the right workspace for your use case — from local development to production integrations. --- -The SDK supports multiple workspace types, each suited to different deployment scenarios. All workspaces share the same API — switching between them requires only changing the workspace argument to `Conversation`. +The SDK supports multiple workspace types. All share the same API — switching between them requires only changing the workspace argument to `Conversation`. -## Quick Comparison +## Local Scenarios -| Workspace | Best For | Infrastructure | Isolated | SaaS | -|-----------|----------|----------------|----------|------| -| [LocalWorkspace](/sdk/guides/agent-server/local-server) | Development, testing | None | ❌ | ❌ | -| [DockerWorkspace](/sdk/guides/agent-server/docker-sandbox) | Local isolation, CI/CD | Local Docker | ✅ | ❌ | -| [ApptainerWorkspace](/sdk/guides/agent-server/apptainer-sandbox) | HPC, shared compute | Singularity | ✅ | ❌ | -| [APIRemoteWorkspace](/sdk/guides/agent-server/api-sandbox) | Enterprise, low-level control | Runtime API | ✅ | ❌ | -| [OpenHandsCloudWorkspace](/sdk/guides/agent-server/cloud-workspace) | Production, managed | OpenHands Cloud | ✅ | ✅ | +Use these when you're developing on your own machine and want the agent to run locally. -## Decision Guide - -```mermaid -graph TD - Start[Need to run an agent?] --> Local{Local development?} - Local -->|Yes| NeedIsolation{Need isolation?} - NeedIsolation -->|No| UsePath[Use path string] - NeedIsolation -->|Yes| UseDocker[Use DockerWorkspace] - Local -->|No| Managed{Want managed infra?} - Managed -->|Yes| UseCloud[Use OpenHandsCloudWorkspace] - Managed -->|No| HPC{HPC environment?} - HPC -->|Yes| UseApptainer[Use ApptainerWorkspace] - HPC -->|No| UseAPI[Use APIRemoteWorkspace] - - style UseCloud fill:#e8f5e8 - style UsePath fill:#e1f5fe - style UseDocker fill:#fff3e0 -``` +### Development and Testing -### Use a Path String or `LocalWorkspace` When... -- You're developing and testing locally -- You don't need isolation between agent and host -- You want the fastest startup time +For the fastest iteration cycle, use a simple path string. The agent runs in your Python process with direct filesystem access: ```python conversation = Conversation(agent=agent, workspace="./my-project") ``` -### Use `DockerWorkspace` When... -- You need isolation on your local machine -- You're running in CI/CD pipelines -- You want reproducible environments +**Best for:** Rapid prototyping, debugging agent behavior, learning the SDK. + +**Trade-off:** No isolation — the agent can access your entire filesystem and network. + +### Local Development with Isolation + +When you need isolation but still want to run locally, use [DockerWorkspace](/sdk/guides/agent-server/docker-sandbox): ```python from openhands.workspace import DockerWorkspace @@ -57,10 +34,23 @@ with DockerWorkspace( conversation = Conversation(agent=agent, workspace=workspace) ``` -### Use `OpenHandsCloudWorkspace` When... -- You want fully managed infrastructure -- You need to inherit LLM config and secrets from your OpenHands Cloud account -- You're building production applications +**Best for:** Testing agent behavior safely, verifying agents work in a sandboxed environment before deployment. + +**Requirements:** Docker installed locally. + + +For HPC environments using Singularity/Apptainer instead of Docker, see [ApptainerWorkspace](/sdk/guides/agent-server/apptainer-sandbox). + + +--- + +## Remote & Integration Scenarios + +Use these when building applications, integrating with CI/CD, or deploying agents to production. + +### Building Applications with OpenHands Cloud + +When you're building an application that uses OpenHands agents, [OpenHandsCloudWorkspace](/sdk/guides/agent-server/cloud-workspace) provides fully managed infrastructure: ```python from openhands.workspace import OpenHandsCloudWorkspace @@ -69,62 +59,127 @@ with OpenHandsCloudWorkspace( cloud_api_url="https://app.all-hands.dev", cloud_api_key=os.environ["OPENHANDS_CLOUD_API_KEY"], ) as workspace: - llm = workspace.get_llm() # Inherit from your SaaS account - secrets = workspace.get_secrets() + llm = workspace.get_llm() # Inherit LLM config from your Cloud account + secrets = workspace.get_secrets() # Inject secrets without exposing them + + agent = get_default_agent(llm=llm) conversation = Conversation(agent=agent, workspace=workspace) ``` -### Use `APIRemoteWorkspace` When... -- You're running OpenHands Enterprise and need low-level control over runtime allocation -- You need fine-grained resource management (pause/resume, scaling) -- You want to specify exact container images and runtime configurations +**Best for:** Production applications, SaaS integrations, teams that don't want to manage infrastructure. - -With `APIRemoteWorkspace`, you are responsible for: -- Managing Runtime API credentials and access -- Container image selection and updates -- Resource allocation and scaling decisions -- LLM and secret configuration (no SaaS credential inheritance) +**What you get:** +- Managed sandbox provisioning and lifecycle +- LLM configuration inherited from your Cloud account (no API keys in your code) +- Secrets injected securely without transiting through your application +- No infrastructure to manage -For most use cases, `OpenHandsCloudWorkspace` provides a simpler experience with managed infrastructure. - +### CI/CD Pipeline Integration + +For running agents in CI/CD pipelines (GitHub Actions, GitLab CI, etc.), you have two options: + +**Option A: DockerWorkspace** — Run the sandbox on the CI runner itself: ```python -from openhands.workspace import APIRemoteWorkspace +# In your CI script +with DockerWorkspace(...) as workspace: + conversation = Conversation(agent=agent, workspace=workspace) +``` -with APIRemoteWorkspace( - runtime_api_url="https://runtime.example.com", - runtime_api_key=os.environ["RUNTIME_API_KEY"], - server_image="ghcr.io/openhands/agent-server:latest-python", +**Option B: OpenHandsCloudWorkspace** — Offload execution to OpenHands Cloud: + +```python +# In your CI script +with OpenHandsCloudWorkspace( + cloud_api_url="https://app.all-hands.dev", + cloud_api_key=os.environ["OPENHANDS_CLOUD_API_KEY"], ) as workspace: conversation = Conversation(agent=agent, workspace=workspace) ``` -### Use `ApptainerWorkspace` When... -- You're running on HPC clusters or shared compute environments -- Your infrastructure uses Singularity/Apptainer instead of Docker -- You need rootless container execution +| Consideration | DockerWorkspace | OpenHandsCloudWorkspace | +|---------------|-----------------|-------------------------| +| Runner requirements | Docker-in-Docker or privileged | None (API calls only) | +| Resource usage | Consumes runner resources | Offloaded to Cloud | +| Secrets management | You manage | Inherited from Cloud account | +| Setup complexity | Higher | Lower | + +### Running SDK Scripts Inside Cloud Sandboxes + +For advanced orchestration, you may want to run SDK scripts *inside* a Cloud sandbox rather than from outside. This pattern is useful when: + +- You want **fire-and-forget execution** — your orchestrator doesn't maintain a connection for the entire agent session +- You need **nested agent execution** — an outer agent spawns inner agents +- You're building an **automation service** that deploys user-provided scripts + +This uses `saas_runtime_mode=True`. See [SaaS Runtime Mode](/sdk/guides/agent-server/cloud-workspace#saas-runtime-mode) for the full pattern. + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Your Orchestrator (CI, scheduler, or parent agent) │ +│ └── Creates sandbox, uploads script, triggers execution │ +└─────────────────────────────────────────────────────────────┘ + │ + ▼ +┌─────────────────────────────────────────────────────────────┐ +│ OpenHands Cloud Sandbox │ +│ ┌───────────────────────────────────────────────────────┐ │ +│ │ Your SDK script (saas_runtime_mode=True) │ │ +│ │ └── Connects to local agent-server │ │ +│ │ └── Inherits LLM/secrets from Cloud account │ │ +│ │ └── Sends callback on completion │ │ +│ └───────────────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────┘ +``` + +### Enterprise: Self-Managed Infrastructure + +If you're running OpenHands Enterprise and need low-level control over runtime allocation, use [APIRemoteWorkspace](/sdk/guides/agent-server/api-sandbox): ```python -from openhands.workspace import ApptainerWorkspace +from openhands.workspace import APIRemoteWorkspace -with ApptainerWorkspace( +with APIRemoteWorkspace( + runtime_api_url="https://runtime.example.com", + runtime_api_key=os.environ["RUNTIME_API_KEY"], server_image="ghcr.io/openhands/agent-server:latest-python", ) as workspace: conversation = Conversation(agent=agent, workspace=workspace) ``` +**Best for:** Organizations that need fine-grained resource management, custom container images, or must run on their own infrastructure. + + +With `APIRemoteWorkspace`, you are responsible for: +- Managing Runtime API credentials and access +- Container image selection and updates +- Resource allocation and scaling decisions +- LLM and secret configuration (no SaaS credential inheritance) + +For most use cases, `OpenHandsCloudWorkspace` provides a simpler experience. + + +--- + +## Quick Reference + +| Workspace | Best For | Infrastructure | Isolated | SaaS | +|-----------|----------|----------------|----------|------| +| [LocalWorkspace](/sdk/guides/agent-server/local-server) | Development, testing | None | ❌ | ❌ | +| [DockerWorkspace](/sdk/guides/agent-server/docker-sandbox) | Local isolation, CI/CD | Local Docker | ✅ | ❌ | +| [ApptainerWorkspace](/sdk/guides/agent-server/apptainer-sandbox) | HPC, shared compute | Singularity | ✅ | ❌ | +| [OpenHandsCloudWorkspace](/sdk/guides/agent-server/cloud-workspace) | Production, managed | OpenHands Cloud | ✅ | ✅ | +| [APIRemoteWorkspace](/sdk/guides/agent-server/api-sandbox) | Enterprise, low-level control | Runtime API | ✅ | ❌ | + ## How Workspaces Relate to Conversations -The `Conversation` factory automatically selects the appropriate implementation based on your workspace: +The `Conversation` factory automatically selects the appropriate implementation: | Workspace Type | Conversation Type | Where Agent Runs | |----------------|-------------------|------------------| | Path / `LocalWorkspace` | `LocalConversation` | Your Python process | | Any `RemoteWorkspace` | `RemoteConversation` | On the agent server | -You don't need to specify the conversation type — it's chosen automatically: - ```python # LocalConversation (agent runs in your process) conversation = Conversation(agent=agent, workspace="./project") @@ -145,11 +200,3 @@ with DockerWorkspace(...) as workspace: | `get_secrets()` | ❌ | ❌ | ✅ | ❌ | ❌ | | Pause/Resume | ❌ | ❌ | ❌ | ✅ | ❌ | | Custom images | N/A | ✅ | Via specs | ✅ | ✅ | - -## Next Steps - -- **[Local Server](/sdk/guides/agent-server/local-server)** — Run without isolation -- **[Docker Sandbox](/sdk/guides/agent-server/docker-sandbox)** — Local Docker containers -- **[Cloud Workspace](/sdk/guides/agent-server/cloud-workspace)** — OpenHands Cloud managed service -- **[API Sandbox](/sdk/guides/agent-server/api-sandbox)** — Self-managed Runtime API -- **[Apptainer Sandbox](/sdk/guides/agent-server/apptainer-sandbox)** — HPC environments From 0c1728441e653a61ae144960ca4854a855cf22c6 Mon Sep 17 00:00:00 2001 From: John-Mason Shackelford Date: Mon, 23 Mar 2026 15:02:43 -0400 Subject: [PATCH 12/14] docs: replace ASCII diagram with SVG for saas_runtime_mode Co-authored-by: openhands --- .../agent-server/images/saas-runtime-mode.svg | 35 +++++++++++++++++++ sdk/guides/agent-server/workspace-types.mdx | 20 ++--------- 2 files changed, 38 insertions(+), 17 deletions(-) create mode 100644 sdk/guides/agent-server/images/saas-runtime-mode.svg diff --git a/sdk/guides/agent-server/images/saas-runtime-mode.svg b/sdk/guides/agent-server/images/saas-runtime-mode.svg new file mode 100644 index 00000000..30b71757 --- /dev/null +++ b/sdk/guides/agent-server/images/saas-runtime-mode.svg @@ -0,0 +1,35 @@ + + + + + + + + + + Your Orchestrator + (CI, scheduler, or parent agent) + Creates sandbox, uploads script, triggers execution + + + + + + + OpenHands Cloud Sandbox + + + + Your SDK script + (saas_runtime_mode=True) + + + + Connects to local agent-server + + + Inherits LLM/secrets from Cloud account + + + Sends callback on completion + diff --git a/sdk/guides/agent-server/workspace-types.mdx b/sdk/guides/agent-server/workspace-types.mdx index d1888da2..cc3444f9 100644 --- a/sdk/guides/agent-server/workspace-types.mdx +++ b/sdk/guides/agent-server/workspace-types.mdx @@ -114,23 +114,9 @@ For advanced orchestration, you may want to run SDK scripts *inside* a Cloud san This uses `saas_runtime_mode=True`. See [SaaS Runtime Mode](/sdk/guides/agent-server/cloud-workspace#saas-runtime-mode) for the full pattern. -``` -┌─────────────────────────────────────────────────────────────┐ -│ Your Orchestrator (CI, scheduler, or parent agent) │ -│ └── Creates sandbox, uploads script, triggers execution │ -└─────────────────────────────────────────────────────────────┘ - │ - ▼ -┌─────────────────────────────────────────────────────────────┐ -│ OpenHands Cloud Sandbox │ -│ ┌───────────────────────────────────────────────────────┐ │ -│ │ Your SDK script (saas_runtime_mode=True) │ │ -│ │ └── Connects to local agent-server │ │ -│ │ └── Inherits LLM/secrets from Cloud account │ │ -│ │ └── Sends callback on completion │ │ -│ └───────────────────────────────────────────────────────┘ │ -└─────────────────────────────────────────────────────────────┘ -``` + + SaaS Runtime Mode orchestration pattern + ### Enterprise: Self-Managed Infrastructure From 47de2d045fca7c86dd86895bcc051bf54acdb7a0 Mon Sep 17 00:00:00 2001 From: John-Mason Shackelford Date: Mon, 23 Mar 2026 15:05:51 -0400 Subject: [PATCH 13/14] docs: replace ASCII diagrams with SVGs in cloud-workspace.mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - normal-mode.svg: Your Machine ↔ API ↔ OpenHands Cloud - saas-runtime-mode-simple.svg: Script inside Cloud sandbox Co-authored-by: openhands --- sdk/guides/agent-server/cloud-workspace.mdx | 22 +++++----------- .../agent-server/images/normal-mode.svg | 25 +++++++++++++++++++ .../images/saas-runtime-mode-simple.svg | 17 +++++++++++++ 3 files changed, 48 insertions(+), 16 deletions(-) create mode 100644 sdk/guides/agent-server/images/normal-mode.svg create mode 100644 sdk/guides/agent-server/images/saas-runtime-mode-simple.svg diff --git a/sdk/guides/agent-server/cloud-workspace.mdx b/sdk/guides/agent-server/cloud-workspace.mdx index c288ebfe..a71d5365 100644 --- a/sdk/guides/agent-server/cloud-workspace.mdx +++ b/sdk/guides/agent-server/cloud-workspace.mdx @@ -400,25 +400,15 @@ Use `saas_runtime_mode=True` when your SDK script is **already running inside** In **normal mode**, `OpenHandsCloudWorkspace` provisions a new sandbox via the Cloud API: -``` -┌─────────────────┐ ┌─────────────────────────┐ -│ Your Machine │ ←───→ │ OpenHands Cloud │ -│ (SDK script) │ API │ (provisions sandbox) │ -└─────────────────┘ └─────────────────────────┘ -``` + + Normal mode: Your machine communicates with OpenHands Cloud via API + In **SaaS runtime mode**, your script is already inside the sandbox and connects to the local agent-server: -``` -┌─────────────────────────────────────────────────────┐ -│ OpenHands Cloud Sandbox │ -│ ┌───────────────────────────────────────────────┐ │ -│ │ Your SDK script (saas_runtime_mode=True) │ │ -│ │ └── connects to localhost:60000 │ │ -│ │ └── agent-server already running here │ │ -│ └───────────────────────────────────────────────┘ │ -└─────────────────────────────────────────────────────┘ -``` + + SaaS runtime mode: Script runs inside Cloud sandbox + Key differences: - **No sandbox provisioning** — skips create/wait/delete lifecycle diff --git a/sdk/guides/agent-server/images/normal-mode.svg b/sdk/guides/agent-server/images/normal-mode.svg new file mode 100644 index 00000000..395a992c --- /dev/null +++ b/sdk/guides/agent-server/images/normal-mode.svg @@ -0,0 +1,25 @@ + + + + + + + + + + + + + Your Machine + (SDK script) + + + + + API + + + + OpenHands Cloud + (provisions sandbox) + diff --git a/sdk/guides/agent-server/images/saas-runtime-mode-simple.svg b/sdk/guides/agent-server/images/saas-runtime-mode-simple.svg new file mode 100644 index 00000000..2786071c --- /dev/null +++ b/sdk/guides/agent-server/images/saas-runtime-mode-simple.svg @@ -0,0 +1,17 @@ + + + + OpenHands Cloud Sandbox + + + + Your SDK script + (saas_runtime_mode=True) + + + + connects to localhost:60000 + + + agent-server already running + From cbed48d241e5eafb20f7e825cee6b967fd7fbd96 Mon Sep 17 00:00:00 2001 From: openhands Date: Wed, 25 Mar 2026 17:52:56 +0000 Subject: [PATCH 14/14] docs: rename saas_runtime_mode to local_agent_server_mode Update all references to match the rename in software-agent-sdk PR #2490: - Rename parameter: saas_runtime_mode -> local_agent_server_mode - Rename section heading: SaaS Runtime Mode -> Local Agent Server Mode - Rename SVG files to match new naming - Move automation_callback_url and automation_run_id to env vars table - Update code examples to remove constructor args that are now env vars Co-authored-by: openhands --- sdk/guides/agent-server/cloud-workspace.mdx | 34 +++++++++---------- ...svg => local-agent-server-mode-simple.svg} | 2 +- ...e-mode.svg => local-agent-server-mode.svg} | 2 +- sdk/guides/agent-server/workspace-types.mdx | 4 +-- 4 files changed, 20 insertions(+), 22 deletions(-) rename sdk/guides/agent-server/images/{saas-runtime-mode-simple.svg => local-agent-server-mode-simple.svg} (92%) rename sdk/guides/agent-server/images/{saas-runtime-mode.svg => local-agent-server-mode.svg} (96%) diff --git a/sdk/guides/agent-server/cloud-workspace.mdx b/sdk/guides/agent-server/cloud-workspace.mdx index a71d5365..50b6888e 100644 --- a/sdk/guides/agent-server/cloud-workspace.mdx +++ b/sdk/guides/agent-server/cloud-workspace.mdx @@ -383,14 +383,14 @@ cd agent-sdk uv run python examples/02_remote_agent_server/10_cloud_workspace_share_credentials.py ``` -## SaaS Runtime Mode +## Local Agent Server Mode -Use `saas_runtime_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. +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 | SaaS Runtime 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 | ❌ | ✅ | @@ -404,25 +404,23 @@ In **normal mode**, `OpenHandsCloudWorkspace` provisions a new sandbox via the C Normal mode: Your machine communicates with OpenHands Cloud via API -In **SaaS runtime mode**, your script is already inside the sandbox and connects to the local agent-server: +In **local agent server mode**, your script is already inside the sandbox and connects to the local agent-server: - SaaS runtime mode: Script runs inside Cloud sandbox + Local agent server mode: Script runs inside Cloud sandbox Key differences: - **No sandbox provisioning** — skips create/wait/delete lifecycle - **Connects to localhost** — talks to the agent-server already running in the sandbox -- **SaaS credentials still work** — `get_llm()` and `get_secrets()` call the Cloud API +- **Cloud credentials still work** — `get_llm()` and `get_secrets()` call the Cloud API ### Configuration | Parameter | Type | Default | Description | |-----------|------|---------|-------------| -| `saas_runtime_mode` | `bool` | `False` | Skip sandbox provisioning, connect to localhost | +| `local_agent_server_mode` | `bool` | `False` | Skip sandbox provisioning, connect to localhost | | `agent_server_port` | `int` | `60000` | Port of the local agent-server | -| `automation_callback_url` | `str \| None` | `None` | URL to POST completion status on exit | -| `automation_run_id` | `str \| None` | `None` | ID included in callback payload | ### Environment Variables @@ -433,6 +431,8 @@ When running inside a Cloud sandbox, these environment variables are set automat | `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 @@ -446,15 +446,13 @@ from openhands.sdk import Conversation from openhands.tools.preset.default import get_default_agent with OpenHandsCloudWorkspace( - saas_runtime_mode=True, + local_agent_server_mode=True, cloud_api_url="https://app.all-hands.dev", cloud_api_key=os.environ["OPENHANDS_API_KEY"], - automation_callback_url=os.environ.get("CALLBACK_URL"), - automation_run_id=os.environ.get("RUN_ID"), ) as workspace: # No sandbox created — connects to local agent-server at localhost:60000 - # SaaS credentials still work + # Cloud credentials still work llm = workspace.get_llm() secrets = workspace.get_secrets() @@ -468,12 +466,12 @@ with OpenHandsCloudWorkspace( conversation.run() conversation.close() -# On exit: completion callback sent automatically (if callback URL configured) +# On exit: completion callback sent automatically (if AUTOMATION_CALLBACK_URL is set) ``` ### Orchestration Pattern -To deploy an automation script that uses SaaS runtime mode: +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 @@ -490,14 +488,14 @@ To deploy an automation script that uses SaaS runtime mode: workspace.execute_command("python /workspace/my_automation.py") ``` -3. The script uses `saas_runtime_mode=True` to connect to the local agent-server +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. -SaaS runtime 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. +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. ## Next Steps diff --git a/sdk/guides/agent-server/images/saas-runtime-mode-simple.svg b/sdk/guides/agent-server/images/local-agent-server-mode-simple.svg similarity index 92% rename from sdk/guides/agent-server/images/saas-runtime-mode-simple.svg rename to sdk/guides/agent-server/images/local-agent-server-mode-simple.svg index 2786071c..7ac94d3b 100644 --- a/sdk/guides/agent-server/images/saas-runtime-mode-simple.svg +++ b/sdk/guides/agent-server/images/local-agent-server-mode-simple.svg @@ -6,7 +6,7 @@ Your SDK script - (saas_runtime_mode=True) + (local_agent_server_mode=True) diff --git a/sdk/guides/agent-server/images/saas-runtime-mode.svg b/sdk/guides/agent-server/images/local-agent-server-mode.svg similarity index 96% rename from sdk/guides/agent-server/images/saas-runtime-mode.svg rename to sdk/guides/agent-server/images/local-agent-server-mode.svg index 30b71757..517afb7a 100644 --- a/sdk/guides/agent-server/images/saas-runtime-mode.svg +++ b/sdk/guides/agent-server/images/local-agent-server-mode.svg @@ -21,7 +21,7 @@ Your SDK script - (saas_runtime_mode=True) + (local_agent_server_mode=True) diff --git a/sdk/guides/agent-server/workspace-types.mdx b/sdk/guides/agent-server/workspace-types.mdx index cc3444f9..bb619548 100644 --- a/sdk/guides/agent-server/workspace-types.mdx +++ b/sdk/guides/agent-server/workspace-types.mdx @@ -112,10 +112,10 @@ For advanced orchestration, you may want to run SDK scripts *inside* a Cloud san - You need **nested agent execution** — an outer agent spawns inner agents - You're building an **automation service** that deploys user-provided scripts -This uses `saas_runtime_mode=True`. See [SaaS Runtime Mode](/sdk/guides/agent-server/cloud-workspace#saas-runtime-mode) for the full pattern. +This uses `local_agent_server_mode=True`. See [Local Agent Server Mode](/sdk/guides/agent-server/cloud-workspace#local-agent-server-mode) for the full pattern. - SaaS Runtime Mode orchestration pattern + Local Agent Server Mode orchestration pattern ### Enterprise: Self-Managed Infrastructure