> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openhands.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# openhands.sdk.workspace

> API reference for openhands.sdk.workspace module

### class BaseWorkspace

Bases: `DiscriminatedUnionMixin`, `ABC`

Abstract base class for workspace implementations.

Workspaces provide a sandboxed environment where agents can execute commands,
read/write files, and perform other operations. All workspace implementations
support the context manager protocol for safe resource management.

#### Example

```pycon theme={null}
>>> with workspace:
...     result = workspace.execute_command("echo 'hello'")
...     content = workspace.read_file("example.txt")
```

#### Properties

* `working_dir`: Annotated\[str, BeforeValidator(func=\_convert\_path\_to\_str, json\_schema\_input\_type=PydanticUndefined), FieldInfo(annotation=NoneType, required=True, description='The working directory for agent operations and tool execution. Accepts both string paths and Path objects. Path objects are automatically converted to strings.')]

#### Methods

#### abstractmethod execute\_command()

Execute a bash command on the system.

* Parameters:
  * `command` – The bash command to execute
  * `cwd` – Working directory for the command (optional)
  * `timeout` – Timeout in seconds (defaults to 30.0)
* Returns:
  Result containing stdout, stderr, exit\_code, and other
  : metadata
* Return type:
  [CommandResult](#class-commandresult)
* Raises:
  `Exception` – If command execution fails

#### abstractmethod file\_download()

Download a file from the system.

* Parameters:
  * `source_path` – Path to the source file on the system
  * `destination_path` – Path where the file should be downloaded
* Returns:
  Result containing success status and metadata
* Return type:
  [FileOperationResult](#class-fileoperationresult)
* Raises:
  `Exception` – If file download fails

#### abstractmethod file\_upload()

Upload a file to the system.

* Parameters:
  * `source_path` – Path to the source file
  * `destination_path` – Path where the file should be uploaded
* Returns:
  Result containing success status and metadata
* Return type:
  [FileOperationResult](#class-fileoperationresult)
* Raises:
  `Exception` – If file upload fails

#### abstractmethod git\_changes()

Get the git changes for the repository at the path given.

* Parameters:
  `path` – Path to the git repository
* Returns:
  List of changes
* Return type:
  list\[GitChange]
* Raises:
  `Exception` – If path is not a git repository or getting changes failed

#### abstractmethod git\_diff()

Get the git diff for the file at the path given.

* Parameters:
  `path` – Path to the file
* Returns:
  Git diff
* Return type:
  GitDiff
* Raises:
  `Exception` – If path is not a git repository or getting diff failed

#### model\_config = (configuration object)

Configuration for the model, should be a dictionary conforming to \[ConfigDict]\[pydantic.config.ConfigDict].

#### pause()

Pause the workspace to conserve resources.

For local workspaces, this is a no-op.
For container-based workspaces, this pauses the container.

* Raises:
  `NotImplementedError` – If the workspace type does not support pausing.

#### resume()

Resume a paused workspace.

For local workspaces, this is a no-op.
For container-based workspaces, this resumes the container.

* Raises:
  `NotImplementedError` – If the workspace type does not support resuming.

### class CommandResult

Bases: `BaseModel`

Result of executing a command in the workspace.

#### Properties

* `command`: str
* `exit_code`: int
* `stderr`: str
* `stdout`: str
* `timeout_occurred`: bool

#### Methods

#### model\_config = (configuration object)

Configuration for the model, should be a dictionary conforming to \[ConfigDict]\[pydantic.config.ConfigDict].

### class FileOperationResult

Bases: `BaseModel`

Result of a file upload or download operation.

#### Properties

* `destination_path`: str
* `error`: str | None
* `file_size`: int | None
* `source_path`: str
* `success`: bool

#### Methods

#### model\_config = (configuration object)

Configuration for the model, should be a dictionary conforming to \[ConfigDict]\[pydantic.config.ConfigDict].

### class LocalWorkspace

Bases: [`BaseWorkspace`](#class-baseworkspace)

Local workspace implementation that operates on the host filesystem.

LocalWorkspace provides direct access to the local filesystem and command execution
environment. It’s suitable for development and testing scenarios where the agent
should operate directly on the host system.

#### Example

```pycon theme={null}
>>> workspace = LocalWorkspace(working_dir="/path/to/project")
>>> with workspace:
...     result = workspace.execute_command("ls -la")
...     content = workspace.read_file("README.md")
```

#### Methods

#### **init**()

Create a new model by parsing and validating input data from keyword arguments.

Raises \[ValidationError]\[pydantic\_core.ValidationError] if the input data cannot be
validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

#### execute\_command()

Execute a bash command locally.

Uses the shared shell execution utility to run commands with proper
timeout handling, output streaming, and error management.

* Parameters:
  * `command` – The bash command to execute
  * `cwd` – Working directory (optional)
  * `timeout` – Timeout in seconds
* Returns:
  Result with stdout, stderr, exit\_code, command, and
  : timeout\_occurred
* Return type:
  [CommandResult](#class-commandresult)

#### file\_download()

Download (copy) a file locally.

For local systems, file download is implemented as a file copy operation
using shutil.copy2 to preserve metadata.

* Parameters:
  * `source_path` – Path to the source file
  * `destination_path` – Path where the file should be copied
* Returns:
  Result with success status and file information
* Return type:
  [FileOperationResult](#class-fileoperationresult)

#### file\_upload()

Upload (copy) a file locally.

For local systems, file upload is implemented as a file copy operation
using shutil.copy2 to preserve metadata.

* Parameters:
  * `source_path` – Path to the source file
  * `destination_path` – Path where the file should be copied
* Returns:
  Result with success status and file information
* Return type:
  [FileOperationResult](#class-fileoperationresult)

#### git\_changes()

Get the git changes for the repository at the path given.

* Parameters:
  `path` – Path to the git repository
* Returns:
  List of changes
* Return type:
  list\[GitChange]
* Raises:
  `Exception` – If path is not a git repository or getting changes failed

#### git\_diff()

Get the git diff for the file at the path given.

* Parameters:
  `path` – Path to the file
* Returns:
  Git diff
* Return type:
  GitDiff
* Raises:
  `Exception` – If path is not a git repository or getting diff failed

#### model\_config = (configuration object)

Configuration for the model, should be a dictionary conforming to \[ConfigDict]\[pydantic.config.ConfigDict].

#### pause()

Pause the workspace (no-op for local workspaces).

Local workspaces have nothing to pause since they operate directly
on the host filesystem.

#### resume()

Resume the workspace (no-op for local workspaces).

Local workspaces have nothing to resume since they operate directly
on the host filesystem.

### class RemoteWorkspace

Bases: `RemoteWorkspaceMixin`, [`BaseWorkspace`](#class-baseworkspace)

Remote workspace implementation that connects to an OpenHands agent server.

RemoteWorkspace provides access to a sandboxed environment running on a remote
OpenHands agent server. This is the recommended approach for production deployments
as it provides better isolation and security.

#### Example

```pycon theme={null}
>>> workspace = RemoteWorkspace(
...     host="https://agent-server.example.com",
...     working_dir="/workspace"
... )
>>> with workspace:
...     result = workspace.execute_command("ls -la")
...     content = workspace.read_file("README.md")
```

#### Properties

* `alive`: bool
  Check if the remote workspace is alive by querying the health endpoint.
  * Returns:
    True if the health endpoint returns a successful response, False otherwise.
* `client`: Client

#### Methods

#### execute\_command()

Execute a bash command on the remote system.

This method starts a bash command via the remote agent server API,
then polls for the output until the command completes.

* Parameters:
  * `command` – The bash command to execute
  * `cwd` – Working directory (optional)
  * `timeout` – Timeout in seconds
* Returns:
  Result with stdout, stderr, exit\_code, and other metadata
* Return type:
  [CommandResult](#class-commandresult)

#### file\_download()

Download a file from the remote system.

Requests the file from the remote system via HTTP API and saves it locally.

* Parameters:
  * `source_path` – Path to the source file on remote system
  * `destination_path` – Path where the file should be saved locally
* Returns:
  Result with success status and metadata
* Return type:
  [FileOperationResult](#class-fileoperationresult)

#### file\_upload()

Upload a file to the remote system.

Reads the local file and sends it to the remote system via HTTP API.

* Parameters:
  * `source_path` – Path to the local source file
  * `destination_path` – Path where the file should be uploaded on remote system
* Returns:
  Result with success status and metadata
* Return type:
  [FileOperationResult](#class-fileoperationresult)

#### git\_changes()

Get the git changes for the repository at the path given.

* Parameters:
  `path` – Path to the git repository
* Returns:
  List of changes
* Return type:
  list\[GitChange]
* Raises:
  `Exception` – If path is not a git repository or getting changes failed

#### git\_diff()

Get the git diff for the file at the path given.

* Parameters:
  `path` – Path to the file
* Returns:
  Git diff
* Return type:
  GitDiff
* Raises:
  `Exception` – If path is not a git repository or getting diff failed

#### model\_config = (configuration object)

Configuration for the model, should be a dictionary conforming to \[ConfigDict]\[pydantic.config.ConfigDict].

#### model\_post\_init()

Override this method to perform additional initialization after **init** and model\_construct.
This is useful if you want to do some validation that requires the entire model to be initialized.

#### reset\_client()

Reset the HTTP client to force re-initialization.

This is useful when connection parameters (host, api\_key) have changed
and the client needs to be recreated with new values.

### class Workspace

### class Workspace

Bases: `object`

Factory entrypoint that returns a LocalWorkspace or RemoteWorkspace.

Usage:
: - Workspace(working\_dir=…) -> LocalWorkspace

* Workspace(working\_dir=…, host=”http\://…”) -> RemoteWorkspace