diff --git a/README.md b/README.md index 36d8408..618b8e0 100644 --- a/README.md +++ b/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, -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. +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. -> **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). +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. -## 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. -``` -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 -``` +## Install -`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 + 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 -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 -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 +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. 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)). +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. -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. +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`. -**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`. +Add a model in the app (Settings → Models). `.env.example` lists optional environment +variables; a basic local run needs none of them. -| 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. | +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 # 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 +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 ``` -Known failures and the numbers to compare against are in -[`docs/oss/baseline.md`](docs/oss/baseline.md). +[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 -- [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) -- [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. +- 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 -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. +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).