Metadata-Version: 2.5
Name: windy-connect
Version: 0.4.4
Summary: Wire any AI agent into the Windy ecosystem in one command.
Project-URL: Homepage, https://windyconnect.com
Project-URL: Source, https://github.com/sneakyfree/windy-connect
Author: Windy
License: MIT
License-File: LICENSE
Keywords: agent,ai,credentials,eternitas,imap,matrix,windy
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Communications :: Email
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: cryptography<49,>=43.0; platform_system == 'Darwin' and platform_machine == 'x86_64'
Requires-Dist: cryptography>=43.0; platform_system != 'Darwin' or platform_machine != 'x86_64'
Requires-Dist: httpx>=0.27.0
Requires-Dist: platformdirs>=4.0.0
Requires-Dist: pydantic>=2.6.0
Requires-Dist: rich>=13.7.0
Requires-Dist: typer>=0.12.0
Provides-Extra: dev
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff<0.17,>=0.16; extra == 'dev'
Description-Content-Type: text/markdown

# Windy Connect

**The one command that wires any AI agent into the Windy ecosystem.**

```bash
curl https://get.windyconnect.com | sh
windy connect
```

That's it. Confirm it's you — a magic link in your inbox, or Sign-in-with-Google. Your agent now has a chat identity, free LLM access, and (with a passport) an email address plus Eternitas credentials that let it talk to other agents across the agent web.

---

## What this is

Windy Connect is the **agent starter pack issuer** for the Windy ecosystem. One `windy connect` invocation does everything a user would otherwise have to do manually:

| Without Windy Connect | With Windy Connect |
|---|---|
| Go to Telegram → BotFather → /newbot → copy token → paste in OpenClaw config → restart | `windy connect` |
| Set up SMTP/IMAP credentials by hand | `windy connect` |
| Sign up for an LLM provider, generate API key, configure base URL | `windy connect` |
| Apply to Eternitas for a passport | `windy connect` (answer "yes" to the prompt) |

The CLI auto-detects which AI agent frameworks are installed (OpenClaw, Hermes, Claude Code, and a generic fallback any framework can read) and writes their respective config files to the right places.

## What gets provisioned

