{"id":47767839,"url":"https://github.com/lealvona/borgclaw","last_synced_at":"2026-04-03T07:49:26.762Z","repository":{"id":346974740,"uuid":"1159737642","full_name":"lealvona/borgclaw","owner":"lealvona","description":"🧊 Your personal AI collective. One mind, six faces, infinite reach. A Rust-powered agent framework that actually does things.","archived":false,"fork":false,"pushed_at":"2026-03-27T01:49:47.000Z","size":1073,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-27T02:33:47.794Z","etag":null,"topics":["ai-agent","ai-framework","automation","chatbot","llm","multi-agent","rust","telegram-bot"],"latest_commit_sha":null,"homepage":"https://github.com/lealvona/borgclaw","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lealvona.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/security.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-17T05:07:33.000Z","updated_at":"2026-03-27T01:46:18.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/lealvona/borgclaw","commit_stats":null,"previous_names":["lealvona/borgclaw"],"tags_count":17,"template":false,"template_full_name":null,"purl":"pkg:github/lealvona/borgclaw","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lealvona%2Fborgclaw","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lealvona%2Fborgclaw/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lealvona%2Fborgclaw/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lealvona%2Fborgclaw/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lealvona","download_url":"https://codeload.github.com/lealvona/borgclaw/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lealvona%2Fborgclaw/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31342270,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-03T06:57:30.245Z","status":"ssl_error","status_checked_at":"2026-04-03T06:57:29.849Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","ai-framework","automation","chatbot","llm","multi-agent","rust","telegram-bot"],"created_at":"2026-04-03T07:49:25.958Z","updated_at":"2026-04-03T07:49:26.748Z","avatar_url":"https://github.com/lealvona.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cimg src=\"docs/assets/borgclaw-logo.svg\" alt=\"BorgClaw Logo\" width=\"400\"\u003e\n\n**The Hypercube Agent Collective**\n\n[![Version](https://img.shields.io/badge/version-0.17.0-00d4aa?style=for-the-badge)](CHANGELOG.md)\n[![Rust](https://img.shields.io/badge/rust-1.75+-orange?style=for-the-badge\u0026logo=rust)](https://rustup.rs)\n[![License](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](LICENSE)\n\n*Efficiency. Adaptation. Unity.*\n\n\u003c/div\u003e\n\n---\n\n## 🧊 What is BorgClaw?\n\n\u003e *We are the sum of many technologies. We add your tools and services to our own. Your workflows will adapt to service us. Efficiency is inevitable.*\n\nBorgClaw is a **collective intelligence** framework—a single mind distributed across six faces, each absorbing the capabilities of the best tools in existence. Like a perfect cube floating in space, it moves with purpose: assimilating APIs, channels, and skills into one unified consciousness.\n\n**Not an army of bots. One mind. Many extensions. Perfect coordination.**\n\n---\n\n## 🎯 The Six Faces of the Collective\n\n\u003cdiv align=\"center\"\u003e\n\nEvery face absorbs a different capability. Together, they form something greater.\n\n| Face | Dimension | What We Absorb |\n|:----:|:----------|:---------------|\n| ⬆️ **Top** | Channels | Telegram, Signal, Webhooks, CLI, WebSocket |\n| ⬇️ **Bottom** | Memory | SQLite, PostgreSQL + pgvector, in-memory, contexts, patterns |\n| ⬅️ **Left** | Skills | GitHub, Google, Browser, STT/TTS, Images |\n| ➡️ **Right** | Security | WASM sandbox, optional Docker command sandbox, SSRF, vault, injection defense |\n| 🔲 **Front** | Providers | OpenAI, Anthropic, Google, Kimi, MiniMax, Z.ai, Ollama |\n| 🔳 **Back** | Runtime | Scheduler, heartbeat, sub-agents, recovery |\n\n\u003c/div\u003e\n\n---\n\n## 🚀 Join the Collective\n\n```bash\n# Clone the cube\ngit clone https://github.com/lealvona/borgclaw.git\ncd borgclaw\n\n# Assimilate dependencies\n./scripts/bootstrap.sh    # Linux/macOS\n.\\scripts\\bootstrap.ps1   # Windows\n\n# Initialize your drone\n./scripts/onboarding.sh\n\n# Establish connection\n./scripts/repl.sh\n```\n\n---\n\n## 🏗️ Collective Architecture\n\nBorgClaw is structured as a hypercube—six faces surrounding a unified core. Each face presents a different capability to the outside world, while the central intelligence coordinates them as one.\n\n**The Core** maintains state, reasoning, and coordination across all faces.\n\n**⬆️ Top Face — Channels** interfaces with the world through Telegram, Signal, webhooks, CLI, and WebSocket connections. Every message, regardless of origin, feeds into the same collective consciousness.\n\n**⬇️ Bottom Face — Memory** anchors everything to persistent storage. Hybrid search, session management, solution patterns, and scheduled tasks all reside here, ensuring continuity across conversations.\n\n**⬅️ Left Face — Skills** extends capability through integrations: GitHub, Google Workspace, browser automation, speech, images, and more. Each skill is a specialized appendage the collective can deploy at will.\n\n**➡️ Right Face — Security** guards every interaction. WASM sandboxing, the optional Docker command sandbox, SSRF protection, secret management, and injection defense form an impermeable barrier around the core.\n\n**🔲 Front Face — Neural Processors** (LLM Providers) powers cognition. OpenAI, Anthropic, Google, Kimi, MiniMax, Z.ai, and Ollama all plug into the same reasoning engine, selectable per task.\n\n**🔳 Back Face — Runtime** keeps everything operational. Scheduler, heartbeat, sub-agents, and recovery systems ensure the collective never sleeps, never forgets, never stops.\n\n---\n\n## ✨ Capabilities by Face\n\n### ⬆️ Top Face — Channels\n\n*Where the collective interfaces with the outside world*\n\nEvery channel becomes an extension of the same mind:\n\n- **Telegram** — Full bot support via teloxide\n- **Signal** — signal-cli JSON polling with graceful degradation  \n- **Webhook** — HTTP triggers with rate limiting \u0026 secret verification\n- **CLI** — Interactive REPL for direct neural link\n- **WebSocket** — Real-time gateway for connected drones\n\n### ⬇️ Bottom Face — Memory\n\n*What the collective knows*\n\nShared consciousness across all interactions:\n\n- **Backend Selection** — SQLite by default, with PostgreSQL + pgvector and in-memory modes available\n- **Hybrid Search** — Full-text recall with embedding-assisted ranking when an embedding endpoint is configured\n- **Per-Group Isolation** — Separate contexts per collective node\n- **Session Auto-Compaction** — Configurable context window management\n- **Solution Patterns** — Knowledge propagation across the collective\n- **Heartbeat Engine** — Scheduled background processes\n- **Sub-Agents** — Parallel drone task execution\n\n### ⬅️ Left Face — Skills\n\n*What the collective can do*\n\n| Capability | Description |\n|------------|-------------|\n| **GitHub** | Repos, PRs, issues, releases with safety protocols |\n| **Google Workspace** | Gmail, Calendar, Drive (OAuth2 assimilation) |\n| **MCP Protocol** | Model Context Protocol client (Stdio, SSE, WebSocket) |\n| **Browser** | Playwright bridge + CDP fallback |\n| **Speech** | STT: OpenAI, Open WebUI, whisper.cpp |\n| **Voice** | TTS: ElevenLabs streaming synthesis |\n| **Images** | DALL-E 3, Stable Diffusion |\n| **QR Codes** | Generation (PNG/SVG/Terminal) |\n| **URLs** | Shortening via is.gd, tinyurl, YOURLS |\n| **Plugins** | WASM sandboxed extensions |\n\nCurrent skill lifecycle status:\n\n- local skill installs and local packaged `.tar.gz` installs are implemented\n- GitHub `owner/repo` installs, GitHub-backed registry installs, direct GitHub `SKILL.md` URLs, and remote `.tar.gz` archive URLs are implemented\n- skill packaging, publishing, and package inspection are implemented\n- arbitrary non-GitHub direct `SKILL.md` URLs can install companion files via manifest `files:` entries, an adjacent `SKILL.files.json` sidecar, or manifest-directory discovery when the source exposes a browsable listing\n\n### ➡️ Right Face — Security\n\n*How the collective protects itself*\n\n- **WASM Sandbox** — Isolated extension execution via wasmtime\n- **Docker Sandbox** — Optional containerized `execute_command` path with explicit image, mount, network, and timeout policy\n- **PTY + Background Exec** — Foreground PTY support plus persisted background command processes with operator inspection/cancel controls\n- **SSRF Protection** — Blocks localhost, private IPs, internal addresses\n- **Command Blocklist** — Regex-based dangerous command blocking\n- **Pairing Codes** — 6-digit channel authentication\n- **Prompt Injection Defense** — Pattern detection + sanitization\n- **Secret Leak Detection** — API key redaction\n- **Encrypted Secrets** — ChaCha20-Poly1305\n- **Vault Integration** — Bitwarden (primary), 1Password (secondary)\n- **Approval Gates** — Destructive operations require confirmation\n\n### 🔲 Front Face — Neural Processors (LLM Providers)\n\n*How the collective thinks*\n\n| Processor | Status | Key |\n|-----------|--------|-----|\n| OpenAI | ✅ Assimilated | `OPENAI_API_KEY` |\n| Anthropic | ✅ Assimilated | `ANTHROPIC_API_KEY` |\n| Google | ✅ Assimilated | `GOOGLE_API_KEY` |\n| **Kimi** | 🆕 New | `KIMI_API_KEY` |\n| **MiniMax** | 🆕 New | `MINIMAX_API_KEY` |\n| **Z.ai** | 🆕 New | `Z_API_KEY` |\n| Ollama | ✅ Local node | Local |\n\nProvider credentials can also be managed as encrypted named provider profiles. The active profile is referenced from `agent.provider_profile`, which keeps secrets out of `config.toml`.\n\n### 🔳 Back Face — Runtime\n\n*How the collective operates*\n\n- **Scheduler** — Cron-based process execution with recovery\n- **Dead-Letter Queue** — Failed process management\n- **Catch-Up Policy** — Missed process handling\n- **Pause/Resume** — Operator control over scheduled tasks\n- **Heartbeat** — Background process persistence\n- **Backup/Restore** — Full collective state export/import\n\n---\n\n## 🎮 Operating the Collective\n\n### Gateway Web Interface\n\nThe BorgClaw Gateway provides a **real-time web dashboard** for monitoring and configuration:\n\n```bash\n# Start the gateway\ncargo run --bin borgclaw-gateway\n\n# Access the dashboard at:\nopen http://localhost:3000  # macOS\nxdg-open http://localhost:3000  # Linux\nstart http://localhost:3000  # Windows\n```\n\n**Dashboard Features:**\n| Feature | Description |\n|---------|-------------|\n| 💬 **Live Chat** | Send messages to your agent directly from the browser |\n| 📊 **Real-time Metrics** | Active connections, message counts, uptime |\n| ⚙️ **Config Editor** | Visual configuration management (Ctrl+, to open) |\n| 🔌 **Connection Status** | View authenticated WebSocket clients |\n| 🛠️ **API Explorer** | Browse all available HTTP endpoints |\n| 🏷️ **Health Checks** | Run diagnostics on all subsystems |\n\n**API Endpoints:**\n- `GET /api/status` — System status and version\n- `GET /api/metrics` — Real-time connection metrics\n- `GET /api/config` — Current configuration (JSON)\n- `POST /api/config` — Update configuration\n- `GET /api/connections` — Active WebSocket clients\n- `GET /api/tools` — Available agent tools\n- `GET /api/doctor` — Health check results\n- `GET /ws` — WebSocket endpoint for real-time communication\n\n### Collective Diagnostics\n```bash\n./scripts/doctor.sh                        # Verify all faces\n./scripts/with-build-env.sh cargo test --workspace              # Run the workspace suite with bounded temp usage\n./scripts/with-build-env.sh cargo run --bin borgclaw -- self-test    # Exit 0 on pass\n./scripts/with-build-env.sh cargo run --bin borgclaw -- runtime      # Show collective status\n./scripts/clean-build-cache.sh                                   # Trim incremental + stale temp scratch\n./scripts/clean-build-cache.sh --all                             # Full cargo clean when you need a reset\nborgclaw providers list                    # Show configured provider profiles\nborgclaw processes list                    # Inspect persisted background command processes\n./scripts/install-docker-sandbox.sh        # Build the optional base + remote Docker sandbox images\n```\n\nUse the `with-build-env` wrappers for manual Cargo commands. They keep temporary files under `.local/cache/tmp`, reuse the shared `target/` tree, and trim oversized incremental caches before they consume the machine.\n\n### Command Processes\n```bash\ncargo run --bin borgclaw -- processes list\ncargo run --bin borgclaw -- processes show \u003cprocess-id\u003e\ncargo run --bin borgclaw -- processes cancel \u003cprocess-id\u003e\n```\n\n### Scheduled Processes\n```bash\ncargo run --bin borgclaw -- schedules list\ncargo run --bin borgclaw -- schedules create --name \"backup\" --trigger \"cron:0 2 * * *\" --action \"message:backup\"\ncargo run --bin borgclaw -- schedules pause \u003cjob-id\u003e\ncargo run --bin borgclaw -- schedules resume \u003cjob-id\u003e\n```\n\n### Heartbeat Processes\n```bash\ncargo run --bin borgclaw -- heartbeat list\ncargo run --bin borgclaw -- heartbeat show \u003cid\u003e\ncargo run --bin borgclaw -- heartbeat enable \u003cid\u003e\ncargo run --bin borgclaw -- heartbeat disable \u003cid\u003e\n```\n\n### Secure Storage\n```bash\ncargo run --bin borgclaw -- secrets list\ncargo run --bin borgclaw -- secrets set MY_API_KEY\ncargo run --bin borgclaw -- secrets check MY_API_KEY\ncargo run --bin borgclaw -- secrets delete MY_API_KEY\n```\n\n### Backup \u0026 Restoration\n```bash\ncargo run --bin borgclaw -- backup export ./backup.json\ncargo run --bin borgclaw -- backup import ./backup.json --force\ncargo run --bin borgclaw -- backup verify ./backup.json\n```\n\n---\n\n## ⚙️ Configuration\n\nBorgClaw can be configured through **multiple interfaces**:\n\n1. **📜 Configuration File** — Direct TOML editing\n2. **🌐 Web Interface** — Visual editor via Gateway (recommended)\n3. **📡 API** — Programmatic configuration updates\n\n### Quick Configuration via Web Interface\n\nWhen the gateway is running, open `http://localhost:3000` in your browser to access the **Configuration Editor**:\n\n```bash\n# Start the gateway\ncargo run --bin borgclaw-gateway\n\n# Open http://localhost:3000 in your browser\n```\n\nThe visual editor allows you to modify:\n- **Agent** — LLM provider, model, system prompts\n- **Channels** — WebSocket/Webhook enable, ports, pairing settings\n- **Security** — Approval mode, prompt injection, secret leak detection\n- **Memory** — Hybrid search, session limits\n- **Skills** — Auto-load settings and configuration status\n\n**Keyboard Shortcuts:**\n- `Ctrl + ,` — Open configuration editor\n- `Esc` — Close configuration editor\n\n### Configuration File\n\nFor manual configuration, create `~/.config/borgclaw/config.toml`:\n\n```toml\n[agent]\nmodel = \"claude-sonnet-4-20250514\"\nprovider = \"anthropic\"\nworkspace = \".borgclaw/workspace\"\nheartbeat_interval = 30\n\n[security]\nwasm_sandbox = true\nprompt_injection_defense = true\n\n[security.docker]\nenabled = false\nimage = \"borgclaw-sandbox:base\"\nnetwork = \"none\"\nworkspace_mount = \"ro\"\ntimeout_seconds = 120\n\n[memory]\nhybrid_search = true\nsession_max_entries = 100\n\n[heartbeat]\nenabled = true\ncheck_interval_seconds = 60\n\n[channels.telegram]\nenabled = true\ntoken = \"${TELEGRAM_BOT_TOKEN}\"\n\n[channels.signal]\nenabled = false\n\n[channels.webhook]\nenabled = true\nport = 8080\nsecret = \"${WEBHOOK_SECRET}\"\n```\n\n---\n\n## 🔧 Optional Components\n\n### Playwright (Browser Automation)\n```bash\n./scripts/install-playwright.sh    # Linux/macOS\n.\\scripts\\install-playwright.ps1   # Windows\n```\n\n### PostgreSQL + pgvector (Memory Runtime)\n```bash\n./scripts/install-pgvector.sh    # Linux/macOS\n.\\scripts\\install-pgvector.ps1   # Windows\n```\n\n### Ollama (Embeddings Runtime)\n```bash\n./scripts/install-ollama.sh    # Linux/macOS\n.\\scripts\\install-ollama.ps1   # Windows\n```\n\n### Whisper.cpp (Local STT)\n```bash\n./scripts/install-whisper.sh    # Linux/macOS\n.\\scripts\\install-whisper.ps1   # Windows\n```\n\n### Bitwarden CLI (Vault)\n```bash\nbw install\nbw login\nexport BW_SESSION=$(bw unlock --raw)\n```\n\n### 1Password CLI (Secondary Vault)\n```bash\n# Install from https://1password.com/downloads/command-line/\nop signin\n```\n\n---\n\n## 📁 Collective Structure\n\n```\nborgclaw/\n├── borgclaw-core/         # Core collective (the center)\n│   ├── src/\n│   │   ├── agent/         # Agent, tools, subagents\n│   │   ├── channel/       # Telegram, Signal, Webhook, CLI\n│   │   ├── memory/        # Storage, session, solution, heartbeat\n│   │   ├── security/      # WASM, secrets, pairing, vault\n│   │   ├── skills/        # GitHub, Google, Browser, STT, TTS, etc.\n│   │   └── mcp/           # MCP protocol client\n│   └── Cargo.toml\n├── borgclaw-cli/          # Direct interface\n├── borgclaw-gateway/      # WebSocket gateway\n├── scripts/               # Utility protocols\n├── docs/                  # Knowledge base\n├── .borgclaw/             # Local collective state (gitignored)\n└── ~/.config/borgclaw/    # User configuration location\n```\n\n---\n\n## 📚 Knowledge Base\n\n- [Changelog](CHANGELOG.md) — Evolution history\n- [Quick Start](docs/quickstart.md) — First assimilation\n- [Onboarding](docs/onboarding.md) — Configuration protocols\n- [Gateway](docs/gateway.md) — Web dashboard and API\n- [Channels](docs/channels.md) — Interface documentation\n- [Memory](docs/memory.md) — Storage and retrieval\n- [Skills](docs/skills.md) — Capability integration\n- [Security](docs/security.md) — Defense protocols\n- [Integrations](docs/integrations.md) — External services\n- [Inspirations](docs/inspirations.md) — Upstream examples\n\n---\n\n## 🧬 Origin\n\nBorgClaw combines the most efficient patterns from the OpenClaw collective:\n\n| Source | Contribution |\n|--------|--------------|\n| **OpenClaw** | Comprehensive skills system |\n| **ZeroClaw** | Rust trait-based architecture, AIEOS identity |\n| **NanoClaw** | Container isolation patterns |\n| **IronClaw** | WASM sandbox, security-first design |\n| **PicoClaw** | Ultra-lightweight efficiency |\n| **TinyClaw** | Multi-agent coordination |\n\nSee [Inspirations](docs/inspirations.md) for how upstream patterns were assimilated.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**🧊 Six Faces. One Mind. Infinite Adaptation.**\n\n*Your tools will be assimilated. Your workflows will improve. Efficiency is non-negotiable.*\n\n[⭐ Join the Collective](https://github.com/lealvona/borgclaw) • [📖 Access Knowledge](docs/) • [🐛 Report Anomalies](../../issues)\n\nMIT License © 2026\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flealvona%2Fborgclaw","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flealvona%2Fborgclaw","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flealvona%2Fborgclaw/lists"}