🪰 Windy Fly

Your AI. Your Rules. Your Ecosystem.

Windy Fly is a personal AI agent — a lifelong, self-improving companion that remembers everything, learns your preferences, and connects to the entire Windy ecosystem. Talk to it from your terminal, phone, browser, or any messaging platform.

pip install windyfly    # official release (0.7.1+) — the brain + every chat channel
windy go                # opens the hatch ceremony in your browser

The PyPI wheel is the headless brain (no web dashboard). For the full product with the dashboard, run it from a source checkout, either windy go or docker compose up -d --build, which builds the image locally from the Dockerfile. There is no published Docker image yet. See docs/DISTRIBUTION.md.

0.7.1: set your Telegram owner explicitly (AGENT_OWNER_TELEGRAM_ID=<your numeric id>). Older releases defaulted it to a maintainer's account. See CHANGELOG.md.

Your agent hatches, gets an identity, and starts chatting in under 2 minutes.

0.7.3: windy go opens the one Windy hatch ceremony. It prints a link and a short code (Open this to hatch your agent: <link> (code ABCD-1234)) and opens your browser. Check the code matches, name your agent, and at "It's alive!" the terminal prints where to say hi in Windy Chat. Your agent is born in the Windy cloud and lives there; windy bring-home (run it on this machine) is coming soon. WINDY_HATCH_VIA_HUB=0 keeps the old terminal hatch for this one release.

Features

Quickstart

From Source (Developers)

git clone https://github.com/sneakyfree/windy-agent && cd windy-agent
uv sync                    # Install dependencies
uv run windy go            # Hatch in the browser ceremony (link + code)

From PyPI (headless — no dashboard)

pip install windyfly        # 0.7.1+ (set AGENT_OWNER_TELEGRAM_ID for Telegram)
windy go                   # Hatch in the browser ceremony (link + code)
windy start                # Start the agent (brain + channels only)

The wheel ships the Python brain and every channel adapter, but NOT the gateway/dashboard (that's a Bun/TypeScript app that lives in the source checkout). Want the full product? Use a source checkout: windy go, or docker compose up -d --build to build the image yourself. Details: docs/DISTRIBUTION.md.

What Happens

1. Link + code — windy go signs you in with your Windy account, prints the ceremony link and a short code, and opens your browser
2. Hatch — check the code, name your agent, and it comes alive with the "It's alive! It's alive! The fly is alive!" ceremony, born in the Windy cloud
3. Chat — the terminal prints "Say hi: "; windy bring-home (run the agent on this machine) is coming soon (With WINDY_HATCH_VIA_HUB=0, this release still runs the old terminal hatch: paste an API key, hatch locally, chat in the terminal or dashboard.)
4. Enjoy — ask about the weather, set reminders, manage to-dos, search the web

Commands

Everyday

Tools (via chat or slash commands)

Agent Management

Architecture

┌─────────────────────────────────────────────────────────────┐
│  Dashboard (React + Vite + Tailwind)  ← localhost:3000      │
├─────────────────────────────────────────────────────────────┤
│  Gateway (Bun/TypeScript)  ← 50+ REST/WS API endpoints     │
├─────────────────────────────────────────────────────────────┤
│  Brain (Python 3.12+)  ← LLM orchestration, tools, memory  │
├─────────────────────────────────────────────────────────────┤
│  Memory (SQLite + FTS5 + sqlite-vec)  ← one file, zero ops  │
└─────────────────────────────────────────────────────────────┘

Configuration

All config lives in windyfly.toml:

[agent]
name = "Windy Fly"
default_model = "kimi-k2.5"

[personality]
preset = "buddy"          # buddy, engineer, powerhouse, coder, friend
warmth = 9
humor = 7

[costs]
daily_budget_usd = 5.0

[ecosystem]
eternitas_url = "https://api.eternitas.ai"
windy_mail_url = "https://api.windymail.ai"
matrix_homeserver = "https://chat.windychat.ai"
windy_cloud_url = "https://cloud.windycloud.com"

Environment Variables

Secrets go in .env (never committed):

OPENAI_API_KEY=sk-...          # Required: at least one LLM key
ANTHROPIC_API_KEY=sk-ant-...   # Optional: for Claude models
BRAVE_SEARCH_API_KEY=...       # Optional: better web search (free at brave.com/search/api)

Ecosystem

Windy Fly connects to the full Windy product suite:

Check connectivity: windy ecosystem

Eternitas Trust Gate

Every sensitive action — send_email, post_chat_message, run_command, install_package, commit_push, upload_file — is gated by the live Eternitas Trust API before it hits the network.

Contract: /Users/thewindstorm/eternitas/docs/trust-api.md is the authoritative consumer reference. Endpoint: GET {ETERNITAS_URL}/api/v1/trust/{passport_number} — public, no auth, 100 req/min/IP, 5-min server cache. Responses carry status, band (exceptional/good/fair/poor/critical), clearance_level, tier_multiplier, allowed_actions, and cache_ttl_seconds. Windy Fly mirrors the TTL in a local SQLite cache and subscribes to trust.changed webhooks to flush on band flip or clearance promotion.

Env vars:

Agent-gate → Eternitas vocabulary:

Running the live integration tests:

# Terminal 1 — start Eternitas
cd /Users/thewindstorm/eternitas
./scripts/dev-start.sh

# Terminal 2 — run the live tests
cd /Users/thewindstorm/windy-agent
ETERNITAS_URL=http://localhost:8200 \
ETERNITAS_USE_MOCK=false \
WINDYFLY_TEST_PASSPORT_EXCEPTIONAL=<exceptional-band passport> \
WINDYFLY_TEST_PASSPORT_CRITICAL=<critical-band passport> \
uv run pytest tests/integration/test_trust_live.py -v

Tests skip automatically when the API isn't reachable.

Telemetry and privacy

Windy Fly sends anonymous health data to Windy so we can see when agents are failing in the field: error codes, counts and durations. It never sends your messages, prompts, files, names or email addresses. You're told this once, when your agent is born or the first time you run windy login or windy go, and nothing is sent before that.

• See or change it: windy telemetry status|on|off, or WINDY_TELEMETRY=0 (in your shell or the agent's .env).
• What's sent: service.boot (version, install type), service.health every 15 minutes (turn/tool/error counts, p95 turn time, lifeboat turns), agent.run_failed (one per turn where you got no real answer, with a code such as rate_limited), agent.model_demoted (when your agent falls back to a weaker or local model), and llm.call (tokens and list-price cost).
• Whose it is: rows are signed with your agent's own passport token and filed under its passport number. An agent without a passport sends nothing.

Details: docs/PRIVACY.md.

Development

# Run tests (~1100 offline + 27 live-Eternitas integration)
uv run pytest tests/ -v
uv run pytest tests/integration/ -v   # needs Eternitas at ETERNITAS_URL

# Lint
uv run ruff check src/

# Build package
uv build

# Release (maintainers only)
./scripts/release.sh 0.6.0    # Bumps version, tags, pushes → PyPI

Project Stats

• 1100+ tests | 0 failures (includes contract, integration, stress)
• 22 LLM-callable tools
• 101 DNA codons | 100% implemented
• 8-page React dashboard
• 9 messaging channels supported

License

Proprietary — (C) 2026 WindyLabs. All rights reserved.

"If you have one copy of the DNA, you can recreate the entire organism."