Metadata-Version: 2.5
Name: toolharbor
Version: 0.0.0
Summary: Local-first API and agent workflow platform for reproducible, secure automation.
Project-URL: Homepage, https://github.com/toolharbor/toolharbor
Project-URL: Repository, https://github.com/toolharbor/toolharbor
Project-URL: Issues, https://github.com/toolharbor/toolharbor/issues
Project-URL: Documentation, https://github.com/toolharbor/toolharbor/tree/main/docs
Author: ToolHarbor contributors
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: agents,api,cli,testing,workflows
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.12
Requires-Dist: typer>=0.27.1
Description-Content-Type: text/markdown

# ToolHarbor

**A local-first, open-source API and agent workflow platform for developers who care about reproducibility, security, and automation.**

> A safe local harbor for APIs, tools, and agent workflows.

ToolHarbor is being designed as an open-source platform for defining, running, testing, and reproducing API and agent workflows from local files.

It is not another cloud-first API client or a graphical Postman clone. The initial product is centered on a portable project format, a CLI, a local runner, and workflows that can be executed by developers, CI systems, automation, and agent-testing environments.

## Project status

ToolHarbor is in early implementation. The repository includes an installable Python workspace (`src/toolharbor/`, locked with `uv`) and a pre-alpha `toolharbor` console command that supports `--version` and `--help`. Product commands such as `init`, `run`, and `test` are not available yet.

The PyPI name `toolharbor` is **not yet published**. Current install is from this repository (`uv sync --frozen --all-groups` then `uv run toolharbor --version`; see the [developer quick start](docs/development/QUICKSTART.md)). `pipx install toolharbor` and `uv tool install toolharbor` are planned after a pre-alpha **`0.0.0` name-claim** ([ADR-0036](docs/adr/0036-accept-pre-alpha-pypi-name-claim-policy.md)); that upload is not a product launch. The first planned product pre-release remains M1 `0.1.0-alpha.1`.

The initial documentation plan is complete and covers:

- product vision, positioning, users, principles, and non-goals;
- detailed requirements, MVP scope, journeys, acceptance criteria, and roadmap;
- architecture, project format, CLI, runner, HTTP, workflows, results, and security;
- testing, packaging, compatibility, performance, and migrations;
- open-source licensing, governance, contribution, release, and security operations;
- competitive strategy, developer adoption, launch, business model, moat, metrics, and decision gates;
- optional future ToolHarbor Relay research.

The implementation operating system is now defined. The next phase begins with the curated T0 engineering-bootstrap issues, followed by domain primitives, the format walking skeleton, CLI composition, and the first HTTP vertical slice.

## Core promise

> Define, run, test, and reproduce API and agent workflows from local files, without requiring an account or cloud backend.

## Why ToolHarbor

Modern API work is fragmented. A developer may explore an endpoint in a GUI, recreate it in a script, rewrite it as a test, adapt it for CI, expose it as an agent tool, and debug it from logs produced by another system.

This fragmentation leads to hidden state, stale examples, unsafe secret handling, different local and CI behavior, difficult agent debugging, and dependence on proprietary workspaces.

ToolHarbor aims to make the workflow itself a portable, inspectable, executable engineering artifact.

## Product direction

1. **Foundation** — vision, specification, architecture, repository, and governance.
2. **Workspace format and CLI** — requests, environments, secret references, tests, and workflows stored as files.
3. **Local runner** — deterministic local and CI execution.
4. **API and agent workflows** — tool contracts, scenarios, mocks, traces, and validation.
5. **Local UI** — visual editing and debugging built on the same files and runner.
6. **Extensions** — plugins, importers, exporters, protocol integrations, and custom runners.
7. **Optional cloud services** — collaboration and hosted capabilities without mandatory cloud use.

## Current CLI surface

After `uv sync --frozen --all-groups` or a wheel install:

```bash
toolharbor --version
toolharbor --help
```

## Proposed experience

These commands describe the intended direction and are **not yet available**:

```bash
toolharbor init
toolharbor run collections/users.yaml
toolharbor test workflows/login.yaml
toolharbor agent test scenarios/customer-support.yaml
```

