Koyal
Zero-overhead AI trading harness. Rust native. Permission-gated. Multi-chain.
Koyal is a local-first control plane for crypto research, portfolio monitoring, AI-driven trading bots, and approval-gated execution across chains. A single binary that ships the gateway, web dashboard, and CLI together.
curl -fsSL https://raw.githubusercontent.com/s1dc0des/koyal/main/install.sh | sh
koyal doctor
# {"status":"ok","version":"0.1.0","harness":"rust","gateway":8790}
koyal gateway # starts HTTP gateway + serves web dashboard
koyal dashboard open # opens browser to http://127.0.0.1:8790/
What Koyal Is
- A harness, not an exchange. Koyal coordinates agents, proposals, and execution. It does not hold funds or custody keys beyond what you configure.
- Review-first by default. Every trade proposal is gated by an explicit approval step. The global halt switch pauses all execution immediately.
- Local-first. Keys, config, agent memory, and trade history stay on your machine. No cloud sync, no vendor dashboard.
- Self-learning. Agents write learnings back to their vault after every tick. Outcome capture drives genuine adaptation.
Key Capabilities
| Capability | Description |
|---|---|
| 55+ AI Providers | OpenAI, Anthropic, Gemini, Bedrock, DeepSeek, Groq, Together, OpenRouter, xAI, Mistral, and 45 more. Priority routing with circuit breaker. |
| Multi-Chain | Solana + Jupiter, EVM + Uniswap v3/v4, Hyperliquid perps, Polymarket prediction markets. |
| Unified Vault | Single source of truth per agent: soul.md, instructions.md, memories, learnings, skills, bot configs. compose_bible builds the full system prompt for every tick. |
| Permission Engine | PermissionEngine with bot-scoped policies, wallet roles (Observe / Trade / Sweep), and scoped authorization. |
| Web Dashboard | React + Vite + WebSocket UI served directly by koyal gateway. No separate Node server required. |
| MCP Server | Built-in Model Context Protocol server. All harness tools exposed as MCP calls. External MCP servers (Solana, Chainstack) configurable. |
| CLI + TUI | 20+ subcommands via clap. koyal tui for ratatui terminal UI. koyal dashboard open for the browser. |
| Integrations | Telegram alerts/control, webhook outbound, Prometheus metrics. |
| Supply Chain | CycloneDX SBOM, SHA256SUMS + GitHub Attestations, cargo deny, daily cargo audit. |
Crate Structure
koyal-api ← public trait boundary (no heavy deps)
koyal-config ← env + frontmatter parser
koyal-memory ← SQLite FTS5, JSONL ledger, MarkdownVault
koyal-chains ← Solana, EVM
koyal-dexes ← Jupiter, Uniswap v3/v4
koyal-exchanges ← Hyperliquid, Polymarket
koyal-providers ← 55+ AI provider implementations
koyal-core ← in-memory stores, type registry
koyal-runtime ← tick engine, PermissionEngine, scheduler
koyal-gateway ← axum HTTP + WebSocket + MCP + static files
koyal-integrations ← loop blueprints, Telegram, webhook
koyal ← CLI (clap) + binary facade
See Architecture for the full crate reference and dependency contract.
Quick Links
- Quick Start — install and run in 2 minutes
- CLI Reference — all 20+ commands documented
- API Reference — all gateway routes with JSON shapes
- Vault Guide — how the agent bible works
- Web Dashboard — start, open, configure
- Release Runbook — tag and ship