chore: remove internal documents and service directories (P2.2 part 1)
The commercial repository carries the product's internal history: audits, screenshots, briefs, decisions, pricing, publication drafts, personal data and research runs. None of it belongs in the community edition. - delete judging/, "UAT 3/", benchmarks/ (including LoCoMo data under CC BY-NC), preflight-results/, gepa-phase-5/, notes/, decisions/, .understand-anything/, .agents/, .lovable/, the legacy sidecar/ package and waggle-cowork/ (an analysis of Claude Code sources) - delete docs/ except docs/oss, the user guides (without the team-mode guide), the reference, methodology, architecture, getting-started and contributing pages, which P2.4 rewrites - delete render.yaml, .parity-allowlist, the retired mind-parity and sync-mind workflows and 29 one-off scripts nothing references - delete tests that only checked removed files (sidecar package, Render blueprint, UAT capture, benchmark harness isolation, internal audit and signing docs); drop sidecar/ and benchmarks/ from the hive-mind subtree split guard; prune ignore, attribute, lint and test globs - replace the commercial README with an interim one for this edition Source comments still point at some deleted docs; P2.2 part 2 cleans them together with names and paths.
This commit is contained in:
226
README.md
226
README.md
@@ -1,201 +1,89 @@
|
||||
# Waggle OS
|
||||
# Waggle OS Community Edition
|
||||
|
||||
Workspace-native AI agent platform with persistent memory, model-agnostic orchestration, and skill-extensible capabilities. The current desktop release scope is Windows-first: a Tauri 2.0 app with a Vite-bundled web UI and bundled Node.js sidecar; macOS packaging and certification remain roadmap work.
|
||||
Waggle is a local-first AI workspace: an agent with persistent memory, personas, skills,
|
||||
connectors and scheduled automations. It runs as a Node.js sidecar with a React web UI, and
|
||||
can be wrapped in a Tauri desktop shell. You bring your own model: a local model through
|
||||
Ollama or a provider API key.
|
||||
|
||||
## Current Release Scope
|
||||
> **Status: work in progress.** This branch is being converted from the commercial Waggle
|
||||
> OS codebase into an open-source community edition. Billing, KVARK, compliance reporting
|
||||
> and self-learning are already removed; memory is moving to a local mem0 store, and
|
||||
> installers for Windows, macOS and Linux are not ready yet. The rules for this conversion
|
||||
> are in [`AGENTS.md`](AGENTS.md) and the decision records in
|
||||
> [`docs/oss/adr/`](docs/oss/adr/README.md).
|
||||
|
||||
The active launch gate is **Windows Solo**. Its in-scope external-agent release cohort is **Claude Code, Codex, and Hermes**. Each tool uses the user's own installation and authentication; Waggle does not redistribute provider credentials or bypass provider terms.
|
||||
|
||||
- **Cursor and OpenClaw are roadmap integrations.** They remain registered for detection and future development, but the production launcher, hooks, Fleet/task path, and direct run API do not offer them.
|
||||
- Claude Desktop, Codex Desktop, and Hermes Desktop may appear as detected convenience launch surfaces; they are not separate memory-hook or agent-acceptance targets in this release gate.
|
||||
- **ChatGPT/OpenAI is a model and memory-import surface**, not a separate local coding-agent launcher.
|
||||
- The Windows Solo launch contract requires an exact-revision Windows installer qualification receipt to prove its bundled Node sidecar, no-Python OpenAI-compatible proxy, Waggle-managed local runtime/model, default in-process embedding path, and freedom from developer Node, Docker, Python, an external LiteLLM service, or a separately installed Ollama. A separate revision-bound router receipt must prove the smart-router primary, compact-tool-context, budget, and fallback paths. Router, persona, and authentication receipts may cover a later candidate only through an independently reviewed bounded no-impact attestation proving that no covered runtime surface changed; otherwise they must be rerun. A user-installed Ollama remains optional.
|
||||
- Docker/LiteLLM deployment files remain optional server and team deployment choices; they are not desktop prerequisites.
|
||||
|
||||
Release status, revision-bound receipts, and any bounded carry-forward attestations are governed only by the current [launch recommendation](docs/production-readiness/09-LAUNCH_RECOMMENDATION.md). If it does not say **GO**, do not describe Waggle as production-ready or reuse historical scores or receipts as current release evidence.
|
||||
|
||||
### Current Windows Solo internal RC evidence — 2026-08-27
|
||||
|
||||
The current runtime candidate is private `main` commit
|
||||
`23ad3fa5f99bddce648b84750a41365299aeb0da`. Its internal-pilot NSIS installer
|
||||
(102,923,936 bytes; SHA-256
|
||||
`7BFA9F9B13633A51CD3336B42E3EF904B7F7A568C6DEE4F6CED967CBD4F40A59`)
|
||||
passed **64/64** clean-profile checks. The receipt proves bundled sidecar and offline
|
||||
npm, FREE/Solo first boot, in-process embeddings, the Waggle-managed local runtime and
|
||||
`qwen2.5:0.5b`, local-model chat, proxy restart, repair, relaunch, data preservation,
|
||||
Exit/cleanup, and uninstall. Docker, Python, developer Node.js, external LiteLLM, and a
|
||||
separately installed Ollama were not prerequisites.
|
||||
|
||||
- Private PR #66 merged as `23ad3fa5` after every blocking check passed: primary CI,
|
||||
Playwright smoke and full E2E, Windows and both macOS Tauri verification targets, and
|
||||
Hive Mind install/smoke on Windows, Ubuntu, and macOS. The tested PR head and merged
|
||||
source have the same tree.
|
||||
- Exact-current full and production dependency audits contain **0 Critical and 0 High**
|
||||
findings. Lower-severity maintenance remains documented.
|
||||
- The historical persona collection at `4c712ff6` still records all ten personas x3 at
|
||||
or above 95/100 after documented independent adjudication, but it is not relabeled as
|
||||
an exact-current seal. PR #66 changed memory behavior, so public release qualification
|
||||
requires a fresh receipt or an explicit bounded semantic-impact attestation.
|
||||
- Smart-router primary, compact-tool-context, durable-budget and fallback evidence, plus
|
||||
the Claude Code, Codex, and Hermes official-user-auth canaries, remain historical
|
||||
scoped evidence. No later change touched provider credential handling; the auth
|
||||
harness read or copied no credential files.
|
||||
- The curated Hive Mind mirror is hardened through private-to-maintainer PR #53, merged
|
||||
on public `master` as `3410327800db3ea23f875d547a0c7f4d08826b7e`; Windows, macOS,
|
||||
Ubuntu, and Ubuntu first-run smoke were green. The immutable drift baseline still
|
||||
reports reviewed release blockers, so the next OSS package release remains a separate
|
||||
maintainer-curated operation and is not implied by this Windows Solo RC.
|
||||
|
||||
Detailed local receipt paths, hashes, limitations, and integration gates are recorded in
|
||||
the current [launch recommendation](docs/production-readiness/09-LAUNCH_RECOMMENDATION.md).
|
||||
The internal signer (`CN=Egzakta Internal Pilot`) and DigiCert timestamp prove the pilot
|
||||
pipeline but are not publicly trusted Authenticode. Public release is **not yet approved**:
|
||||
a protected hosted build with a publicly trusted signer, an exact-candidate sealed
|
||||
managed Deep Security report, current persona qualification, and either fresh or
|
||||
explicitly attested smart-router and official-auth qualification remain mandatory.
|
||||
|
||||
## Architecture
|
||||
## Repository layout
|
||||
|
||||
```
|
||||
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
|
||||
├── apps/web/ # Web UI (React 19, Vite, Tailwind 4)
|
||||
├── app/ # Tauri 2 desktop shell (Rust); loads the apps/web build
|
||||
├── packages/ # npm workspaces: agent, server, core, shared, marketplace,
|
||||
│ # memory-contract, memory-mem0, cli, launcher, sdk, weaver, ...
|
||||
└── docs/ # Guides, reference, and docs/oss for the community edition
|
||||
```
|
||||
|
||||
### Packages
|
||||
`AGENTS.md` lists the status of every package in this edition.
|
||||
|
||||
The monorepo has **28 packages** under `packages/`. They split into two groups.
|
||||
## Run from source
|
||||
|
||||
**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
|
||||
|
||||
### Windows Solo desktop
|
||||
|
||||
Use only the signed Windows installer and SHA-256 identified by a **GO** [launch recommendation](docs/production-readiness/09-LAUNCH_RECOMMENDATION.md). If that recommendation is not GO, no packaged desktop artifact is release-approved; use the source-development instructions below.
|
||||
|
||||
### Self-host from the private repository (Linux / macOS)
|
||||
Prerequisites: Node.js `^20.19.0` or `>=22.12.0`, and npm.
|
||||
|
||||
```bash
|
||||
gh repo clone marolinik/waggle-os
|
||||
cd waggle-os
|
||||
bash install.sh
|
||||
```
|
||||
|
||||
This path is for maintainers with authenticated access to the private repository.
|
||||
Do not publish an anonymous raw-file installer until the source/licensing decision is explicit.
|
||||
|
||||
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.19.0 or >=22.12.0, 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 build:packages # workspace packages export dist/; the sidecar needs it
|
||||
npm run build # builds the web UI into dist/
|
||||
npm run dev:server # the sidecar on http://localhost:3333, serving the UI
|
||||
```
|
||||
|
||||
The source tree follows the root `package.json` Node engine above. The packaged
|
||||
Windows Solo desktop carries its own pinned Node.js 22.23.2 runtime, so an
|
||||
installed user does not need a separate Node.js installation.
|
||||
Open http://localhost:3333. Rebuild the UI and restart the sidecar to see UI changes:
|
||||
the Vite dev server (`npm run dev:web`) cannot authenticate against the sidecar yet
|
||||
(UF-003 in [`docs/oss/upstream-fixes.md`](docs/oss/upstream-fixes.md)).
|
||||
|
||||
`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`.
|
||||
Provider keys are entered in the app under **Settings → API Keys** and stored in the
|
||||
encrypted vault, so a basic local run needs no `.env` file. `.env.example` lists the
|
||||
optional variables.
|
||||
|
||||
**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
|
||||
**Embeddings.** By default `EMBEDDING_PROVIDER=auto` downloads a small in-process model
|
||||
(about 23 MB, cached under `~/.waggle/models/`) and works offline. To use Ollama instead,
|
||||
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.
|
||||
| Variable | Description |
|
||||
|---|---|
|
||||
| `ANTHROPIC_API_KEY` | Claude API key; can be set in the app instead. |
|
||||
| `OPENAI_API_KEY` | Enables OpenAI models and optional OpenAI embeddings. |
|
||||
| `EMBEDDING_PROVIDER` | `auto` (default), `inprocess`, `ollama`, `voyage`, `openai` or `mock`. |
|
||||
| `LITELLM_BASE_URL` | Optional external LiteLLM-compatible proxy. |
|
||||
|
||||
## Environment Variables
|
||||
## Checks
|
||||
|
||||
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.
|
||||
```bash
|
||||
npm run build:packages # build all workspace packages
|
||||
npm run typecheck:web # type-check the web UI
|
||||
npm run lint # lint the packages
|
||||
npm run check:deps # every import is a declared dependency
|
||||
npm test # unit tests
|
||||
```
|
||||
|
||||
| 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 | Optional external LiteLLM-compatible proxy URL. The Windows Solo desktop uses its bundled no-Python proxy unless explicitly configured otherwise. |
|
||||
| `DATABASE_URL` | Team only | PostgreSQL connection string. |
|
||||
| `REDIS_URL` | Team only | Redis for the background job queue. |
|
||||
Known failures and the numbers to compare against are in
|
||||
[`docs/oss/baseline.md`](docs/oss/baseline.md).
|
||||
|
||||
## 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
|
||||
- [Getting Started](docs/GETTING-STARTED.md)
|
||||
- [Architecture](docs/ARCHITECTURE.md)
|
||||
- [Contributing](docs/CONTRIBUTING.md)
|
||||
- [Threat Model](THREAT_MODEL.md)
|
||||
- [Security Policy](SECURITY.md)
|
||||
- [Code of Conduct](CODE_OF_CONDUCT.md)
|
||||
|
||||
The guides predate the community edition and still describe some removed features; they
|
||||
are rewritten before the first release.
|
||||
|
||||
## 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.
|
||||
package.
|
||||
|
||||
Reference in New Issue
Block a user