> ## Documentation Index
> Fetch the complete documentation index at: https://allhandsai-fix-security-analyzer-examples.mintlify.site/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

* `model_config`: ClassVar\[ConfigDict] = (configuration object)
  Configuration for the model, should be a dictionary conforming to \[ConfigDict]\[pydantic.config.ConfigDict].
* `working_dir`: str

#### 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

### class CommandResult

Bases: `BaseModel`

Result of executing a command in the workspace.

#### Properties

* `command`: str
* `exit_code`: int
* `model_config`: ClassVar\[ConfigDict] = (configuration object)
  Configuration for the model, should be a dictionary conforming to \[ConfigDict]\[pydantic.config.ConfigDict].
* `stderr`: str
* `stdout`: str
* `timeout_occurred`: bool

### class FileOperationResult

Bases: `BaseModel`

Result of a file upload or download operation.

#### Properties

* `destination_path`: str
* `error`: str | None
* `file_size`: int | None
* `model_config`: ClassVar\[ConfigDict] = (configuration object)
  Configuration for the model, should be a dictionary conforming to \[ConfigDict]\[pydantic.config.ConfigDict].
* `source_path`: str
* `success`: bool

### 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")
```

#### Properties

* `kind`: Literal\['LocalWorkspace']
* `model_config`: ClassVar\[ConfigDict] = (configuration object)
  Configuration for the model, should be a dictionary conforming to \[ConfigDict]\[pydantic.config.ConfigDict].
* `working_dir`: str

#### Methods

#### 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

### 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

* `api_key`: str | None
* `client`: Client
* `host`: str
* `kind`: Literal\['RemoteWorkspace']
* `model_config`: ClassVar\[ConfigDict] = (configuration object)
  Configuration for the model, should be a dictionary conforming to \[ConfigDict]\[pydantic.config.ConfigDict].
* `working_dir`: str

#### 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\_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.

### 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