Proposed short alias:

```bash
th
```

## Design commitments

- **Local-first:** no hosted account is required.
- **Files as source of truth:** projects remain understandable and reviewable in Git.
- **Reproducibility:** the same definition can run locally and in CI.
- **Security by design:** project files reference secrets instead of embedding them.
- **Agent-aware, not AI-dependent:** agent workflows are first-class, but API usage does not require AI.
- **Open portability:** users retain control of their projects and execution data.
- **Transparent automation:** network calls, mutations, model calls, and side effects must be visible.

## Initial technical direction

- **Python** for the CLI, local runner, workflow engine, agent/tool testing, and initial plugin system.
- **TypeScript** for the future local UI, schema tooling, documentation website, and frontend packages.
- **Canonical constrained YAML**, governed by versioned JSON Schemas, for portable project definitions.
- **JSON** for machine-readable results and traces.

## Foundation documents

- [Foundation overview](docs/foundation/README.md)
- [Vision](docs/foundation/01-vision.md)
- [Positioning](docs/foundation/02-positioning.md)
- [Problem statement](docs/foundation/03-problem-statement.md)
- [Target users](docs/foundation/04-target-users.md)
- [Use cases](docs/foundation/05-use-cases.md)
- [Product principles](docs/foundation/06-product-principles.md)
- [Non-goals](docs/foundation/07-non-goals.md)
- [Glossary](docs/foundation/08-glossary.md)
- [Decision summary](docs/foundation/09-decision-summary.md)

## Product specification

- [Product specification overview](docs/product/README.md)
- [Product requirements](docs/product/01-product-requirements.md)
- [MVP scope](docs/product/02-mvp-scope.md)
- [Feature catalog](docs/product/03-feature-catalog.md)
- [User journeys](docs/product/04-user-journeys.md)
- [User flows](docs/product/05-user-flows.md)
- [Roadmap](docs/product/06-roadmap.md)
- [Success metrics](docs/product/07-success-metrics.md)
- [Pricing and business model](docs/product/08-pricing-and-business-model.md)
- [Acceptance criteria](docs/product/09-acceptance-criteria.md)
- [Edge cases and constraints](docs/product/10-edge-cases-and-constraints.md)
- [Release and milestone plan](docs/product/11-release-and-milestone-plan.md)
- [Product risks](docs/product/12-product-risks.md)
- [Open questions](docs/product/13-open-questions.md)
- [MVP traceability matrix](docs/product/14-mvp-traceability-matrix.md)

## Technical foundation

- [Technical foundation overview](docs/engineering/README.md)
- [Architecture overview](docs/engineering/01-architecture-overview.md)
- [Technology stack](docs/engineering/02-technology-stack.md)
- [Monorepo and package layout](docs/engineering/03-monorepo-and-package-layout.md)
- [Domain model](docs/engineering/04-domain-model.md)
- [Project format](docs/engineering/05-project-format.md)
- [Schema and compatibility](docs/engineering/06-schema-and-compatibility.md)
- [CLI specification](docs/engineering/07-cli-specification.md)
- [Runner lifecycle](docs/engineering/08-runner-and-execution-lifecycle.md)
- [Variables and environments](docs/engineering/09-variables-and-environments.md)
- [Secrets and redaction](docs/engineering/10-secrets-and-redaction.md)
- [HTTP transport](docs/engineering/11-http-transport.md)
- [Workflow engine](docs/engineering/12-workflow-engine.md)
- [Assertions and testing model](docs/engineering/13-assertions-and-testing-model.md)
- [Tool contracts and agent scenarios](docs/engineering/14-tool-contracts-and-agent-scenarios.md)
- [Results and traces](docs/engineering/15-results-and-traces.md)
- [Plugin architecture](docs/engineering/16-plugin-and-extension-architecture.md)
- [Security model](docs/engineering/17-security-model.md)
- [Threat model](docs/engineering/18-threat-model.md)
- [Testing strategy](docs/engineering/19-testing-strategy.md)
- [Packaging and distribution](docs/engineering/20-packaging-and-distribution.md)
- [Performance and observability](docs/engineering/21-performance-and-observability.md)
- [Compatibility and migrations](docs/engineering/22-compatibility-and-migrations.md)
- [Technical implementation roadmap](docs/engineering/23-technical-implementation-roadmap.md)
- [Technical open questions](docs/engineering/24-technical-open-questions.md)
- [Technical traceability matrix](docs/engineering/25-technical-traceability-matrix.md)

