Skip to content

Commit e0767d0

Browse files
jpshackelfordopenhands-agent
jpshackelford
and
openhands-agent
committed
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 <openhands@all-hands.dev>
1 parent 7cd08c3 commit e0767d0

1 file changed

Lines changed: 123 additions & 76 deletions

File tree

‎sdk/guides/agent-server/workspace-types.mdx‎

Lines changed: 123 additions & 76 deletions
Original file line numberDiff line numberDiff line change
@@ -1,52 +1,29 @@
11
---
22
title: Overview
3-
description: Choose the right workspace for your use case — from local development to fully managed cloud execution.
3+
description: Choose the right workspace for your use case — from local development to production integrations.
44
---
55

6-
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`.
6+
The SDK supports multiple workspace types. All share the same API — switching between them requires only changing the workspace argument to `Conversation`.
77

8-
## Quick Comparison
8+
## Local Scenarios
99

10-
| Workspace | Best For | Infrastructure | Isolated | SaaS |
11-
|-----------|----------|----------------|----------|------|
12-
| [LocalWorkspace](/sdk/guides/agent-server/local-server) | Development, testing | None | ❌ | ❌ |
13-
| [DockerWorkspace](/sdk/guides/agent-server/docker-sandbox) | Local isolation, CI/CD | Local Docker | ✅ | ❌ |
14-
| [ApptainerWorkspace](/sdk/guides/agent-server/apptainer-sandbox) | HPC, shared compute | Singularity | ✅ | ❌ |
15-
| [APIRemoteWorkspace](/sdk/guides/agent-server/api-sandbox) | Enterprise, low-level control | Runtime API | ✅ | ❌ |
16-
| [OpenHandsCloudWorkspace](/sdk/guides/agent-server/cloud-workspace) | Production, managed | OpenHands Cloud | ✅ | ✅ |
10+
Use these when you're developing on your own machine and want the agent to run locally.
1711

18-
## Decision Guide
19-
20-
```mermaid
21-
graph TD
22-
Start[Need to run an agent?] --> Local{Local development?}
23-
Local -->|Yes| NeedIsolation{Need isolation?}
24-
NeedIsolation -->|No| UsePath[Use path string]
25-
NeedIsolation -->|Yes| UseDocker[Use DockerWorkspace]
26-
Local -->|No| Managed{Want managed infra?}
27-
Managed -->|Yes| UseCloud[Use OpenHandsCloudWorkspace]
28-
Managed -->|No| HPC{HPC environment?}
29-
HPC -->|Yes| UseApptainer[Use ApptainerWorkspace]
30-
HPC -->|No| UseAPI[Use APIRemoteWorkspace]
31-
32-
style UseCloud fill:#e8f5e8
33-
style UsePath fill:#e1f5fe
34-
style UseDocker fill:#fff3e0
35-
```
12+
### Development and Testing
3613

37-
### Use a Path String or `LocalWorkspace` When...
38-
- You're developing and testing locally
39-
- You don't need isolation between agent and host
40-
- You want the fastest startup time
14+
For the fastest iteration cycle, use a simple path string. The agent runs in your Python process with direct filesystem access:
4115

4216
```python
4317
conversation = Conversation(agent=agent, workspace="./my-project")
4418
```
4519

46-
### Use `DockerWorkspace` When...
47-
- You need isolation on your local machine
48-
- You're running in CI/CD pipelines
49-
- You want reproducible environments
20+
**Best for:** Rapid prototyping, debugging agent behavior, learning the SDK.
21+
22+
**Trade-off:** No isolation — the agent can access your entire filesystem and network.
23+
24+
### Local Development with Isolation
25+
26+
When you need isolation but still want to run locally, use [DockerWorkspace](/sdk/guides/agent-server/docker-sandbox):
5027

5128
```python
5229
from openhands.workspace import DockerWorkspace
@@ -57,10 +34,23 @@ with DockerWorkspace(
5734
conversation = Conversation(agent=agent, workspace=workspace)
5835
```
5936

60-
### Use `OpenHandsCloudWorkspace` When...
61-
- You want fully managed infrastructure
62-
- You need to inherit LLM config and secrets from your OpenHands Cloud account
63-
- You're building production applications
37+
**Best for:** Testing agent behavior safely, verifying agents work in a sandboxed environment before deployment.
38+
39+
**Requirements:** Docker installed locally.
40+
41+
<Note>
42+
For HPC environments using Singularity/Apptainer instead of Docker, see [ApptainerWorkspace](/sdk/guides/agent-server/apptainer-sandbox).
43+
</Note>
44+
45+
---
46+
47+
## Remote & Integration Scenarios
48+
49+
Use these when building applications, integrating with CI/CD, or deploying agents to production.
50+
51+
### Building Applications with OpenHands Cloud
52+
53+
When you're building an application that uses OpenHands agents, [OpenHandsCloudWorkspace](/sdk/guides/agent-server/cloud-workspace) provides fully managed infrastructure:
6454

6555
```python
6656
from openhands.workspace import OpenHandsCloudWorkspace
@@ -69,62 +59,127 @@ with OpenHandsCloudWorkspace(
6959
cloud_api_url="https://app.all-hands.dev",
7060
cloud_api_key=os.environ["OPENHANDS_CLOUD_API_KEY"],
7161
) as workspace:
72-
llm = workspace.get_llm() # Inherit from your SaaS account
73-
secrets = workspace.get_secrets()
62+
llm = workspace.get_llm() # Inherit LLM config from your Cloud account
63+
secrets = workspace.get_secrets() # Inject secrets without exposing them
64+
65+
agent = get_default_agent(llm=llm)
7466
conversation = Conversation(agent=agent, workspace=workspace)
7567
```
7668

77-
### Use `APIRemoteWorkspace` When...
78-
- You're running OpenHands Enterprise and need low-level control over runtime allocation
79-
- You need fine-grained resource management (pause/resume, scaling)
80-
- You want to specify exact container images and runtime configurations
69+
**Best for:** Production applications, SaaS integrations, teams that don't want to manage infrastructure.
8170

82-
<Warning>
83-
With `APIRemoteWorkspace`, you are responsible for:
84-
- Managing Runtime API credentials and access
85-
- Container image selection and updates
86-
- Resource allocation and scaling decisions
87-
- LLM and secret configuration (no SaaS credential inheritance)
71+
**What you get:**
72+
- Managed sandbox provisioning and lifecycle
73+
- LLM configuration inherited from your Cloud account (no API keys in your code)
74+
- Secrets injected securely without transiting through your application
75+
- No infrastructure to manage
8876

89-
For most use cases, `OpenHandsCloudWorkspace` provides a simpler experience with managed infrastructure.
90-
</Warning>
77+
### CI/CD Pipeline Integration
78+
79+
For running agents in CI/CD pipelines (GitHub Actions, GitLab CI, etc.), you have two options:
80+
81+
**Option A: DockerWorkspace** — Run the sandbox on the CI runner itself:
9182

9283
```python
93-
from openhands.workspace import APIRemoteWorkspace
84+
# In your CI script
85+
with DockerWorkspace(...) as workspace:
86+
conversation = Conversation(agent=agent, workspace=workspace)
87+
```
9488

95-
with APIRemoteWorkspace(
96-
runtime_api_url="https://runtime.example.com",
97-
runtime_api_key=os.environ["RUNTIME_API_KEY"],
98-
server_image="ghcr.io/openhands/agent-server:latest-python",
89+
**Option B: OpenHandsCloudWorkspace** — Offload execution to OpenHands Cloud:
90+
91+
```python
92+
# In your CI script
93+
with OpenHandsCloudWorkspace(
94+
cloud_api_url="https://app.all-hands.dev",
95+
cloud_api_key=os.environ["OPENHANDS_CLOUD_API_KEY"],
9996
) as workspace:
10097
conversation = Conversation(agent=agent, workspace=workspace)
10198
```
10299

103-
### Use `ApptainerWorkspace` When...
104-
- You're running on HPC clusters or shared compute environments
105-
- Your infrastructure uses Singularity/Apptainer instead of Docker
106-
- You need rootless container execution
100+
| Consideration | DockerWorkspace | OpenHandsCloudWorkspace |
101+
|---------------|-----------------|-------------------------|
102+
| Runner requirements | Docker-in-Docker or privileged | None (API calls only) |
103+
| Resource usage | Consumes runner resources | Offloaded to Cloud |
104+
| Secrets management | You manage | Inherited from Cloud account |
105+
| Setup complexity | Higher | Lower |
106+
107+
### Running SDK Scripts Inside Cloud Sandboxes
108+
109+
For advanced orchestration, you may want to run SDK scripts *inside* a Cloud sandbox rather than from outside. This pattern is useful when:
110+
111+
- You want **fire-and-forget execution** — your orchestrator doesn't maintain a connection for the entire agent session
112+
- You need **nested agent execution** — an outer agent spawns inner agents
113+
- You're building an **automation service** that deploys user-provided scripts
114+
115+
This uses `saas_runtime_mode=True`. See [SaaS Runtime Mode](/sdk/guides/agent-server/cloud-workspace#saas-runtime-mode) for the full pattern.
116+
117+
```
118+
┌─────────────────────────────────────────────────────────────┐
119+
│ Your Orchestrator (CI, scheduler, or parent agent) │
120+
│ └── Creates sandbox, uploads script, triggers execution │
121+
└─────────────────────────────────────────────────────────────┘
122+
│
123+
▼
124+
┌─────────────────────────────────────────────────────────────┐
125+
│ OpenHands Cloud Sandbox │
126+
│ ┌───────────────────────────────────────────────────────┐ │
127+
│ │ Your SDK script (saas_runtime_mode=True) │ │
128+
│ │ └── Connects to local agent-server │ │
129+
│ │ └── Inherits LLM/secrets from Cloud account │ │
130+
│ │ └── Sends callback on completion │ │
131+
│ └───────────────────────────────────────────────────────┘ │
132+
└─────────────────────────────────────────────────────────────┘
133+
```
134+
135+
### Enterprise: Self-Managed Infrastructure
136+
137+
If you're running OpenHands Enterprise and need low-level control over runtime allocation, use [APIRemoteWorkspace](/sdk/guides/agent-server/api-sandbox):
107138

108139
```python
109-
from openhands.workspace import ApptainerWorkspace
140+
from openhands.workspace import APIRemoteWorkspace
110141

111-
with ApptainerWorkspace(
142+
with APIRemoteWorkspace(
143+
runtime_api_url="https://runtime.example.com",
144+
runtime_api_key=os.environ["RUNTIME_API_KEY"],
112145
server_image="ghcr.io/openhands/agent-server:latest-python",
113146
) as workspace:
114147
conversation = Conversation(agent=agent, workspace=workspace)
115148
```
116149

150+
**Best for:** Organizations that need fine-grained resource management, custom container images, or must run on their own infrastructure.
151+
152+
<Warning>
153+
With `APIRemoteWorkspace`, you are responsible for:
154+
- Managing Runtime API credentials and access
155+
- Container image selection and updates
156+
- Resource allocation and scaling decisions
157+
- LLM and secret configuration (no SaaS credential inheritance)
158+
159+
For most use cases, `OpenHandsCloudWorkspace` provides a simpler experience.
160+
</Warning>
161+
162+
---
163+
164+
## Quick Reference
165+
166+
| Workspace | Best For | Infrastructure | Isolated | SaaS |
167+
|-----------|----------|----------------|----------|------|
168+
| [LocalWorkspace](/sdk/guides/agent-server/local-server) | Development, testing | None | ❌ | ❌ |
169+
| [DockerWorkspace](/sdk/guides/agent-server/docker-sandbox) | Local isolation, CI/CD | Local Docker | ✅ | ❌ |
170+
| [ApptainerWorkspace](/sdk/guides/agent-server/apptainer-sandbox) | HPC, shared compute | Singularity | ✅ | ❌ |
171+
| [OpenHandsCloudWorkspace](/sdk/guides/agent-server/cloud-workspace) | Production, managed | OpenHands Cloud | ✅ | ✅ |
172+
| [APIRemoteWorkspace](/sdk/guides/agent-server/api-sandbox) | Enterprise, low-level control | Runtime API | ✅ | ❌ |
173+
117174
## How Workspaces Relate to Conversations
118175

119-
The `Conversation` factory automatically selects the appropriate implementation based on your workspace:
176+
The `Conversation` factory automatically selects the appropriate implementation:
120177

121178
| Workspace Type | Conversation Type | Where Agent Runs |
122179
|----------------|-------------------|------------------|
123180
| Path / `LocalWorkspace` | `LocalConversation` | Your Python process |
124181
| Any `RemoteWorkspace` | `RemoteConversation` | On the agent server |
125182

126-
You don't need to specify the conversation type — it's chosen automatically:
127-
128183
```python
129184
# LocalConversation (agent runs in your process)
130185
conversation = Conversation(agent=agent, workspace="./project")
@@ -145,11 +200,3 @@ with DockerWorkspace(...) as workspace:
145200
| `get_secrets()` | ❌ | ❌ | ✅ | ❌ | ❌ |
146201
| Pause/Resume | ❌ | ❌ | ❌ | ✅ | ❌ |
147202
| Custom images | N/A | ✅ | Via specs | ✅ | ✅ |
148-
149-
## Next Steps
150-
151-
- **[Local Server](/sdk/guides/agent-server/local-server)** — Run without isolation
152-
- **[Docker Sandbox](/sdk/guides/agent-server/docker-sandbox)** — Local Docker containers
153-
- **[Cloud Workspace](/sdk/guides/agent-server/cloud-workspace)** — OpenHands Cloud managed service
154-
- **[API Sandbox](/sdk/guides/agent-server/api-sandbox)** — Self-managed Runtime API
155-
- **[Apptainer Sandbox](/sdk/guides/agent-server/apptainer-sandbox)** — HPC environments

0 commit comments

Comments
 (0)