Metadata-Version: 2.5
Name: harness-run
Version: 0.4.0
Summary: Define and run remote/background coding agents (Claude Code, Codex) locally and in Gemini Enterprise Agent Platform sandboxes.
Project-URL: Homepage, https://github.com/zytedata/harness-run
Project-URL: Documentation, https://github.com/zytedata/harness-run/tree/main/docs
Project-URL: Changelog, https://github.com/zytedata/harness-run/blob/main/CHANGELOG.md
Project-URL: Issues, https://github.com/zytedata/harness-run/issues
Project-URL: Source, https://github.com/zytedata/harness-run
Author: Konstantin Lopuhin, Ivan Sanchez, Julia Medina
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agent,claude-code,codex,llm,remote-execution,sandbox
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.12
Requires-Dist: google-auth
Requires-Dist: google-cloud-agentplatform>=2.1
Requires-Dist: google-cloud-storage
Requires-Dist: jsonschema
Requires-Dist: packaging
Requires-Dist: pyyaml
Requires-Dist: uv>=0.5
Provides-Extra: local
Requires-Dist: claude-agent-sdk==0.2.130; extra == 'local'
Requires-Dist: openai-codex==0.147.0; extra == 'local'
Description-Content-Type: text/markdown

# harness-run

[![PyPI](https://img.shields.io/pypi/v/harness-run.svg)](https://pypi.org/project/harness-run/)
[![Python versions](https://img.shields.io/pypi/pyversions/harness-run.svg)](https://pypi.org/project/harness-run/)
[![CI](https://github.com/zytedata/harness-run/actions/workflows/ci.yml/badge.svg)](https://github.com/zytedata/harness-run/actions/workflows/ci.yml)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/zytedata/harness-run/blob/main/LICENSE)

`harness-run` is a Python library for running coding agents locally and in remote sandbox environments through a common API.

It provides an abstraction over agent harnesses such as Claude Code and Codex, with support for multiple model providers. Your application can switch harnesses or models without being tightly coupled to one vendor's agent runtime.

The same `Engine` → `Session` → `Run` API works locally for development and remotely on GCP Agent Sandbox for production. With a warm sandbox pool, remote agents can start and complete small tasks in just a few seconds.

## Install

```bash
pip install harness-run
```

To also run agents locally:

```bash
pip install "harness-run[local]"
```

## Requirements

- Python 3.12 or newer.
- Credentials for the model the agent uses: an Anthropic, OpenAI or OpenRouter API key, or Vertex AI on the sandbox. See [Getting started](https://github.com/zytedata/harness-run/blob/main/docs/getting-started.md#credentials).
- For remote runs, a GCP project prepared with `harness-run-gcp-setup --project <your-project>`. See [GCP setup](https://github.com/zytedata/harness-run/blob/main/docs/gcp-setup.md).

## Example

Define a coding agent explicitly using the Codex harness:

```python
from harness_run import AgentSpec

spec = AgentSpec(
    name="code-agent",
    harness="codex",
    model="gpt-5.6-luna",
    checkpoint=True,
)
```

Run it locally:

```python
from harness_run import local

engine = local.deploy(spec)
session = engine.start_session()

result = await session.run(
    "Create a Python function fibonacci(n), add a few tests, and run them."
)

print(result.text)
print(result.cost_usd)
```

A session can continue across multiple turns:

```python
result = await session.send(
    "Now make it iterative instead of recursive and run the tests again."
)
```

### Run remotely

The same agent can run remotely on GCP Agent Sandbox. `harness-run` handles building and deploying the agent environment and running each turn inside an isolated sandbox. Credentials are passed to each run rather than baked into the deployed agent:

```python
import os
from harness_run import sandbox

# Deployment is normally done by CI / ops.
sandbox.deploy(
    spec,
    project="my-project",
    location="us-central1",
    warm_pool=True,
)

# Application code looks up the deployed engine by name.
engine = sandbox.get_engine(
    "code-agent",
    project="my-project",
    location="us-central1",
)

session = engine.start_session()

result = await session.run(
    "Create a Python function fibonacci(n), add a few tests, and run them.",
    secrets={"OPENAI_API_KEY": os.environ["OPENAI_API_KEY"]},
)

session_id = session.session_id
```

With `warm_pool=True`, a ready sandbox is kept available for low-latency execution. Small turns typically start in about a second and can complete in a few seconds.

Another process can later re-attach to the session and continue the conversation:

```python
engine = sandbox.get_engine(
    "code-agent",
    project="my-project",
    location="us-central1",
)

session = engine.get_session(session_id)

result = await session.send(
    "Add type hints and explain the time complexity.",
    secrets={"OPENAI_API_KEY": os.environ["OPENAI_API_KEY"]},
)
```

Want Claude Code instead? The application-level API stays the same. On GCP Agent Sandbox, Claude models are called through Vertex AI by default, so these runs need no API key at all:

```python
spec = AgentSpec(
    name="code-agent",
    harness="claude-code",
    model="claude-sonnet-4-6",
    checkpoint=True,
)
```

The model can also be overridden per session or per turn, and an engine deployed with both harnesses baked in can pick either one per session, so a deployed engine does not need to represent a single fixed model configuration.

### Customize the agent

Skills, MCP servers, a repository to work on and extra packages are all declared on the spec. Secrets are not: the spec names them, and each run supplies the values.

```python
import os
from harness_run import AgentSpec, McpServer, RepoSource, SkillSource, SystemPrompt, local

spec = AgentSpec(
    name="repo-fixer",
    harness="codex",
    model="gpt-5.6-luna",
    system_prompt=SystemPrompt.inherit(append="Keep changes small and add tests."),
    # Skills from a git repository or a local directory, staged for the harness.
    skills=[SkillSource.git("https://github.com/zytedata/codex-skills")],
    # Cloned into the working directory before the agent runs; `auth` makes it push-ready.
    repos=[RepoSource.git("https://github.com/acme/some-repo", ref="main", auth="GH_TOKEN")],
    mcp_servers=[
        McpServer.github(),  # lets the agent open pull requests, using GH_TOKEN
        McpServer.remote(
            "search",
            "https://mcp.example.com",
            header_secrets={"Authorization": "SEARCH_AUTH"},
        ),
    ],
    packages=["httpx", "beautifulsoup4"],  # installed into the agent's environment
    checkpoint=True,
)

session = local.deploy(spec).start_session()

result = await session.run(
    "Fix the failing test in tests/test_parser.py and open a pull request.",
    secrets={
        "OPENAI_API_KEY": os.environ["OPENAI_API_KEY"],
        "GH_TOKEN": os.environ["GH_TOKEN"],
        "SEARCH_AUTH": "Bearer " + os.environ["SEARCH_API_KEY"],
    },
)
```

The same spec deploys unchanged to the sandbox. Every other field has a default; [Configuration](https://github.com/zytedata/harness-run/blob/main/docs/configuration.md) covers the rest, from environment variables and tool allow-lists to budgets and reasoning effort.

## Features

Beyond the basic example, `harness-run` supports:

- Multiple agent harnesses and models — Claude Code with Claude models, Codex with OpenAI models, and either harness with models served through OpenRouter.
- Local and remote execution through the same API, with remote runs on GCP Agent Sandbox.
- Low-latency remote runs using warm sandbox pools.
- Multi-turn sessions with checkpoint/resume and durable remote history.
- Per-session and per-turn configuration for models, prompts, budgets, tools, output schemas, and more.
- Streaming and polling as alternatives to awaiting a completed run.
- Structured output with Pydantic models or JSON Schema.
- Repository and workspace setup, MCP servers, and agent skills.
- Per-run secrets without baking credentials into deployed agents.
- Steering, interruption, and shell access (`exec()`) while an agent is running.
- Usage, cost, and resource reporting for production workloads.

## Documentation

Start with [Getting started](https://github.com/zytedata/harness-run/blob/main/docs/getting-started.md).

- [Harnesses and models](https://github.com/zytedata/harness-run/blob/main/docs/harnesses-and-models.md) — Claude Code, Codex, model selection, and reasoning settings
- [Configuration](https://github.com/zytedata/harness-run/blob/main/docs/configuration.md) — `AgentSpec`, `SessionConfig`, and `TurnConfig`
- [Sessions and runs](https://github.com/zytedata/harness-run/blob/main/docs/runs-and-sessions.md) — multi-turn conversations, streaming, polling, resume, steering, interruption, and `exec()`
- [Local runtime](https://github.com/zytedata/harness-run/blob/main/docs/local-runtime.md) — local development and workspaces
- [Sandbox runtime](https://github.com/zytedata/harness-run/blob/main/docs/sandbox-runtime.md) — GCP Agent Sandbox deployment, remote execution, warm pools, and engine versions
- [Structured output](https://github.com/zytedata/harness-run/blob/main/docs/structured-output.md)
- [OpenRouter](https://github.com/zytedata/harness-run/blob/main/docs/openrouter.md) — models and provider routing
- [Secrets and security](https://github.com/zytedata/harness-run/blob/main/docs/secrets-and-security.md)
- [Observability](https://github.com/zytedata/harness-run/blob/main/docs/observability.md) — events, history, transcripts, cost, usage, and resources
- [GCP setup](https://github.com/zytedata/harness-run/blob/main/docs/gcp-setup.md)

For contributors, see [TESTING.md](https://github.com/zytedata/harness-run/blob/main/TESTING.md). For implementation details and platform architecture, see [DESIGN.md](https://github.com/zytedata/harness-run/blob/main/DESIGN.md). Release notes and upgrade instructions are in [CHANGELOG.md](https://github.com/zytedata/harness-run/blob/main/CHANGELOG.md).

## License and provenance

`harness-run` is developed by [Zyte](https://www.zyte.com) and released under the [Apache-2.0](https://github.com/zytedata/harness-run/blob/main/LICENSE) license.

Much of the code was written with AI coding agents, chiefly Claude Code, with the maintainers directing the work and reviewing the result.
