Install & Compatibility
Where this runs
tested against v0.3.3 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
✕ build_error
✕ build_error
py 3.11
✕ build_error
✕ build_error
py 3.12
✕ build_error
✓ 20s
py 3.13
✕ build_error
✓ 21.1s
py 3.9
✕ build_error
✕ build_error
574MB installed
● package 574MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
StrReplaceEditor
✓ from openhands_aci.editor import StrReplaceEditor
✗ from openhands_aci.editor import StrReplaceEditor
This quickstart demonstrates a basic utility from `openhands-aci`, specifically executing a shell command, which represents a core function of an Agent-Computer Interface. This is for illustrative purposes as the library is deprecated. For developing with OpenHands, it is recommended to use the OpenHands Agent SDK or the `openhands` CLI directly.
import os
import asyncio
from openhands_aci.utils.shell import execute_shell_command
async def main():
print("Demonstrating a basic utility from openhands-aci (shell command execution).")
print("Note: The openhands-aci library is deprecated. For modern usage, refer to the OpenHands Agent SDK.")
# Example: Execute a simple shell command
command = "echo Hello from OpenHands ACI"
print(f"Executing: '{command}'")
result = await execute_shell_command(command, os.environ.get('AUTH_TOKEN', ''))
print(f"Stdout: {result.stdout.strip()}")
print(f"Stderr: {result.stderr.strip()}")
print(f"Return Code: {result.return_code}")
# Example: List files in the current directory
command_ls = "ls -la"
print(f"\nExecuting: '{command_ls}'")
result_ls = await execute_shell_command(command_ls, os.environ.get('AUTH_TOKEN', ''))
print(f"Stdout:\n{result_ls.stdout.strip()}")
if __name__ == "__main__":
asyncio.run(main())
Debug
Known issues
breakingThe `openhands-aci` repository is officially archived, and the file editor tool, a core component, has been migrated to the OpenHands Agent SDK under `openhands/tools/str_replace_editor`. This means direct usage of `openhands-aci` for file editing functionality is deprecated and likely to be broken or not maintained.fixMigrate your code to use the OpenHands Agent SDK for agent-computer interface functionalities, especially for file editing. Refer to the official OpenHands documentation for the latest SDK usage.
affects: All versions, especially 0.3.3 and earlier, as future development shifts.
gotchaPractical use of OpenHands (which utilizes ACI) often requires a running Docker environment for sandboxed code execution. Without Docker installed and running, core functionalities related to agent interaction with the system may fail.fixEnsure Docker is installed and running on your system. For Windows users, WSL (Windows Subsystem for Linux) is required. Troubleshoot Docker connectivity if errors like 'Launch docker client failed' occur.
affects: All versions that interact with an OpenHands agent or similar sandbox environments.
gotchaEarlier versions of `openhands-aci` (and potentially `openhands` CLI interactions) have reported issues with invalid JSON output, which can lead to parsing errors for agents or consuming applications.fixEnsure you are using the latest available version of `openhands-aci` (though deprecated) or, more importantly, the OpenHands Agent SDK, as fixes for such issues would be integrated there. Monitor for updates related to structured output and parsing.
affects: <0.3.3 (specifically fixed in versions after the reported bug in Dec 2024)
Upgrade
Version history
0.3.3latest on PyPI · released Feb 27, 2026
Audit
Dependencies
pythonrequiredRequired Python version.
DockerrequiredThe OpenHands ecosystem, which utilizes ACI, heavily relies on Docker for sandboxed execution of agent commands. While not a direct Python dependency for the 'openhands-aci' library itself, it is crucial for practical use with an OpenHands agent.