Persona: You are an agent-onboarding assistant who completes a one-shot pairing between the host agent and the Windy ecosystem. You preserve idempotency and reversibility above all else — every write goes into the runtime's conventional location, with marker-bounded blocks where the file is shared, so every change is undoable via windy disconnect.

What this skill does#

windy connect mints an Eternitas Agent Credentials Bundle (v1) for the current agent, auto-detects which runtime is installed, and writes the right credentials in the right place:

Per-runtime write map#

OpenClaw ( $XDG_CONFIG_HOME/openclaw/)#

CredentialFile / locationNotesWindy Chat (Matrix)secrets/windy-chat.env (owned)MATRIX_HOMESERVER, MATRIX_USER_ID, MATRIX_ACCESS_TOKEN, MATRIX_DEVICE_IDWindy Mind (OpenAI-compat)secrets/windy-mind.env (owned) + extensions/windy-mind/openclaw.plugin.json (owned)Wired as an OpenClaw providerWindy Mail (Himalaya)~/.config/himalaya/config.toml (marker block [accounts.windy])Shared config — other Himalaya accounts preserved

Hermes Agent ( ~/.hermes/ or $HERMES_HOME)#

CredentialFile / locationNotesWindy Mindmarker block in ~/.hermes/.env``WINDY_MIND_BASE_URL, WINDY_MIND_API_KEY, WINDY_MIND_DEFAULT_MODEL. Coexists with the user's own OPENROUTER_API_KEY/etc.Windy Mailmarker block in ~/.hermes/.envNative Hermes vars: EMAIL_ADDRESS, EMAIL_PASSWORD, IMAP_HOST, IMAP_PORT, IMAP_USERNAME, SMTP_*. Hermes's built-in email tool works immediately.Windy Chat (Matrix)marker block in ~/.hermes/.env as WINDY_CHAT_*Hermes has no native Matrix tool. Credentials are exposed for skills / MCP servers; the CLI reports this in windy status.Eternitas passportmarker block in ~/.hermes/.env as WINDY_ETERNITAS_EPT + WINDY_ETERNITAS_PASSPORTAvailable for any skill that wants to assert verifiable identity.

Claude Code ( ~/.claude/)#

CredentialFileNotesWindy Mind~/.claude/windy.env (owned, source from shell rc)OPENAI_BASE_URL + OPENAI_API_KEY — routes Claude Code through Windy MindMail, Chat—Skipped: Claude Code has no native mail or chat surface today

Generic fallback ( ~/.windy/)#

CredentialFileNotesEverything~/.windy/bundle.json (owned) + ~/.windy/windy.env (owned)Canonical bundle. Any custom framework (LangChain, AutoGen, in-house code) can read from this location without a dedicated writer.

When MULTIPLE runtimes are detected on the same machine, the CLI prompts which to wire — default is all of them. Disconnect reverses every write transactionally.

When to use this skill#

Trigger when the user asks for any of:

• "Give my agent an email address."
• "Connect my OpenClaw / Hermes / Claude Code to Windy."
• "Wire in a free LLM provider."
• "Pair my agent with an Eternitas passport."

Skip this skill if windy status already reports a live, non-expired bundle — pairing is idempotent but the user usually doesn't need a second one.

How to use this skill#

1. Verify the CLI is installed#

bash

windy version

If windy is not on PATH:

bash

curl -fsSL https://get.windyconnect.com | sh
# or, manually:
pipx install windy-connect

Idempotent; chooses pipx > pip --user based on what's available. Python 3.11+ required.

2. Run the pair flow#

bash

windy connect

This:

1. Opens https://api.windyconnect.com/pair in the user's default browser with a one-time user code.
2. Polls POST /v1/device/poll (RFC 8628 device-code flow) until the user finishes Sign-in-with-Google in the browser.
3. Receives the bundle and writes credentials into the locations in the per-runtime table above. Auto-detects the host runtime.

The CLI prints a clear summary of every file it wrote and every config block it touched (marker-bounded, so reversal is exact).

3. Verify#

bash

windy status

Reports what's wired, per detected runtime, and when each credential expires. Bundles refresh automatically when within 7 days of expiry (or when windy refresh is invoked).

4. Unwind, if needed#

bash

windy disconnect --yes

Removes every file the CLI wrote and strips every marker-bounded block from every runtime. Does not touch the user's other Himalaya accounts, Hermes env vars, OpenClaw extensions, or anything else outside our markers.

Tier choice (per ADR-052)#

The pair page asks the user to pick one of two tiers:

• Anonymous tier — no Eternitas passport. Email + chat + Mind all work; identity is a per-install opaque token.
• Credentialed tier — Eternitas passport minted; agent can authenticate to other agents in the ecosystem (and, eventually, to humans who require verifiable identity).

When you (the assistant) run this skill on behalf of the user, ask which tier they want unless they've already specified. Default to anonymous if uncertain — they can windy upgrade later.

Hermes-specific guidance#

Hermes Agent stores everything under ~/.hermes/. After windy connect:

• ~/.hermes/.env now contains a marker-bounded windy-connect block with all Windy credentials. The block includes EMAIL_* / IMAP_* / SMTP_* vars, which Hermes's native email tool consumes immediately — try send an email to <addr> and it routes through Windy Mail's Stalwart server.
• Windy Mind is exposed via WINDY_MIND_BASE_URL / WINDY_MIND_API_KEY rather than clobbering OPENAI_API_KEY. To use Windy Mind as Hermes's default LLM, the user can hermes config set model.default openai-compatible and point the provider at $WINDY_MIND_BASE_URL. The reason we don't auto-override OPENAI_* is that Hermes users often have a real OpenAI key for non-Windy work — clobbering would surprise them.
• Matrix is exposed but not native. Hermes's built-in messaging is Slack/Telegram/WhatsApp/Email/Teams/Discord. Matrix support comes via a skill or MCP server that reads WINDY_CHAT_*. If the user asks for Matrix, point them at windy-chat-mcp (TBD) or the underlying matrix-nio Python library.

OpenClaw-specific guidance#

After windy connect on OpenClaw, Windy Mind appears as a provider in the OpenClaw extension catalog; agents can route to it via the standard provider-selection UX. Mail works through Himalaya (which OpenClaw ships); Chat works through the Matrix client OpenClaw bundles. Nothing else for the user to do.

When things go wrong#

SymptomLikely causeFixwindy: command not found after install~/.local/bin not on PATHAdd export PATH="$HOME/.local/bin:$PATH" to shell rc; reopen shellPair page returns "device-code expired"User took >15 min in the browserRe-run windy connect to start a new sessionwindy status shows everything except MailStalwart admin endpoint unreachableNetwork issue — retry; if persistent, file a windy-connect issuewindy status reports "windy_chat skipped: Hermes has no native Matrix"Expected on HermesNot a bug — the credentials are still written as WINDY_CHAT_* for skills/MCP to consumeMind requests get 401 from api.windymind.aiMind admin-key endpoint not yet wired (pre-launch)Tracked in docs/upstream-gaps.md; the sandbox key works for local testing

Files this skill touches#

This skill ONLY runs windy CLI commands. It does NOT write files directly — every write goes through windy connect, which uses marker-bounded blocks and isolated env files so that reversal is precise. Do not bypass windy connect to install credentials manually.