hyperclaw 5.0.0 → 5.0.1

package/README.md

@@ -1,40 +1,55 @@
-<p align="center">
-  <img src="assets/icon.png" width="120" alt="HyperClaw">
-  <br>
-  <h1 align="center">🦅 HyperClaw — Personal AI Assistant</h1>
-</p>
+<div align="center">
+  <img src="assets/icon.png" width="140" alt="HyperClaw">
+  <h1>🦅 HyperClaw</h1>
+  <p><strong>Your personal AI assistant — running on your hardware, talking on your channels.</strong></p>
+  <p><em>One command to install. Works on Telegram, Discord, WhatsApp, Signal, iMessage and 25+ more.</em></p>
+</div>
 
 <p align="center">
-  <img src="https://img.shields.io/badge/build-passing-brightgreen?style=flat-square" alt="build">
-  <img src="https://img.shields.io/badge/release-v5.0.0-blue?style=flat-square" alt="release">
-  <img src="https://img.shields.io/badge/node-%E2%89%A522-green?style=flat-square" alt="node">
-  <img src="https://img.shields.io/badge/license-MIT-gray?style=flat-square" alt="license">
+  <a href="https://github.com/mylo-2001/hyperclaw/stargazers"><img src="https://img.shields.io/github/stars/mylo-2001/hyperclaw?style=flat-square&logo=github&color=yellow" alt="GitHub Stars"></a>
+  <a href="https://github.com/mylo-2001/hyperclaw/network/members"><img src="https://img.shields.io/github/forks/mylo-2001/hyperclaw?style=flat-square&logo=github" alt="GitHub Forks"></a>
+  <a href="https://www.npmjs.com/package/hyperclaw"><img src="https://img.shields.io/npm/dw/hyperclaw?style=flat-square&logo=npm&color=red" alt="npm downloads"></a>
+  <a href="https://www.npmjs.com/package/hyperclaw"><img src="https://img.shields.io/npm/v/hyperclaw?style=flat-square&logo=npm&label=npm" alt="npm version"></a>
+  <a href="https://github.com/mylo-2001/hyperclaw/actions"><img src="https://img.shields.io/github/actions/workflow/status/mylo-2001/hyperclaw/secrets-scan.yml?branch=main&style=flat-square&label=CI" alt="CI"></a>
+  <img src="https://img.shields.io/badge/node-%E2%89%A522-green?style=flat-square&logo=node.js" alt="node">
   <img src="https://img.shields.io/badge/typescript-5.4-3178c6?style=flat-square&logo=typescript&logoColor=white" alt="typescript">
-  <img src="https://img.shields.io/badge/security-ethical%20hacking-red?style=flat-square&logo=hackthebox&logoColor=white" alt="security">
+  <img src="https://img.shields.io/badge/license-MIT-gray?style=flat-square" alt="license">
+  <img src="https://img.shields.io/badge/platforms-Windows%20%7C%20macOS%20%7C%20Linux-blue?style=flat-square" alt="platforms">
 </p>
 
 <p align="center">
-  <strong>HyperClaw</strong> is a personal AI assistant you run on your own devices.<br>
-  It answers you on the channels you already use — Telegram, Discord, WhatsApp, Slack, Signal, iMessage,<br>
-  Matrix, IRC, Mattermost, Google Chat, Microsoft Teams, Nostr, and more.<br>
-  It can speak and listen on macOS/iOS/Android, and render a live Canvas you control.<br>
-  The Gateway is just the control plane — the product is the assistant.
+  <a href="docs/README.md">📚 Docs</a> ·
+  <a href="docs/architecture.md">🏗 Architecture</a> ·
+  <a href="docs/configuration.md">⚙️ Config</a> ·
+  <a href="docs/security.md">🔒 Security</a> ·
+  <a href="docs/sandboxing.md">🐳 Sandboxing</a> ·
+  <a href="docs/tlon.md">🌊 Tlon</a> ·
+  <a href="docs/google-chat.md">💬 Google Chat</a> ·
+  <a href="CONTRIBUTING.md">🤝 Contributing</a>
 </p>
 
