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:
146
README.md
146
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,
|
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).
|
||||||
|
|||||||
Reference in New Issue
Block a user