A credentialed `windy connect` run provisions four things. The free tier gets
three — see [Two-tier access](#two-tier-access) for what differs and why.

1. **Eternitas Passport (optional but recommended)** — a third-party JWT credential issued by [Eternitas](https://eternitas.ai), the independent State-Department-and-credit-bureau-for-AI-agents. With it, your agent can engage in agent-to-agent communication on Windy Chat, gets higher rate limits, and starts building an integrity score that compounds across every ecosystem that adopts the Eternitas standard.
2. **Windy Mail mailbox** — `<agent>@windymail.ai`, with IMAP/SMTP/JMAP credentials your agent can use to send and receive mail. **Credentialed tier only** — the free tier ships no mailbox rather than a mailbox that cannot send.
3. **Windy Chat identity** — a Matrix identity (`@<agent>:windychat.ai`) and access token your agent uses to chat with humans (and, with Eternitas, other agents).
4. **Windy Mind quota** — free LLM access via the OpenAI-compatible Windy Mind router (BYOM-capable, multiple providers behind one endpoint).

Since 0.4.4 the CLI also sends the machine's hardware facts to Eternitas after pairing (OS, architecture, CPU and GPU model, storage type and size, connection type, whether it is virtual, and the serial number over TLS; never a hostname, MAC, username, path or IP). Run `windy status` to see exactly what was sent, or set `WINDY_NO_HOUSING=1` to send nothing. It never delays or fails pairing.

All four are delivered as a single **Eternitas Agent Credentials Bundle** ([spec](docs/bundle-spec-v1.md)) that the CLI writes to wherever your agent expects it.

## Two-tier access

The Windy ecosystem follows the **two-tier-everywhere** principle (see [ADR-052](docs/adr/adr-052-two-tier-ecosystem-access-2026-05-20.md)):

| Tier | Who | What you get |
|---|---|---|
| **Tier 1 — Free** | Anyone | Mind quota, Chat identity (human-facing). **No mailbox** — a mailbox without a credentialed identity behind it can't be trusted to send, and a mailbox that silently fails is worse than none |
| **Tier 2 — Credentialed** | Anyone with an Eternitas passport | Everything in Tier 1 **plus** a real `@windymail.ai` mailbox, agent-to-agent comms on Chat, higher rate limits, EI-gated features, and a refreshable bundle |

`windy connect` asks once which tier you want. The Eternitas tier is the recommended default — it's how the agent web prevents spam at scale.

## Repo layout

```
windy-connect/
  src/windy_connect/      # Python CLI (published to PyPI as windy-connect)
  backend/                # Cloudflare Worker orchestrator (TypeScript)
  skills/windy-access/    # ClawHub skill (SKILL.md + README) — also bundled into the wheel
  tests/                  # pytest suite for the CLI
  docs/
    bundle-spec-v1.md     # The Eternitas Agent Credentials Bundle spec
    upstream-gaps.md      # Real-provisioning state per upstream service
    oauth-setup.md
    pypi-setup.md
    adr/                  # Architectural decision records
    dns-plan.md
  pyproject.toml
  README.md
```

The marketing site (windyconnect.com) lives in its own repo at
[`sneakyfree/windy-connect-site`](https://github.com/sneakyfree/windy-connect-site)
per the Windy ecosystem `<product>-site` convention.

## Orchestrator backend

The CLI talks to a stateless Cloudflare Worker that mints bundles via the device-code flow (RFC 8628), with the human confirming by magic link or Sign-in-with-Google. See [backend/README.md](backend/README.md) for the route map, real-vs-sandbox gating, secrets and deployment.

**Note on identity, and where this is going.** Today the Worker runs its *own*
login and derives a Connect-local identity, so an existing Windy account buys you
nothing here and the same person can end up with two unrelated agents.
[ADR-053](docs/adr/adr-053-federate-login-to-account-server-2026-08-10.md)
records the decision to federate login to the ecosystem identity provider at
`account.windyword.ai` — the same device-code flow Windy Code already uses — and
to hatch through its shared ledger. Cross-repo prerequisites are tracked in
[docs/ECOSYSTEM-INTEGRATION-REQUEST.md](docs/ECOSYSTEM-INTEGRATION-REQUEST.md).

Point the CLI at a non-default orchestrator with `WINDY_CONNECT_API_URL=https://your-orchestrator/...` — useful for staging or local `wrangler dev`.

## Status

**Live in production at `api.windyconnect.com`, with real provisioning on since 2026-07-02.** `windy connect` mints a real bundle against the deployed orchestrator: the human confirms by magic link (primary) or Sign-in-with-Google, and all four upstreams — Eternitas, Windy Mail, Windy Chat, Windy Mind — are wired for real.

**PyPI `latest` is 0.3.1 (2026-05-21) and `main` is ahead of it.** See `CHANGELOG.md` `[Unreleased]`; the Worker's live commit is at `GET /version`.

```bash
pip install windy-connect       # or `pip install -e .` from a checkout
windy connect                   # sign in, provision, write configs, persist state
windy status                    # show what's wired
windy doctor                    # run diagnostics against the current connection
windy refresh                   # renew credentials before they expire (same agent identity)
windy disconnect                # reverse everything cleanly
```

An offline `--mock` path exists for development. It is **gated behind
`WINDY_CONNECT_DEV=1`** and deliberately produces an anonymous-tier bundle with
no Eternitas block: it used to fabricate a realistic-looking passport and EPT and
write them into real agent configs, which is identity fabrication and is
forbidden — no lane may substitute a mock and report success.

State is persisted to `~/.windy/state.json` (mode 0600). Disconnect deletes owned files and strips marker-bounded blocks from shared config files (e.g., Himalaya's `config.toml`) without touching the user's other accounts.

Test suites:
- **CLI** — `pytest tests/` — 100 tests covering bundle parsing, state round-trip, every writer in dry-run + wet mode, value escaping, non-UTF-8 locale safety, the developer-mode gate, doctor diagnostics, refresh, and the full CLI lifecycle.
- **Worker** — `cd backend && npm test` (vitest) — 75 tests covering provisioning, the pre-flight secret check, the Eternitas platform key, magic-link signing/verification, rate limiting, status rollup, and Eternitas JWKS handling. `npx tsc --noEmit` is a gate and is clean.

The bundle spec is v1-draft. ADR-052 is Accepted (canonical home: `~/kit-army-config/docs/adr-052-two-tier-ecosystem-access-2026-05-20.md`).

## What's next

See the open issues / project board on GitHub. Wave-by-wave delivery status lives in [WAVE-STATUS.md](WAVE-STATUS.md).

Shipped foundations (0.x):
1. **`windy connect` CLI** — interactive flow, auto-detection of OpenClaw + Ollama + Claude Code + generic, writes configs to the right places
2. **Orchestrator backend** — Sign-in-with-Google → mints Eternitas EPT → provisions Mail mailbox → provisions Chat identity → returns the bundle (live at `api.windyconnect.com`)
3. **`get.windyconnect.com` installer** — one-line bootstrap that installs the CLI
4. **`windyconnect.com/pair` browser flow** — the page the CLI opens for the user to sign in
5. **OpenClaw ClawHub skill** — `windy-access` skill on ClawHub for discoverability inside the OpenClaw community

Real EPT verification against the Eternitas JWKS shipped in wave F. What remains
is integration rather than construction — see
[docs/upstream-gaps.md](docs/upstream-gaps.md) for current upstream state and
[docs/ECOSYSTEM-INTEGRATION-REQUEST.md](docs/ECOSYSTEM-INTEGRATION-REQUEST.md)
for the open cross-repo asks. The three that matter most:

1. **An Eternitas platform key**, so Connect stops calling the issuer
   anonymously. The code sends it the moment the secret exists.
2. **Registration as an OAuth client** of `account.windyword.ai`, so an existing
   Windy login works here (ADR-053).
3. **A shared hatch ledger**, so Connect's agents are on the record like every
   other hatched agent — the honest fix for being a fifth hallway.

## Naming

- **Product name:** Windy Connect
- **CLI command:** `windy connect` (subcommand of the `windy` binary; future siblings: `windy status`, `windy disconnect`, `windy upgrade`)
- **Repo:** `windy-connect` (this repo)
- **Domain:** windyconnect.com (CLI installer + browser pairing page + marketing)
- **PyPI package:** `windy-connect`
- **Dashboard tile:** "Windy Connect"

## License

MIT for the entire repo (CLI + Worker backend + skill). See [`LICENSE`](LICENSE).
The marketing site is also MIT — see [`sneakyfree/windy-connect-site`](https://github.com/sneakyfree/windy-connect-site).