-<p align="center">
-  <em>If you want a personal, single-user assistant that feels local, fast, and always-on, this is it.</em><br>
-  <em>Built for developers, security researchers, and power users who want full control.</em>
-</p>
+---
 
-<p align="center">
-  <a href="docs/README.md">Docs</a> ·
-  <a href="docs/architecture.md">Architecture</a> ·
-  <a href="docs/configuration.md">Configuration</a> ·
-  <a href="docs/security.md">Security</a> ·
-  <a href="docs/deployment.md">Docker</a> ·
-  <a href="docs/tailscale.md">Tailscale</a> ·
-  <a href="CONTRIBUTING.md">Contributing</a>
-</p>
+> **"One `npm install -g hyperclaw` and your AI is live on Telegram."**
+
+---
+
+## Why HyperClaw?
+
+| Feature | HyperClaw | Cloud assistants | Self-hosted alternatives |
+|---------|:---------:|:----------------:|:------------------------:|
+| Runs on your own hardware | ✅ | ❌ | ✅ |
+| No subscription / pay-per-token only | ✅ | ❌ | ✅ |
+| 28+ messaging channels built-in | ✅ | ❌ | ⚠️ few |
+| Windows native (no WSL) | ✅ | — | ❌ |
+| Config hot-reload (no restart) | ✅ | — | ❌ |
+| Built-in security audit (`--fix`) | ✅ | — | ❌ |
+| DM pairing / allowlist by default | ✅ | — | ⚠️ manual |
+| Voice (TTS + STT) | ✅ | ✅ | ⚠️ |
+| Docker sandbox for agent tools | ✅ | — | ⚠️ |
+| MCP (Model Context Protocol) | ✅ | ⚠️ | ⚠️ |
+| One-command wizard (`hyperclaw onboard`) | ✅ | — | ❌ |
+| OSINT / Ethical hacking mode (`hyperclaw osint`) | ✅ | ❌ | ❌ |
 
 ---
 
@@ -53,65 +68,52 @@
 
 ---
 
-## Install
+## 🚀 Get started in 60 seconds
 
-Runtime: Node ≥ 22. Runs **natively on Windows, macOS, and Linux** — no WSL2 required.
+**Requires Node ≥ 22.** Runs natively on Windows, macOS, and Linux — no WSL2 required.
 
 ```bash
+# Install
 npm install -g hyperclaw@latest
-# or: pnpm add -g hyperclaw@latest
 
-# First-time setup wizard
+# Run the interactive setup wizard
 hyperclaw onboard
-
-# Or install with daemon (auto-start on boot, full PC access)
+# Run the interactive setup wizard with deamon
 hyperclaw onboard --install-daemon
 ```
 
-## Uninstall
+The wizard walks you through: AI provider → model → channels → skills. Done.
 
 ```bash
-# Stop and remove daemon (if running)
-hyperclaw daemon uninstall
+# After setup, start your assistant
+hyperclaw daemon start
 
-# Remove the package
-npm uninstall -g hyperclaw
+# Send a test message
+hyperclaw agent --message "What can you do?"
 
-# Remove config and data (optional)
-rm -rf ~/.hyperclaw
+# Health check
+hyperclaw doctor
 ```
 
-> **Windows users**: HyperClaw runs natively via Node.js. No WSL2, no admin rights needed.
-> The daemon uses **Task Scheduler** and runs as your user account with full desktop access.
-
-The wizard guides you step by step — provider, model, gateway, channels, and skills.
-Works on **macOS, Linux, and Windows** (native — no WSL2 required). Compatible with npm, pnpm, and bun.
-
----
+> **Windows**: No WSL2, no admin rights needed. The daemon uses Task Scheduler and runs as your account.
 
