docs: rewrite the README for the first community release (P2.4)

Say plainly what Waggle is, show both install paths with a link to the
install guide, the current run-from-source steps (no build:packages),
the checks and a documentation index. The license section points to
THIRD_PARTY_NOTICES.md; the Apache-2.0 hive-mind sentence is gone with
those packages.
This commit is contained in:
shumeiko.it
2026-11-01 01:53:54 +01:00
parent 06a0df73b5
commit ea724a6bfd

146
README.md
View File

@@ -1,89 +1,113 @@
# Waggle OS Community Edition
# Waggle 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.
Waggle is an AI agent workspace that runs on your own computer. You organize work into
workspaces; in each one an agent chats with you, uses tools (files, web search, documents,
connected services), runs scheduled automations, and remembers facts and decisions between
chats. Memory, settings and keys stay on your computer.
> **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 agent needs a model: a local model that Waggle downloads and runs for you, or your own key
for a provider such as Anthropic, OpenAI or Google.
## Repository layout
This is the open-source community edition (MIT). It has no paid tiers, no license checks and no
team features. Analytics are off unless you allow them.
```
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
```
## Install
`AGENTS.md` lists the status of every package in this edition.
Two ways, on Windows x64, macOS (Apple silicon and Intel) and Linux x64:
- **Desktop app.** Download the installer for your system (`.exe` or `.msi`, `.dmg`, `.deb` or
`.AppImage`) and run it. The first release is unsigned, so Windows and macOS show a warning
the first time; [the install guide](docs/install.md) shows how to get past it.
- **Server installer.** Install the server and use Waggle in your browser:
```bash
npx @waggle-ai/waggle install --from <archive path or URL>
waggle-server # starts Waggle at http://localhost:3333
```
Node.js 20 or newer is needed only for the `npx` call. The package and command names are
temporary, and there is no default download location yet, which is why `--from` is needed
for now.
Neither way needs Python, Docker or a compiler. Details, updates and uninstalling:
[docs/install.md](docs/install.md).
## What is in this edition
- Workspaces with chat sessions, files and a choice of personas
- Memory on your computer: facts, search and a profile of what Waggle learned about you, through
a memory contract backed by a local [mem0](https://github.com/mem0ai/mem0) store
([docs/memory.md](docs/memory.md))
- Models: the Waggle-managed Ollama runtime, an Ollama you run, or your own provider keys
- Skills, plugins, MCP servers and a marketplace with a security scan before install
- Connectors (GitHub, Slack, Jira, Notion, Google Workspace and Microsoft apps among others) and
messaging channels (Telegram, Discord, Slack, WhatsApp)
- Automations, approvals for sensitive actions, cost tracking and budgets
- An encrypted vault for keys and credentials
Not in this edition: billing and tiers, KVARK, compliance reports, self-learning, team mode, the
knowledge graph, chat-history import, the wiki, memory hooks for external coding agents (Claude
Code, Codex) and the memory server for external tools (MCP).
[CHANGELOG.md](CHANGELOG.md) lists what changed from the commercial product.
## Run from source
Prerequisites: Node.js `^20.19.0` or `>=22.12.0`, and npm.
Prerequisites: Node.js `^20.19.0` or `>=22.12.0` (22 recommended) 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
npm ci
npm run build # type-checks the web UI and builds it into dist/
npm run dev:server # the sidecar on http://localhost:3333, serving dist/
```
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)).
Open http://localhost:3333. After changing the UI, run `npm run build` again and restart the
sidecar: it registers the files in `dist/` when it starts. The Vite dev server
(`npm run dev:web`) cannot sign in to the sidecar yet.
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.
Workspace packages are resolved from their TypeScript source, so no package build is needed
before running or testing. Data goes to `~/.waggle` unless you set `WAGGLE_DATA_DIR`.
**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`.
Add a model in the app (Settings → Models). `.env.example` lists optional environment
variables; a basic local run needs none of them.
| 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. |
The desktop app and release archives are built per system:
see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md#how-a-release-is-built).
## 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
npm run build:packages # type-check every package
npm run typecheck:web # type-check the web UI
npm run lint # lint the packages
(cd apps/web && npx eslint .) # lint the web UI
npm run check:deps # every import is a declared dependency
npm run check:licenses # shipped dependencies allow MIT distribution
npm test # unit tests (packages, tests/, scripts/)
(cd apps/web && npx vitest run) # web UI unit tests
```
Known failures and the numbers to compare against are in
[`docs/oss/baseline.md`](docs/oss/baseline.md).
[CONTRIBUTING.md](CONTRIBUTING.md) has the full list, and
[docs/oss/baseline.md](docs/oss/baseline.md) records the known failures to compare against.
## Documentation
- [Getting Started](docs/GETTING-STARTED.md)
- [Install](docs/install.md)
- [Getting started](docs/guides/getting-started.md)
- [Workspaces](docs/guides/workspaces.md)
- [Skills, plugins and the marketplace](docs/guides/capabilities.md)
- [Connectors and channels](docs/guides/connectors.md)
- [Troubleshooting](docs/guides/troubleshooting.md)
- [Memory](docs/memory.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.
- Reference: [slash commands](docs/reference/commands.md), [local API](docs/reference/api.md)
- [Decision records](docs/oss/adr/README.md)
- [Contributing](CONTRIBUTING.md), [Security policy](SECURITY.md),
[Threat model](THREAT_MODEL.md), [Code of conduct](CODE_OF_CONDUCT.md)
- [Changelog](CHANGELOG.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.
The code in this repository is licensed under the [MIT License](LICENSE).
Waggle uses third-party packages under their own licenses. The notices for the components that
ship with Waggle are in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).