This commit is contained in:
Oleg Maslov
136
README.md
Normal file
136
README.md
Normal file
@@ -0,0 +1,136 @@
|
||||
# Waggle OS
|
||||
|
||||
Workspace-native AI agent platform with persistent memory, model-agnostic orchestration, and skill-extensible capabilities. It ships as a Tauri 2.0 desktop binary (Windows/macOS) with a Vite-bundled web app and a Node.js sidecar.
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
waggle-os/
|
||||
├── apps/
|
||||
│ ├── web/ # Main web app UI (React 19 + Vite + Tailwind 4 + base-ui/react)
|
||||
│ ├── www/ # Marketing site (Next.js)
|
||||
│ └── browser-ext/ # Browser extension (unpacked; not an npm workspace)
|
||||
├── packages/ # 28 workspace packages (see "Packages" below)
|
||||
├── app/ # Tauri 2.0 desktop shell (Rust) — loads the apps/web build
|
||||
├── sidecar/ # Node.js sidecar bundled into the Tauri desktop binary
|
||||
└── docs/ # Architecture, contributing, threat model, and guides
|
||||
```
|
||||
|
||||
### Packages
|
||||
|
||||
The monorepo has **28 packages** under `packages/`. They split into two groups.
|
||||
|
||||
**Product packages (15, MIT):**
|
||||
|
||||
| Package | Purpose |
|
||||
|---|---|
|
||||
| `agent` | Agent loop, orchestrator, tools, personas, workflows, and the evolution subsystem |
|
||||
| `core` | Config, the encrypted vault, cron store, file store, telemetry, and compliance/audit |
|
||||
| `server` | Fastify sidecar — local (solo) and team routes, SSE streaming, Stripe, KVARK client |
|
||||
| `shared` | Shared types, Zod schemas, the tier system, and the MCP catalog |
|
||||
| `marketplace` | Package catalog with the `SecurityGate` installer |
|
||||
| `optimizer` | GEPA prompt optimization |
|
||||
| `weaver` | Memory consolidation daemon |
|
||||
| `waggle-dance` | Multi-agent coordination protocol |
|
||||
| `worker` | Background job processor (BullMQ, team mode) |
|
||||
| `sdk` | Plugin / skill SDK |
|
||||
| `cli` | Command-line REPL |
|
||||
| `launcher` | AI-tool launcher / dock backend |
|
||||
| `admin-web` | Admin dashboard for team deployments |
|
||||
| `wiki-compiler` | Knowledge / wiki compiler |
|
||||
| `memory-mcp` | MCP server exposing the memory substrate to external agents |
|
||||
|
||||
**Memory substrate — `hive-mind-*` (13, Apache-2.0):** the persistent-memory core, mirrored to the public OSS repo [`marolinik/hive-mind`](https://github.com/marolinik/hive-mind).
|
||||
|
||||
| Package | Purpose |
|
||||
|---|---|
|
||||
| `hive-mind-core` | The memory substrate: `FrameStore`, `HybridSearch`, `KnowledgeGraph`, `IdentityLayer`, `AwarenessLayer`, plus Harvest ingestion (`src/mind` + `src/harvest`) |
|
||||
| `hive-mind-cli` | CLI for the substrate |
|
||||
| `hive-mind-mcp-server` | MCP server for the substrate |
|
||||
| `hive-mind-shim-core` | Signal-emitter shim library |
|
||||
| `hive-mind-wiki-compiler` | Wiki compiler (OSS) |
|
||||
| `hive-mind-hooks-core` | Shared hook library |
|
||||
| `hive-mind-hooks-*` | Per-tool capture hooks: `claude-code`, `claude-desktop`, `codex`, `codex-desktop`, `cursor`, `hermes`, `openclaw` |
|
||||
|
||||
> The memory substrate is developed **here** and mirrored out — never the reverse.
|
||||
> See the "Memory Substrate Sync" section of [`CLAUDE.md`](./CLAUDE.md) before touching `packages/hive-mind-core`.
|
||||
|
||||
## Quick Start
|
||||
|
||||
### Self-host in one line (Linux / macOS)
|
||||
|
||||
```bash
|
||||
curl -fsSL https://raw.githubusercontent.com/marolinik/waggle-os/main/install.sh | bash
|
||||
```
|
||||
|
||||
Best for a VPS or homelab — this runs a headless Waggle server (no desktop shell):
|
||||
|
||||
- **Checks prerequisites, clones, builds, and starts** the Node.js sidecar, then prints the URL (`http://127.0.0.1:3333`). A 5-question wizard — install dir, port, data dir, build web UI, start now — is all Enter-defaulted; pass `--yes` to accept every default non-interactively.
|
||||
- **Boots with zero API keys** in echo mode so the UI works immediately. Add a provider key later under **Settings → API Keys**, where it is stored in the encrypted vault — keys are never passed on the command line.
|
||||
- **No sudo, ever.** A missing prerequisite prints the exact per-OS install command and exits; the installer never installs system packages for you.
|
||||
|
||||
Manage the running server with the installed wrapper: `scripts/waggle-server.sh status | logs | stop | start`. Re-running the one-liner against an existing install prints an upgrade hint instead of reinstalling.
|
||||
|
||||
### Run from source (development)
|
||||
|
||||
```bash
|
||||
# Prerequisites: Node.js >= 20, npm
|
||||
npm install
|
||||
|
||||
# (Optional) copy the env template. Provider API keys are normally set in-app
|
||||
# (Settings → API Keys), which stores them in the encrypted vault — so you do
|
||||
# NOT need to put keys in .env for a basic local run.
|
||||
cp .env.example .env
|
||||
|
||||
# Terminal 1 — backend sidecar (http://localhost:3333)
|
||||
npm run dev:server
|
||||
|
||||
# Terminal 2 — web app (http://localhost:8080)
|
||||
npm run dev:web
|
||||
|
||||
# Open http://localhost:8080
|
||||
```
|
||||
|
||||
`npm run dev:server` runs the Fastify sidecar via `tsx` (equivalent to
|
||||
`cd packages/server && npx tsx src/local/start.ts`). `npm run dev:web` runs the
|
||||
Vite dev server for `apps/web`.
|
||||
|
||||
**Embeddings.** By default `EMBEDDING_PROVIDER=auto` downloads a small in-process
|
||||
model (~23 MB, cached under `~/.waggle/models/`) and works fully offline. For
|
||||
better recall — and to reproduce any hive-mind benchmark — install
|
||||
[Ollama](https://ollama.com), run `ollama pull nomic-embed-text`, and set
|
||||
`EMBEDDING_PROVIDER=ollama`.
|
||||
|
||||
> **Windows:** if the sidecar fails to start with an esbuild platform error, see
|
||||
> [Troubleshooting](docs/CONTRIBUTING.md#troubleshooting) in the contributing guide.
|
||||
|
||||
## Environment Variables
|
||||
|
||||
Provider keys are stored in the encrypted vault (set via **Settings → API Keys**)
|
||||
and hydrated into the process at boot, so most of these are optional for a local
|
||||
run. See [`.env.example`](./.env.example) for the full contract.
|
||||
|
||||
| Variable | Required | Description |
|
||||
|----------|----------|-------------|
|
||||
| `ANTHROPIC_API_KEY` | Recommended | Claude API key. Optional in `.env` — can be set in-app instead (vault). |
|
||||
| `OPENAI_API_KEY` | No | Enables OpenAI models and optional OpenAI embeddings. |
|
||||
| `EMBEDDING_PROVIDER` | No | `auto` (default) · `inprocess` · `ollama` · `voyage` · `openai` · `mock`. `auto` tries in-process → Ollama → API → mock. |
|
||||
| `LITELLM_BASE_URL` | No | LiteLLM proxy URL for multi-model routing (default `http://localhost:4000`). |
|
||||
| `DATABASE_URL` | Team only | PostgreSQL connection string. |
|
||||
| `REDIS_URL` | Team only | Redis for the background job queue. |
|
||||
|
||||
## Documentation
|
||||
|
||||
- [Getting Started](docs/GETTING-STARTED.md) — first-run walkthrough
|
||||
- [Architecture](docs/ARCHITECTURE.md) — package structure, data flow, extension points
|
||||
- [Contributing](docs/CONTRIBUTING.md) — setup, tests, PR process, troubleshooting
|
||||
- [Threat Model](THREAT_MODEL.md) — trust boundary and security controls
|
||||
- [Security Policy](SECURITY.md) — how to report a vulnerability
|
||||
- [Code of Conduct](CODE_OF_CONDUCT.md)
|
||||
|
||||
## License
|
||||
|
||||
This repository is licensed under the [MIT License](./LICENSE), **except** the
|
||||
`hive-mind-*` packages under `packages/`, which are licensed under **Apache-2.0**.
|
||||
Each `hive-mind-*` package carries its own `LICENSE` file, which governs that
|
||||
package. See [Packages](#packages) for the split.
|
||||
Reference in New Issue
Block a user