## AI-assisted implementation and engineering operations

ToolHarbor uses a public, vendor-neutral engineering system for human and AI contributors:

- [Universal agent instructions](AGENTS.md)
- [Canonical AI engineering system](.ai/README.md)
- [Development handbook](docs/development/README.md)
- [Developer quick start](docs/development/QUICKSTART.md)
- [Curated T0 backlog](docs/backlog/t0/README.md)

Cursor, Claude Code, and GitHub Copilot files are adapters to the canonical policy. Human approval, deterministic CI, and independent review remain mandatory boundaries.

## Strategy, growth, and business

- [Strategy overview](docs/strategy/README.md)
- [Executive strategy](docs/strategy/01-executive-strategy.md)
- [Market landscape](docs/strategy/02-market-landscape.md)
- [Competitive analysis](docs/strategy/03-competitive-analysis.md)
- [Positioning and category](docs/strategy/04-positioning-and-category.md)
- [Ideal users and beachhead](docs/strategy/05-ideal-users-and-beachhead.md)
- [Strategic wedge](docs/strategy/06-strategic-wedge-and-product-sequence.md)
- [Developer adoption](docs/strategy/07-developer-adoption.md)
- [Community growth](docs/strategy/08-community-growth.md)
- [Launch and go-to-market](docs/strategy/09-launch-and-go-to-market.md)
- [Open-source sustainability](docs/strategy/12-open-source-sustainability.md)
- [Business model](docs/strategy/13-business-model.md)
- [Pricing and packaging](docs/strategy/14-pricing-and-packaging.md)
- [Enterprise strategy](docs/strategy/15-enterprise-strategy.md)
- [Moat and defensibility](docs/strategy/16-moat-and-defensibility.md)
- [Metrics](docs/strategy/17-metrics-and-measurement.md)
- [Execution horizons](docs/strategy/22-execution-horizons.md)
- [Decision gates](docs/strategy/23-decision-gates.md)

## Strategic future extension — ToolHarbor Relay

ToolHarbor is researching an optional runtime component that could turn live API and agent traffic into safe, reproducible ToolHarbor artifacts.

- [Relay research overview](docs/future/relay/README.md)
- [Executive assessment](docs/future/relay/01-executive-assessment.md)
- [Landscape and existing solutions](docs/future/relay/03-landscape-and-existing-solutions.md)
- [Differentiation and product wedge](docs/future/relay/06-differentiation-and-product-wedge.md)
- [Validation MVP](docs/future/relay/12-validation-mvp.md)
- [Risks and kill criteria](docs/future/relay/15-risks-kill-criteria-and-open-questions.md)

Relay is not part of the current MVP and has not been approved for production implementation.

## Open-source governance and community

ToolHarbor uses an explicit open-source operating model:

- [Contributing guide](CONTRIBUTING.md)
- [Code of Conduct](CODE_OF_CONDUCT.md)
- [Security policy](SECURITY.md)
- [Governance](GOVERNANCE.md)
- [Maintainers](MAINTAINERS.md)
- [Support policy](SUPPORT.md)
- [Developer Certificate of Origin](DCO.md)
- [Trademark guidelines](TRADEMARKS.md)
- [AI-assisted contribution policy](AI_ASSISTED_CONTRIBUTIONS.md)
- [Governance documentation](docs/governance/README.md)
- [Community documentation](docs/community/README.md)
- [RFC process](docs/rfcs/README.md)

The project is licensed under the Apache License 2.0.

## Architecture decisions

