# Waggle OS 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. > **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). ## Repository layout ``` 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. ## Run from source Prerequisites: Node.js `^20.19.0` or `>=22.12.0`, 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 ``` 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)). 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. **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`. | 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. | ## Checks ```bash npm run build:packages # build all workspace packages npm run typecheck:web # type-check the web UI npm run lint # lint the packages npm run check:deps # every import is a declared dependency npm test # unit tests ``` Known failures and the numbers to compare against are in [`docs/oss/baseline.md`](docs/oss/baseline.md). ## Documentation - [Getting Started](docs/GETTING-STARTED.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. ## 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.