# Installation

Python requirements, optional extras, and credentials.

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](https://docs.astral.sh/uv/) project:

~~~bash
uv add harnessx
~~~

Any other installer works the same way; the package has no build step:

~~~bash
pip install harnessx
~~~

## Optional dependencies

Install only the integrations your application uses, as extras:

~~~bash
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](../openshell/); 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](../decisions/).

## Configure credentials

The default provider reads `ANTHROPIC_API_KEY` from the process environment. Configure other providers as described in [Model providers](../providers/).

~~~bash
export ANTHROPIC_API_KEY="your-api-key"
~~~

Live Jev decisions need a separate `TYPESAFE_API_KEY`; see [Decisions with Jev](../decisions/#evaluate-typed-questions).

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](../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:

~~~bash
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:

~~~bash
docker compose run --rm tests
~~~

## Check the installed version

~~~bash
uv pip show harnessx
~~~