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.
90 lines
3.7 KiB
Markdown
90 lines
3.7 KiB
Markdown
# Waggle OS Community Edition
|
|
|
|
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.
|
|
|
|
> **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).
|
|
|
|
## Repository layout
|
|
|
|
```
|
|
waggle-os/
|
|
├── 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
|
|
```
|
|
|
|
`AGENTS.md` lists the status of every package in this edition.
|
|
|
|
## Run from source
|
|
|
|
Prerequisites: Node.js `^20.19.0` or `>=22.12.0`, and npm.
|
|
|
|
```bash
|
|
npm install
|
|
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
|
|
```
|
|
|
|
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)).
|
|
|
|
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
|
|
(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`.
|
|
|
|
| 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. |
|
|
|
|
## Checks
|
|
|
|
```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
|
|
```
|
|
|
|
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)
|
|
- [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.
|