The package on PyPI is harnessx and the import namespace is harnessx. Python 3.11 or newer is required.
Install the SDK
Add it to a uv project:
uv add harnessx
Any other installer works the same way; the package has no build step:
pip install harnessx
Optional dependencies
Install only the integrations your application uses, as extras:
uv add "harnessx[openai]"
uv add "harnessx[mcp,postgres]"
uv add "harnessx[all]"
| Extra | Adds |
|---|---|
| openai | OpenAI provider dependencies |
| azure | Azure OpenAI provider (same dependencies as openai) |
| openrouter | OpenRouter provider dependencies |
| gemini | Google GenAI provider |
| jev | TypeSafe SDK for Choice, Score, and Noul decisions |
| mcp | MCP clients and CLI |
| postgres | Psycopg SQL backend dependencies |
| temporal | Temporal, Redis, and S3 client dependencies |
| docker | Docker SDK; a running daemon is also required |
| openshell | NVIDIA OpenShell client for the OpenShell sandbox; a running gateway is also required |
| langsmith | Tracing and evaluations |
| server | FastAPI, Uvicorn and python-dotenv for harness-web |
| all | Every integration extra above |
Importing decision types and running the offline Jev examples do not require the jev extra; live decisions do. See Decisions with Jev.
Configure credentials
The default provider reads ANTHROPIC_API_KEY from the process environment. Configure other providers as described in Model providers.
export ANTHROPIC_API_KEY="your-api-key"
Live Jev decisions need a separate TYPESAFE_API_KEY; see Decisions with Jev.
A standalone Agent application does not load a .env file for you; call load_dotenv yourself or export the variables before launching Python. The repository examples and harness-web load the repository's .env.
Work from the repository
The examples and harness-web live in the repository, not in the package. Examples covers the clone, uv sync --all-extras, and what each example needs. That sync installs the SDK in editable mode with every integration and the development tools, so uv run pytest -q runs the suite offline.
Run everything in containers
The repository ships a Dockerfile and a docker-compose.yml. Clone it, and one command builds the image and starts harness-web with PostgreSQL, Temporal and Redis beside it, with no Python or Node to install:
git clone https://github.com/datagol/agent-harness-x.git
cd agent-harness-x
cp .env.example .env # then set ANTHROPIC_API_KEY=... in .env
docker compose up --build
The web app is on http://localhost:8765. Model keys come from your .env, which is read at run time and never copied into the image, or from Workspace setup → API keys in the app. Without keys the offline examples still run. The tests service runs the suite with the PostgreSQL, Temporal and Redis tests enabled:
docker compose run --rm tests
Check the installed version
uv pip show harnessx