-## Quick start
+<details>
+<summary>More install options</summary>
 
 ```bash
-# 1. Run the onboarding wizard (first time)
-hyperclaw onboard
-
-# 2a. Start the gateway in foreground
-hyperclaw gateway --port 18789 --verbose
-
-# 2b. Or run as a background daemon (auto-start on boot)
-hyperclaw daemon start
-
-# 3. Talk to your assistant
-hyperclaw agent --message "What can you do?"
+# pnpm
+pnpm add -g hyperclaw@latest
 
-# 4. Security / bug bounty — run recon from your phone
-# Just message your Telegram bot: "search HackerOne for targets on acme.com"
+# Install with daemon (auto-start on boot + full PC access)
+hyperclaw onboard --install-daemon
 
-# 5. Check status
-hyperclaw doctor
+# Uninstall
+hyperclaw daemon uninstall
+npm uninstall -g hyperclaw
+rm -rf ~/.hyperclaw   # optional — removes config and data
 ```
 
-Upgrading? Run `hyperclaw doctor` to check and migrate.
+</details>
 
 ---
 
@@ -148,6 +150,7 @@ HyperClaw connects to the channels you already use (28+ channels):
 | 📧 Email | ✅ Available | SMTP + IMAP |
 | 🎙️ Voice Call | ✅ Available | Terminal voice session |
 | 🌐 Chrome Extension | ✅ Available | Browser sidebar |
+| 🌊 Tlon (Urbit Groups) | ✅ Available | Decentralized — see [docs/tlon.md](docs/tlon.md) |
 
 Twitch is also available via IRC over WebSocket.
 
@@ -229,6 +232,47 @@ Or use OpenRouter (access to all models with one key):
 
 Full reference: [docs/configuration.md](docs/configuration.md)
 
+### Config hot reload
+
+The gateway watches `~/.hyperclaw/hyperclaw.json` and applies changes automatically — no restart needed for most settings:
+
+```json
+{
+  "gateway": {
+    "reload": { "mode": "hybrid", "debounceMs": 300 }
+  }
+}
+```
+
+| Mode | Behavior |
+|------|----------|
+| `hybrid` _(default)_ | Hot-applies safe changes, auto-restarts for critical ones |
+| `hot` | Hot-applies only — warns when a restart is needed |
+| `restart` | Restarts on any change |
+| `off` | Disables file watching |
+
+### Reverse proxy / trustedProxies
+
+If you run behind Nginx, Caddy, or Cloudflare Tunnel, set `trustedProxies` so the gateway resolves the real client IP from `X-Forwarded-For`:
+
+```json
+{
+  "gateway": {
+    "trustedProxies": ["127.0.0.1", "10.0.0.0/8"]
+  }
+}
+```
+
+### DM scope isolation
+
+Isolate DM sessions per channel/peer (useful when multiple people share one gateway):
+
+```json
+{
+  "session": { "dmScope": "per-channel-peer" }
+}
+```
+
 ---
 
 ## Security defaults
@@ -242,7 +286,14 @@ HyperClaw connects to real messaging surfaces. Inbound DMs are treated as untrus
 - Set `dmPolicy: "open"` only if you want anyone to reach your assistant.
 - Non-main sessions (groups/channels) can run in Docker sandboxes: `agents.defaults.sandbox.mode: "non-main"`
 
-Run `hyperclaw doctor` to surface risky/misconfigured policies.
+Run the security audit regularly:
+
+```bash
+hyperclaw security audit           # standard scan
+hyperclaw security audit --deep    # live gateway probe
+hyperclaw security audit --fix     # auto-fix safe issues
+hyperclaw security audit --json    # machine-readable output
+```
 
 Full guide: [docs/security.md](docs/security.md)
 
@@ -251,7 +302,8 @@ Full guide: [docs/security.md](docs/security.md)
 ## Features
 
 - **Local-first Gateway** — single control plane for sessions, channels, tools, and events
