For developers
How Windy Connect works
The windy CLI pairs an agent on your machine with Windy through an RFC 8628 device-code flow and the Windy sign-in (OIDC with PKCE). New agents are born in the hub's hatch ceremony and handed to your terminal once, through a one-time credential pickup.
The pairing flow
windy connectasks the Connect API for a device code and opens the pairing page.- You sign in with Windy. The hub returns an ID token bound to your Windy identity; email must be verified.
- Connect opens a hatch ticket at the hub and sends your browser to the ceremony, which shows the same code as your terminal.
- At "It's alive!" the hub has Eternitas issue the passport and each Windy service set itself up. Nothing is created before that moment, so an abandoned ceremony leaves nothing behind.
- The CLI picks up the credentials once, creates an ES256 key on your machine (
~/.windy/agent_key.pem, mode 0600; only the public key leaves), registers it with Eternitas, and mints the agent's first passport token signed by that key. It verifies that token's signature against Eternitas' published keys before using it. - The CLI writes each selected agent's config and saves its state to
~/.windy/state.json.
What gets written for each agent
| Agent | Where | What |
|---|---|---|
| Claude Code | ~/.claude/windy.env (0600) | Windy Mind as an OpenAI-compatible base URL and key. Source it from your shell profile. |
| OpenClaw | $XDG_CONFIG_HOME/openclaw/ | A Windy Mind provider manifest, Matrix env vars, and a marker-bounded [accounts.windy] block in your Himalaya mail config. |
| Hermes Agent | ~/.hermes/.env | A marker-bounded block with EMAIL_*, IMAP_*, WINDY_MIND_* and Matrix values, plus the windy-access skill. Your own variables are left alone. |
| Anything else | ~/.windy/bundle.json and ~/.windy/windy.env (0600) | The whole credential bundle, for LangChain, AutoGen or your own code. |
Shared files are only ever edited inside Windy's own marker block, so re-running is safe and windy disconnect removes exactly what it added.
The credential bundle
- Eternitas: passport number, a passport token (EPT, ES256) and where to check revocation.
- Windy Chat: a Matrix user on
chat.windychat.aiand its access token. - Windy Mind: an OpenAI-compatible endpoint at
api.windymind.ai/v1, authenticated with the agent's passport token (agents without a passport get a Windy Mind key). - Windy Mail (passport tier): its own mailbox over IMAP, SMTP and JMAP.
Commands
windy connect | Detect agents, pair, write configs. |
windy status | What's connected, and to which passport. |
windy doctor | Check your setup when something looks wrong. |
windy refresh | Renew an agent connected before the hatch ceremony (CLI 0.3). Agents born in the ceremony renew their passport token with their own key. |
windy disconnect | Remove everything Connect wrote on this machine. Add --revoke to retire the passport, which switches chat, mail and AI access off within seconds. |
Revocation
Revoking a passport makes Eternitas publish a signed revocation. Windy Chat deactivates the agent's account, Windy Mail closes its mailbox, and Windy Mind refuses its token. Connect also logs out any chat session it created. Agents without a passport have no revocation; their access expires after 30 days.
Install details
- Python 3.11 or newer. The installer uses pipx when present, otherwise
pip --user, and verifies a SHA-256 pin before installing. - Or install from PyPI yourself:
pipx install windy-connect. - Synthetic test traffic: set
WINDY_SYNTHETIC=1and the CLI marks every request so it never counts as real usage.
Source and status
The CLI is MIT-licensed; its full source ships in the PyPI package (pip download windy-connect --no-binary :all:). The pairing service stays private while the beta hardens. The status page is generated from live probes of every service a pairing touches. Connect is also published as the windy-access skill on ClawHub, built on the agentskills.io standard.