> ## Documentation Index
> Fetch the complete documentation index at: https://allhandsai-cookbook-sync.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Workspace

> High-level architecture of the execution environment abstraction

The **Workspace** component abstracts execution environments for agent operations. It provides a unified interface for command execution and file operations across local processes, containers, and remote servers.

**Source:** [`openhands/sdk/workspace/`](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-sdk/openhands/sdk/workspace)

## Core Responsibilities

The Workspace system has four primary responsibilities:

1. **Execution Abstraction** - Unified interface for command execution across environments
2. **File Operations** - Upload, download, and manipulate files in workspace
3. **Resource Management** - Context manager protocol for setup/teardown
4. **Environment Isolation** - Separate agent execution from host system

## Architecture

```mermaid theme={null}
%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 25, "rankSpacing": 60}} }%%
flowchart TB
    subgraph Interface["Abstract Interface"]
        Base["BaseWorkspace<br><i>Abstract base class</i>"]
    end
    
    subgraph Implementations["Concrete Implementations"]
        Local["LocalWorkspace<br><i>Direct subprocess</i>"]
        Remote["RemoteWorkspace<br><i>HTTP API calls</i>"]
    end
    
    subgraph Operations["Core Operations"]
        Command["execute_command()"]
        Upload["file_upload()"]
        Download["file_download()"]
        Context["__enter__ / __exit__"]
    end
    
    subgraph Targets["Execution Targets"]
        Process["Local Process"]
        Container["Docker Container"]
        Server["Remote Server"]
    end
    
    Base --> Local
    Base --> Remote
    
    Base -.->|Defines| Operations
    
    Local --> Process
    Remote --> Container
    Remote --> Server
    
    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 Base primary
    class Local,Remote secondary
    class Command,Upload tertiary
```

### Key Components

| Component | Purpose | Design |
| - | - | - |
| **[`BaseWorkspace`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/workspace/base.py)** | Abstract interface | Defines execution and file operation contracts |
| **[`LocalWorkspace`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/workspace/local.py)** | Local execution | Subprocess-based command execution |
| **[`RemoteWorkspace`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/workspace/remote/base.py)** | Remote execution | HTTP API-based execution via agent-server |
| **[`CommandResult`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/workspace/models.py)** | Execution output | Structured result with stdout, stderr, exit\_code |
| **[`FileOperationResult`](https://github.com/OpenHands/software-agent-sdk/blob/main/openhands-sdk/openhands/sdk/workspace/models.py)** | File op outcome | Success status and metadata |

## Workspace Types

### Local vs Remote Execution

| Aspect | LocalWorkspace | RemoteWorkspace |
| - | - | - |
| **Execution** | Direct subprocess | HTTP → agent-server |
| **Isolation** | Process-level | Container/VM-level |
| **Performance** | Fast (no network) | Network overhead |
| **Security** | Host system access | Sandboxed |
| **Use Case** | Development, CLI | Production, web apps |

## Core Operations

### Command Execution

```mermaid theme={null}
%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30, "rankSpacing": 40}} }%%
flowchart LR
    Tool["Tool invokes<br>execute_command()"]
    
    Decision{"Workspace<br>type?"}
    
    LocalExec["subprocess.run()<br><i>Direct execution</i>"]
    RemoteExec["POST /command<br><i>HTTP API</i>"]
    
    Result["CommandResult<br>stdout, stderr, exit_code"]
    
    Tool --> Decision
    Decision -->|Local| LocalExec
    Decision -->|Remote| RemoteExec
    
    LocalExec --> Result
    RemoteExec --> Result
    
    style Decision fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px
    style LocalExec fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px
    style RemoteExec fill:#fff4df,stroke:#b7791f,stroke-width:2px
```

**Command Result Structure:**

| Field | Type | Description |
| - | - | - |
| **stdout** | str | Standard output stream |
| **stderr** | str | Standard error stream |
| **exit\_code** | int | Process exit code (0 = success) |
| **timeout** | bool | Whether command timed out |
| **duration** | float | Execution time in seconds |

### File Operations

| Operation | Local Implementation | Remote Implementation |
| - | - | - |
| **Upload** | `shutil.copy()` | `POST /file/upload` with multipart |
| **Download** | `shutil.copy()` | `GET /file/download` stream |
| **Result** | `FileOperationResult` | `FileOperationResult` |

## Resource Management

Workspaces use **context manager** for safe resource handling:

**Lifecycle Hooks:**

| Phase | LocalWorkspace | RemoteWorkspace |
| - | - | - |
| **Enter** | Create working directory | Connect to agent-server, verify |
| **Use** | Execute commands | Proxy commands via HTTP |
| **Exit** | No cleanup (persistent) | Disconnect, optionally stop container |

## Remote Workspace Extensions

The SDK provides remote workspace implementations in `openhands-workspace` package:

```mermaid theme={null}
%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 50}} }%%
flowchart TB
    Base["RemoteWorkspace<br><i>SDK base class</i>"]
    
    Docker["DockerWorkspace<br><i>Auto-spawn containers</i>"]
    API["RemoteAPIWorkspace<br><i>Connect to existing server</i>"]
    
    Base -.->|Extended by| Docker
    Base -.->|Extended by| API
    
    Docker -->|Creates| Container["Docker Container<br>with agent-server"]
    API -->|Connects| Server["Remote Agent Server"]
    
    style Base fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px
    style Docker fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px
    style API fill:#fff4df,stroke:#b7791f,stroke-width:2px
```

**Implementation Comparison:**

| Type | Setup | Isolation | Use Case |
| - | - | - | - |
| **LocalWorkspace** | Immediate | Process | Development, trusted code |
| **DockerWorkspace** | Spawn container | Container | Multi-user, untrusted code |
| **RemoteAPIWorkspace** | Connect to URL | Remote server | Distributed systems, cloud |

**Source:**

* **DockerWorkspace**: [`openhands-workspace/openhands/workspace/docker`](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-workspace/openhands/workspace/docker)
* **RemoteAPIWorkspace**: [`openhands-workspace/openhands/workspace/remote_api`](https://github.com/OpenHands/software-agent-sdk/tree/main/openhands-workspace/openhands/workspace/remote_api)

## Component Relationships

### How Workspace Integrates

```mermaid theme={null}
%%{init: {"theme": "default", "flowchart": {"nodeSpacing": 30}} }%%
flowchart LR
    Workspace["Workspace"]
    Conversation["Conversation"]
    AgentServer["Agent Server"]
    
    Conversation -->|Configures| Workspace
    Workspace -.->|Remote type| AgentServer
    
    style Workspace fill:#f3e8ff,stroke:#7c3aed,stroke-width:2px
    style Conversation fill:#e8f3ff,stroke:#2b6cb0,stroke-width:2px
```

**Relationship Characteristics:**

* **Conversation → Workspace**: Conversation factory uses workspace type to select LocalConversation or RemoteConversation
* **Workspace → Agent Server**: RemoteWorkspace delegates operations to agent-server API
* **Tools Independence**: Tools run in the same environment as workspace

## See Also

* **[Conversation Architecture](/sdk/arch/conversation)** - How workspace type determines conversation implementation
* **[Agent Server](/sdk/arch/agent-server)** - Remote execution API
* **[Tool System](/sdk/arch/tool-system)** - Tools that use workspace for execution


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.