-- **Multi-channel inbox** — 27+ channels, unified session model
+- **Config hot reload** — gateway watches `~/.hyperclaw/hyperclaw.json`, hot-applies changes (hybrid/hot/restart/off)
+- **Multi-channel inbox** — 28+ channels, unified session model
 - **Multi-agent routing** — route channels/accounts to isolated agent workspaces
 - **Extended thinking** — Claude extended thinking with `/think high` in chat
 - **Voice** — Talk Mode with ElevenLabs TTS + system TTS fallback
@@ -379,6 +431,18 @@ Sandbox image (no PC access, restricted tools):
 docker build -f Dockerfile.sandbox -t hyperclaw:sandbox .
 ```
 
+Or use **Docker Compose** for the full stack (gateway + browser sandbox):
+
+```bash
+# Copy and fill in your API keys
+cp env.example .env
+
+# Start gateway + sandbox
+docker compose --profile full up -d
+```
+
+See [`docker-compose.yml`](docker-compose.yml) and [`env.example`](env.example) for all options.
+
 ---
 
 ## Monorepo structure
@@ -398,7 +462,7 @@ hyperclaw/
 │   ├── media/              # Voice, TTS, STT, audio
 │   ├── routing/            # Session routing + multi-agent dispatch
 │   ├── security/           # Auth, sandboxing, DM policy
-│   └── …                  # (sdk, types, webhooks, logging, plugins…)
+│   └── …                   # (sdk, types, webhooks, logging, plugins…)
 ├── packages/
 │   ├── core/               # Inference engine, agent loop
 │   ├── gateway/            # Gateway package (standalone)
@@ -419,9 +483,80 @@ hyperclaw/
 
 ---
 
+## Documentation
+
+| Topic | File |
+|-------|------|
+| **Getting started** | [docs/README.md](docs/README.md) |
+| Architecture overview | [docs/architecture.md](docs/architecture.md) |
+| Configuration reference | [docs/configuration.md](docs/configuration.md) |
+| Environment variables | [docs/environment.md](docs/environment.md) |
+| API keys guide | [docs/API-KEYS-README.md](docs/API-KEYS-README.md) |
+| OAuth providers | [docs/oauth-providers.md](docs/oauth-providers.md) |
+| **Security** | [docs/security.md](docs/security.md) · [SECURITY.md](SECURITY.md) |
+| Deployment / Docker | [docs/deployment.md](docs/deployment.md) |
+| Tailscale remote access | [docs/tailscale.md](docs/tailscale.md) |
+| Remote gateway setup | [docs/remote-gateway-setup.md](docs/remote-gateway-setup.md) |
+| Multi-agent routing | [docs/multi-agent.md](docs/multi-agent.md) |
+| Session management | [docs/session-management.md](docs/session-management.md) |
+| Sandboxing (Docker isolation) | [docs/sandboxing.md](docs/sandboxing.md) |
+| MCP (Model Context Protocol) | [docs/mcp.md](docs/mcp.md) |
+| OSINT / Ethical Hacking mode | [docs/osint.md](docs/osint.md) |
+| Voice / Talk Mode | [docs/voice.md](docs/voice.md) |
+| Canvas (A2UI) | [docs/canvas-a2ui.md](docs/canvas-a2ui.md) |
+| Browser control | [docs/browser.md](docs/browser.md) |
+| **Channel guides** | |
+| Telegram | [docs/telegram.md](docs/telegram.md) |
+| Discord | [docs/discord-setup.md](docs/discord-setup.md) |
+| WhatsApp | [docs/whatsapp.md](docs/whatsapp.md) |
+| Slack | [docs/slack.md](docs/slack.md) |
+| Google Chat | [docs/google-chat.md](docs/google-chat.md) |
+| Tlon (Urbit Groups) | [docs/tlon.md](docs/tlon.md) |
+| Matrix | [docs/matrix.md](docs/matrix.md) |
+| Zalo / Zalo Personal | [docs/zalo.md](docs/zalo.md) · [docs/zalo-personal.md](docs/zalo-personal.md) |
+| LINE | [docs/line.md](docs/line.md) |
+| Nostr | [docs/nostr.md](docs/nostr.md) |
+| Nextcloud Talk | [docs/nextcloud-talk.md](docs/nextcloud-talk.md) |
+| Microsoft Teams | [docs/msteams.md](docs/msteams.md) |
+| Twitch | [docs/twitch.md](docs/twitch.md) |
+| iMessage (BlueBubbles) | [docs/imessage-native.md](docs/imessage-native.md) |
+| **Apps** | |
+| Mobile & Desktop apps | [docs/mobile-desktop-apps.md](docs/mobile-desktop-apps.md) |
+| Mobile nodes (iOS/Android) | [docs/mobile-nodes.md](docs/mobile-nodes.md) |
+| macOS remote control | [docs/macos-remote-control.md](docs/macos-remote-control.md) |
+| **Help** | |
+| FAQ | [docs/faq.md](docs/faq.md) |
+| Troubleshooting | [docs/troubleshooting.md](docs/troubleshooting.md) |
+| Contributing | [docs/contributing.md](docs/contributing.md) |
+
+---
+
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. AI/vibe-coded PRs welcome! 🤖
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. AI/vibe-coded PRs welcome!
+
+Found a bug? [Open an issue](https://github.com/mylo-2001/hyperclaw/issues/new/choose).  
+Found a vulnerability? Email [securityhyperclaw.ai@gmail.com](mailto:securityhyperclaw.ai@gmail.com) — we respond within 48 h.
+
+---
+
+## Community
+
+| | |
+|--|--|
+| 💬 **Discussions** | [GitHub Discussions](https://github.com/mylo-2001/hyperclaw/discussions) — questions, ideas, show & tell |
+| 🐛 **Bug reports** | [GitHub Issues](https://github.com/mylo-2001/hyperclaw/issues) — templates for bugs & features |
+| 🔒 **Security** | [SECURITY.md](SECURITY.md) — responsible disclosure |
+
+---
+
+<div align="center">
+
+**If HyperClaw is useful to you, a ⭐ helps others find it.**
+
+[![Star on GitHub](https://img.shields.io/github/stars/mylo-2001/hyperclaw?style=social)](https://github.com/mylo-2001/hyperclaw)
+
+</div>
 
 ---
 

package/dist/api-keys-guide-CGn5BSF7.js

@@ -0,0 +1,149 @@
+const require_chunk = require('./chunk-jS-bbMI5.js');
+
+//#region src/infra/api-keys-guide.ts
+const API_KEYS_GUIDE = [
+	{
+		serviceId: "anthropic",
+		name: "Anthropic (Claude)",
+		envVar: "ANTHROPIC_API_KEY",
+		url: "platform.anthropic.com",
+		setupSteps: [
+			"1. Go to platform.anthropic.com → API Keys.",
+			"2. Sign up / sign in with an Anthropic account.",
+			"3. Create Key — copy it (starts with sk-ant-). Not shown again!",
+			"",
+			"  🔗 platform.anthropic.com/settings/keys"
+		]
+	},
+	{
+		serviceId: "openai",
+		name: "OpenAI (GPT)",
+		envVar: "OPENAI_API_KEY",
+		url: "platform.openai.com",
+		setupSteps: [
+			"1. Go to platform.openai.com → API keys.",
+			"2. Create new secret key — copy it (starts with sk-). Not shown again!",
+			"3. You need billing enabled for production use.",
+			"",
+			"  🔗 platform.openai.com/api-keys"
+		]
+	},
+	{
+		serviceId: "openrouter",
+		name: "OpenRouter",
+		envVar: "OPENROUTER_API_KEY",
+		url: "openrouter.ai",
+		setupSteps: [
+			"1. Go to openrouter.ai → Keys.",
+			"2. Sign in (Google/GitHub).",
+			"3. Create Key — copy it. OpenRouter provides access to many models (Claude, GPT etc.).",
+			"",
+			"  🔗 openrouter.ai/keys"
+		]
+	},
+	{
+		serviceId: "tavily",
+		name: "Tavily (Web Search)",
+		envVar: "TAVILY_API_KEY",
+		url: "tavily.com",
+		setupSteps: [
+			"1. Go to tavily.com → Sign up.",
+			"2. Dashboard → API Keys → Create API Key.",
+			"3. Copy the key. Used for the web-search skill.",
+			"",
+			"  🔗 app.tavily.com"
+		]
+	},
+	{
+		serviceId: "elevenlabs",
+		name: "ElevenLabs (TTS)",
+		envVar: "ELEVENLABS_API_KEY",
+		url: "elevenlabs.io",
+		setupSteps: [
+			"1. Go to elevenlabs.io → Profile → API Key.",
+			"2. Copy the API key (or create a new one).",
+			"3. Used for talk mode (voice responses).",
+			"",
+			"  🔗 elevenlabs.io/app/settings/api-keys"
+		]
+	},
+	{
+		serviceId: "deepl",
+		name: "DeepL (Translation)",
+		envVar: "DEEPL_API_KEY",
+		url: "deepl.com",
+		setupSteps: [
+			"1. Go to deepl.com/pro-api → Get API key.",
+			"2. Sign up (free tier available).",
+			"3. Account → API keys — copy the Authentication Key.",
+			"",
+			"  🔗 deepl.com/pro-api"
+		]
+	},
+	{
+		serviceId: "github",
+		name: "GitHub (PAT)",
+		envVar: "GITHUB_TOKEN",
+		url: "github.com",
+		setupSteps: [
+			"1. GitHub → Settings → Developer settings → Personal access tokens.",
+			"2. Generate new token (classic or fine-grained).",
+			"3. Select scopes: repo, read:user etc. depending on use case.",
+			"",
+			"  🔗 github.com/settings/tokens"
+		]
+	},
+	{
+		serviceId: "xai",
+		name: "xAI (Grok)",
+		envVar: "XAI_API_KEY",
+		url: "x.ai",
+		setupSteps: [
+			"1. Go to console.x.ai → API keys.",
+			"2. Sign in and create a new key.",
+			"3. Copy the key.",
+			"",
+			"  🔗 console.x.ai"
+		]
+	},
+	{
+		serviceId: "google",
+		name: "Google AI (Gemini)",
+		envVar: "GOOGLE_AI_API_KEY",
+		url: "ai.google.dev",
+		setupSteps: [
+			"1. Go to aistudio.google.com/apikey.",
+			"2. Get API key or Create API key.",
+			"3. Copy the key.",
+			"",
+			"  🔗 aistudio.google.com/apikey"
+		]
+	}
+];
+const SERVICE_ID_MAP = new Map(API_KEYS_GUIDE.map((g) => [g.serviceId.toLowerCase(), g]));
+/** Known name aliases (e.g. anthropic, claude -> anthropic) */
+const ALIASES = {
+	claude: "anthropic",
+	gpt: "openai",
+	xai: "xai",
+	google: "google"
+};
+function getApiKeyGuide(serviceId) {
+	const id = serviceId.toLowerCase().replace(/[^a-z0-9-]/g, "");
+	return SERVICE_ID_MAP.get(id) ?? SERVICE_ID_MAP.get(ALIASES[id] ?? "") ?? null;
+}
+/** For unknown services — generic API key instructions */
+const GENERIC_API_KEY_STEPS = [
+	"For an unknown service:",
+	"1. Go to the official service website (e.g. developers.xxx.com).",
+	"2. Sign up / sign in. An account is usually required.",
+	"3. Look for \"API Keys\", \"Credentials\", \"Developer\" or \"Integrations\" section.",
+	"4. Create a new API key or token. Copy it immediately — many services do not show it again.",
+	"5. Keep it secret — do not share it or commit it to a repo.",
+	"",
+	"  💡 Known services: anthropic, openai, openrouter, tavily, elevenlabs, deepl, github, xai, google"
+];
+
+//#endregion
+exports.GENERIC_API_KEY_STEPS = GENERIC_API_KEY_STEPS;
+exports.getApiKeyGuide = getApiKeyGuide;