Files
waggle-os/README.md
shumeiko.it 5f088698dd 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.
2026-10-20 01:02:18 +02:00

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.