Windy Connect

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

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:

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 for what differs and why.

1. Eternitas Passport (optional but recommended) — a third-party JWT credential issued by Eternitas, 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).

All four are delivered as a single Eternitas Agent Credentials Bundle (spec) 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):

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 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 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 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.

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.

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.

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 for current upstream state and 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. The marketing site is also MIT — see sneakyfree/windy-connect-site.