- [ADR-0001: Initial product direction](docs/adr/0001-initial-product-direction.md)
- [ADR-0002: GitHub organization and monorepo](docs/adr/0002-github-organization-and-monorepo.md)
- [ADR-0003: MVP product surface](docs/adr/0003-mvp-product-surface.md)
- [ADR-0004: Open core and cloud boundaries](docs/adr/0004-open-core-and-cloud-boundaries.md)
- [ADR-0005: Modular monolith with ports and adapters](docs/adr/0005-modular-monolith-ports-and-adapters.md)
- [ADR-0006: Canonical YAML project format](docs/adr/0006-canonical-yaml-project-format.md)
- [ADR-0007: Python core and TypeScript UI boundary](docs/adr/0007-python-core-typescript-ui-boundary.md)
- [ADR-0008: Asynchronous runner and event model](docs/adr/0008-asynchronous-runner-event-model.md)
- [ADR-0009: Secret references and redaction boundary](docs/adr/0009-secret-references-redaction-boundary.md)
- [ADR-0010: Stable identifiers and versioned schemas](docs/adr/0010-stable-identifiers-versioned-schemas.md)
- [ADR-0011: Defer the public plugin runtime](docs/adr/0011-defer-public-plugin-runtime.md)
- [ADR-0012: Local results and no required telemetry](docs/adr/0012-local-results-no-required-telemetry.md)
- [ADR-0013: ToolHarbor Relay as an optional future data plane](docs/adr/0013-toolharbor-relay-optional-data-plane.md)
- [ADR-0014: Adopt Apache License 2.0](docs/adr/0014-adopt-apache-2.0.md)
- [ADR-0015: Use DCO 1.1](docs/adr/0015-use-dco-1.1.md)
- [ADR-0016: Founder-led, consensus-seeking governance](docs/adr/0016-founder-led-consensus-seeking-governance.md)
- [ADR-0017: Organization community defaults](docs/adr/0017-use-public-github-repository-for-community-defaults.md)
- [ADR-0018: GitHub Discussions](docs/adr/0018-use-github-discussions-for-questions-and-ideas.md)
- [ADR-0019: Private vulnerability reporting](docs/adr/0019-use-github-private-vulnerability-reporting.md)
- [ADR-0020: Squash merge and protected main](docs/adr/0020-use-squash-merge-and-protected-main.md)
- [ADR-0021: Executable workflows over API-client parity](docs/adr/0021-executable-workflows-not-api-client-parity.md)
- [ADR-0022: Developer-led bottom-up adoption](docs/adr/0022-developer-led-bottom-up-adoption.md)
- [ADR-0023: Interoperability over format lock-in](docs/adr/0023-interoperability-over-format-lock-in.md)
- [ADR-0024: Monetize coordination and managed execution](docs/adr/0024-monetize-coordination-and-managed-execution.md)
- [ADR-0025: Active repositories over vanity reach](docs/adr/0025-active-repositories-over-vanity-reach.md)
- [ADR-0026: Vendor-neutral AI engineering system](docs/adr/0026-vendor-neutral-ai-engineering-system.md)
- [ADR-0027: Human-authorized issue and PR workflow](docs/adr/0027-human-authorized-issue-pr-workflow.md)
- [ADR-0028: TDD and deterministic quality gates](docs/adr/0028-tdd-deterministic-quality-gates.md)
- [ADR-0029: Independent AI review before merge](docs/adr/0029-independent-ai-review-before-merge.md)
- [ADR-0030: GitHub and PR handoff as task state](docs/adr/0030-github-pr-handoff-task-state.md)

## License

ToolHarbor is licensed under the Apache License 2.0 unless a file states otherwise.

## Contributing

ToolHarbor welcomes scoped documentation, examples, conformance, and implementation contributions as corresponding milestones open.

Read:

- [CONTRIBUTING.md](CONTRIBUTING.md)
- [GOVERNANCE.md](GOVERNANCE.md)
- [SECURITY.md](SECURITY.md)
- [AI_ASSISTED_CONTRIBUTIONS.md](AI_ASSISTED_CONTRIBUTIONS.md)

Large or cross-cutting changes should begin with an issue or RFC.

## Maintainer

ToolHarbor was initiated by [Miguel Payá](https://github.com/mpaya5).
