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, Waggle is an AI agent workspace that runs on your own computer. You organize work into
connectors and scheduled automations. It runs as a Node.js sidecar with a React web UI, and workspaces; in each one an agent chats with you, uses tools (files, web search, documents,
can be wrapped in a Tauri desktop shell. You bring your own model: a local model through connected services), runs scheduled automations, and remembers facts and decisions between
Ollama or a provider API key. chats. Memory, settings and keys stay on your computer.
> **Status: work in progress.** This branch is being converted from the commercial Waggle The agent needs a model: a local model that Waggle downloads and runs for you, or your own key
> OS codebase into an open-source community edition. Billing, KVARK, compliance reporting for a provider such as Anthropic, OpenAI or Google.
> 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 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.
``` ## Install
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. 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 ## 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 ```bash
npm install npm ci
npm run build:packages # workspace packages export dist/; the sidecar needs it npm run build # type-checks the web UI and builds it into dist/
npm run build # builds the web UI into dist/ npm run dev:server # the sidecar on http://localhost:3333, serving 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: Open http://localhost:3333. After changing the UI, run `npm run build` again and restart the
the Vite dev server (`npm run dev:web`) cannot authenticate against the sidecar yet sidecar: it registers the files in `dist/` when it starts. The Vite dev server
(UF-003 in [`docs/oss/upstream-fixes.md`](docs/oss/upstream-fixes.md)). (`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 Workspace packages are resolved from their TypeScript source, so no package build is needed
encrypted vault, so a basic local run needs no `.env` file. `.env.example` lists the before running or testing. Data goes to `~/.waggle` unless you set `WAGGLE_DATA_DIR`.
optional variables.
**Embeddings.** By default `EMBEDDING_PROVIDER=auto` downloads a small in-process model Add a model in the app (Settings → Models). `.env.example` lists optional environment
(about 23 MB, cached under `~/.waggle/models/`) and works offline. To use Ollama instead, variables; a basic local run needs none of them.
install [Ollama](https://ollama.com), run `ollama pull nomic-embed-text`, and set
`EMBEDDING_PROVIDER=ollama`.
| Variable | Description | The desktop app and release archives are built per system:
|---|---| see [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md#how-a-release-is-built).
| `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 ## Checks
```bash ```bash
npm run build:packages # build all workspace packages npm run build:packages # type-check every package
npm run typecheck:web # type-check the web UI npm run typecheck:web # type-check the web UI
npm run lint # lint the packages npm run lint # lint the packages
npm run check:deps # every import is a declared dependency (cd apps/web && npx eslint .) # lint the web UI
npm test # unit tests 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 [CONTRIBUTING.md](CONTRIBUTING.md) has the full list, and
[`docs/oss/baseline.md`](docs/oss/baseline.md). [docs/oss/baseline.md](docs/oss/baseline.md) records the known failures to compare against.
## Documentation ## 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) - [Architecture](docs/ARCHITECTURE.md)
- [Contributing](docs/CONTRIBUTING.md) - Reference: [slash commands](docs/reference/commands.md), [local API](docs/reference/api.md)
- [Threat Model](THREAT_MODEL.md) - [Decision records](docs/oss/adr/README.md)
- [Security Policy](SECURITY.md) - [Contributing](CONTRIBUTING.md), [Security policy](SECURITY.md),
- [Code of Conduct](CODE_OF_CONDUCT.md) [Threat model](THREAT_MODEL.md), [Code of conduct](CODE_OF_CONDUCT.md)
- [Changelog](CHANGELOG.md)
The guides predate the community edition and still describe some removed features; they
are rewritten before the first release.
## License ## License
This repository is licensed under the [MIT License](./LICENSE), **except** the The code in this repository is licensed under the [MIT License](LICENSE).
`hive-mind-*` packages under `packages/`, which are licensed under **Apache-2.0**.
Each `hive-mind-*` package carries its own `LICENSE` file, which governs that Waggle uses third-party packages under their own licenses. The notices for the components that
package. ship with Waggle are in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).