Files
waggle-os/README.md
shumeiko.it c4580b95f8 docs(oss): settle the licensing items the owner left to us
ADR-0010 records that the marketplace catalog holds package metadata
only (names, authors, licenses, short descriptions, links, install
instructions), like any package index, and needs no licensing review.
The pending licensing row of the ADR index keeps only the copyright
holder in LICENSE; the settled items (Apache-2.0 files in core, the
notices and the LGPL terms, the catalog) are listed below the table.
The README names the Apache-2.0 files of packages/core.
2026-11-04 10:35:54 +01:00

5.3 KiB

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 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: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.

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

License

The code in this repository is licensed under the MIT License, except some files in packages/core that were copied from an Apache-2.0 package and keep the Apache License 2.0; packages/core/LICENSE.md lists them.

Waggle uses third-party packages under their own licenses. The notices for the components that ship with Waggle are in THIRD_PARTY_NOTICES.md.