The community edition defaulted to ~/.waggle, the data directory of the commercial Waggle, so both editions would open the same config, vault, waggle.db, marketplace catalog and skills. Default to ~/.waggle-community instead (ADR-0011). WAGGLE_DATA_DIR still overrides it wherever it did; nothing is migrated from ~/.waggle. The name is defined once as DEFAULT_DATA_DIR_NAME and DEFAULT_DATA_DIR_LABEL in @waggle/shared, with defaultDataDir() in @waggle/core for the sidecar, the CLI, the agent and the model caches. The marketplace installs on its own without workspace packages, so it keeps a copy in its data-dir.ts; the CLI help, which loads no dependency, spells the path out and its runtime test checks it. The marketplace security scan also flags skills that reference the new skills folder. Tests that asserted the old default now use the constant, and comments name the new directory.
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 (
.exeor.msi,.dmg,.debor.AppImage) and run it. The first release is unsigned, so Windows and macOS show a warning the first time; the install guide shows how to get past it. -
Server installer. Install the server and use Waggle in your browser:
npx @waggle-ai/waggle install --from <archive path or URL> waggle-server # starts Waggle at http://localhost:3333Node.js 20 or newer is needed only for the
npxcall. The package and command names are temporary, and there is no default download location yet, which is why--fromis needed for now.
Neither way needs Python, Docker or a compiler. Details, updates and uninstalling: 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 store (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 lists what changed from the commercial product.
Run from source
Prerequisites: Node.js ^20.19.0 or >=22.12.0 (22 recommended) and npm.
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 unless you set WAGGLE_DATA_DIR.
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.
Checks
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 has the full list, and docs/oss/baseline.md records the known failures to compare against.
Documentation
- Install
- Getting started
- Workspaces
- Skills, plugins and the marketplace
- Connectors and channels
- Troubleshooting
- Memory
- Architecture
- Reference: slash commands, local API
- Decision records
- Contributing, Security policy, Threat model, Code of conduct
- Changelog
License
The code in this repository is licensed under the MIT 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.