Files
waggle-os/README.md
shumeiko.it e0836388f1 docs: record the separate data directory (ADR-0011)
Add ADR-0011: the community edition defaults to ~/.waggle-community, a
temporary name that follows the product-name decision (Q8), and copies
nothing from the commercial ~/.waggle. It supersedes point 4 of
ADR-0009 and closes the pending "separate data directory" decision.

Update the install guide, troubleshooting, capabilities, memory,
architecture, the Windows build notes, THREAT_MODEL, README,
.env.example and the changelog. Log UF-068 (Open): marketplace skills
and plugins ignore a custom data directory.
2026-11-04 10:32:08 +01:00

115 lines
5.2 KiB
Markdown

# Waggle Community Edition
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.
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.
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
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), Waggle Room tasks for those agents 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` (22 recommended) and npm.
```bash
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. 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.
Workspace packages are resolved from their TypeScript source, so no package build is needed
before running or testing. Data goes to `~/.waggle-community` unless you set `WAGGLE_DATA_DIR`;
the commercial Waggle's `~/.waggle` is not used.
Add a model in the app (Settings → Models). `.env.example` lists optional environment
variables; a basic local run needs none of them.
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 # 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
```
[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
- [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)
- 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
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).