🪰 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                # setup wizard + hatch ceremony

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.

Features

Quickstart

From Source (Developers)

git clone https://github.com/sneakyfree/windy-agent && cd windy-agent
uv sync                    # Install dependencies
uv run windy go            # Interactive setup + hatch

From PyPI (headless — no dashboard)

pip install windyfly        # 0.7.1+ (set AGENT_OWNER_TELEGRAM_ID for Telegram)
windy go                   # Setup wizard
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. Setup — paste your API key (OpenAI, Anthropic, xAI, or others)
2. Hatch — your agent comes alive with the "IT'S ALIVE!" ceremony
3. Chat — talk in terminal, or open the dashboard at http://localhost:3000
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.

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