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:
140
README.md
140
README.md
@@ -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 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 test # unit tests
|
||||
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).
|
||||
|
||||
Reference in New Issue
Block a user