Skip to main content

​
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.

​
Properties

  • working_dir: Annotated[str, BeforeValidator(_convert_path_to_str), Field(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() -> CommandResult source Execute a bash command on the system. Parameters:
  • command str – The bash command to execute
  • cwd str | Path | None – Working directory for the command (optional)
  • timeout float – Timeout in seconds (defaults to 30.0)
Returns:
  • CommandResult Result containing stdout, stderr, exit_code, and other metadata
Raises:
  • Exception – If command execution fails
    ​
    command
    str
    required
    None
    ​
    cwd
    str | Path | None
    None
    ​
    timeout
    float
    None
abstractmethod file_upload() -> FileOperationResult source Upload a file to the system. Parameters:
  • source_path str | Path – Path to the source file
  • destination_path str | Path – Path where the file should be uploaded
Returns:
  • FileOperationResult Result containing success status and metadata
Raises:
  • Exception – If file upload fails
    ​
    source_path
    str | Path
    required
    None
    ​
    destination_path
    str | Path
    required
    None
abstractmethod file_download() -> FileOperationResult source Download a file from the system. Parameters:
  • source_path str | Path – Path to the source file on the system
  • destination_path str | Path – Path where the file should be downloaded
Returns:
  • FileOperationResult Result containing success status and metadata
Raises:
  • Exception – If file download fails
    ​
    source_path
    str | Path
    required
    None
    ​
    destination_path
    str | Path
    required
    None
abstractmethod git_changes() -> list[GitChange] source Get the git changes for the repository at the path given. Parameters:
  • path str | Path – Path to the git repository
Returns:
  • list[GitChange] list[GitChange]: List of changes
Raises:
  • Exception – If path is not a git repository or getting changes failed
    ​
    path
    str | Path
    required
    None
abstractmethod git_diff() -> GitDiff source Get the git diff for the file at the path given. Parameters:
  • path str | Path – Path to the file
Returns:
  • GitDiff Git diff
Raises:
  • Exception – If path is not a git repository or getting diff failed
    ​
    path
    str | Path
    required
    None
pause() -> None source 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() -> None source 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 LocalWorkspace

Bases: 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.

​
Methods

init() source
​
working_dir
str | Path
required
None
​
kwargs
Any
None
execute_command() -> CommandResult source 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 str – The bash command to execute
  • cwd str | Path | None – Working directory (optional)
  • timeout float – Timeout in seconds
Returns:
  • CommandResult Result with stdout, stderr, exit_code, command, and timeout_occurred
    ​
    command
    str
    required
    None
    ​
    cwd
    str | Path | None
    None
    ​
    timeout
    float
    None
file_upload() -> FileOperationResult source 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 str | Path – Path to the source file
  • destination_path str | Path – Path where the file should be copied
Returns:
  • FileOperationResult Result with success status and file information
    ​
    source_path
    str | Path
    required
    None
    ​
    destination_path
    str | Path
    required
    None
file_download() -> FileOperationResult source 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 str | Path – Path to the source file
  • destination_path str | Path – Path where the file should be copied
Returns:
  • FileOperationResult Result with success status and file information
    ​
    source_path
    str | Path
    required
    None
    ​
    destination_path
    str | Path
    required
    None
git_changes() -> list[GitChange] source Get the git changes for the repository at the path given. Parameters:
  • path str | Path – Path to the git repository
Returns:
  • list[GitChange] list[GitChange]: List of changes
Raises:
  • Exception – If path is not a git repository or getting changes failed
    ​
    path
    str | Path
    required
    None
git_diff() -> GitDiff source Get the git diff for the file at the path given. Parameters:
  • path str | Path – Path to the file
Returns:
  • GitDiff Git diff
Raises:
  • Exception – If path is not a git repository or getting diff failed
    ​
    path
    str | Path
    required
    None
pause() -> None source Pause the workspace (no-op for local workspaces). Local workspaces have nothing to pause since they operate directly on the host filesystem. resume() -> None source Resume the workspace (no-op for local workspaces). Local workspaces have nothing to resume since they operate directly on the host filesystem.

​
class CommandResult

Bases: BaseModel Result of executing a command in the workspace.

​
Properties

  • command: str The command that was executed
  • exit_code: int Exit code of the command
  • stdout: str Standard output from the command
  • stderr: str Standard error from the command
  • timeout_occurred: bool Whether the command timed out during execution

​
class FileOperationResult

Bases: BaseModel Result of a file upload or download operation.

​
Properties

  • success: bool Whether the operation was successful
  • source_path: str Path to the source file
  • destination_path: str Path to the destination file
  • file_size: int | None Size of the file in bytes (if successful)
  • error: str | None Error message (if operation failed)

​
class RemoteWorkspace

Bases: RemoteWorkspaceMixin, 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.

​
Properties

  • client: httpx.Client
  • 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.

​
Methods

reset_client() -> None source 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. execute_command() -> CommandResult source 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 str – The bash command to execute
  • cwd str | Path | None – Working directory (optional)
  • timeout float – Timeout in seconds
Returns:
  • CommandResult Result with stdout, stderr, exit_code, and other metadata
    ​
    command
    str
    required
    None
    ​
    cwd
    str | Path | None
    None
    ​
    timeout
    float
    None
file_upload() -> FileOperationResult source Upload a file to the remote system. Reads the local file and sends it to the remote system via HTTP API. Parameters:
  • source_path str | Path – Path to the local source file
  • destination_path str | Path – Path where the file should be uploaded on remote system
Returns:
  • FileOperationResult Result with success status and metadata
    ​
    source_path
    str | Path
    required
    None
    ​
    destination_path
    str | Path
    required
    None
file_download() -> FileOperationResult source Download a file from the remote system. Requests the file from the remote system via HTTP API and saves it locally. Parameters:
  • source_path str | Path – Path to the source file on remote system
  • destination_path str | Path – Path where the file should be saved locally
Returns:
  • FileOperationResult Result with success status and metadata
    ​
    source_path
    str | Path
    required
    None
    ​
    destination_path
    str | Path
    required
    None
git_changes() -> list[GitChange] source Get the git changes for the repository at the path given. Parameters:
  • path str | Path – Path to the git repository
Returns:
  • list[GitChange] list[GitChange]: List of changes
Raises:
  • Exception – If path is not a git repository or getting changes failed
    ​
    path
    str | Path
    required
    None
git_diff() -> GitDiff source Get the git diff for the file at the path given. Parameters:
  • path str | Path – Path to the file
Returns:
  • GitDiff Git diff
Raises:
  • Exception – If path is not a git repository or getting diff failed
    ​
    path
    str | Path
    required
    None

​
class Workspace

Factory entrypoint that returns a LocalWorkspace or RemoteWorkspace.