docs: merge the two getting-started pages and update the workspaces guide (P2.4)

docs/GETTING-STARTED.md and docs/guides/getting-started.md covered the
same ground; keep one guide in docs/guides that follows the current
setup flow, the two model paths, memory on mem0 and the real keyboard
shortcuts. Drop the product tiers, the signed-Windows-only install, the
.mind files, install.sh and the external coding-agent sign-in.

The workspaces guide loses team workspaces, the .mind files, FTS5 search
and the knowledge graph, and describes virtual and local storage, the
shipped personas and what deleting a workspace removes.
This commit is contained in:
shumeiko.it
2026-11-01 01:57:12 +01:00
parent b8a4134b0a
commit eca050328b
3 changed files with 144 additions and 396 deletions

View File

@@ -1,211 +1,131 @@
# Getting Started with Waggle
# Getting started
This guide walks you through installing Waggle, configuring your API key, creating your first workspace, having your first conversation, and understanding how memory works.
This guide takes you from a fresh install to your first conversation, and explains how Waggle
remembers things between chats.
## Prerequisites
## 1. Install
- **Node.js 20+** (for local server and CLI)
- **An LLM API key** (Anthropic recommended; OpenAI, Google, and 100+ others supported)
- **Rust toolchain** (only if building the desktop app from source)
Install the desktop app or the server installer as described in [install.md](../install.md). Then
open Waggle: start the desktop app, or run `waggle-server`, which opens
http://localhost:3333 in your browser.
## Installation
## 2. Go through the setup
### Option 1: One-line self-host (Linux / macOS)
The first launch walks you through a short setup:
Best for a VPS or homelab, where you want a headless server rather than the desktop app:
1. **Who are you**: your name, role and the kind of work you do. Waggle keeps this in your profile
on this computer and uses it to tailor answers.
2. **Model**: add a model (next section). You can skip this, but chat stays unavailable until a
model is set up.
3. **Pick a starting point**: a template for your first workspace, such as Research Hub, Sales
Pipeline, Engineering or Legal & Compliance, or **Blank Workspace**. Each template comes with a
matching persona.
4. **What's first?**: type a first task for the agent, or pick a suggestion.
```bash
curl -fsSL <repository-raw-url>/main/install.sh | bash # the public repository location is not decided yet
```
## 3. Connect a model
The installer checks prerequisites (Node.js 20+, git — no sudo), clones the repo, builds the packages and web UI, then starts the sidecar and prints its URL (`http://127.0.0.1:3333`). A short wizard (all Enter-defaulted) lets you change the install dir, port, and data dir; add `--yes` to accept every default non-interactively. It boots in echo mode with zero API keys, so the UI works right away — add a provider key later under **Settings → API Keys**.
Waggle needs at least one working model. Choose one of two ways, in the setup or later in
**Settings** → **Models**:
Manage the server afterward with `scripts/waggle-server.sh {start|stop|status|logs}`. Windows users should use the desktop app (Option 2) — the one-line installer targets Linux and macOS only.
- **API key**: choose a provider (Anthropic, OpenAI, Google, DeepSeek, xAI, Mistral, Alibaba
Qwen, MiniMax, Zhipu GLM, Moonshot Kimi, Perplexity or OpenRouter) and paste your key. Waggle
checks it with the provider when it can reach it, and stores it encrypted in the **Vault** on
this computer.
- **Local model**: choose **Install private runtime**. Waggle downloads the official Ollama
runtime, checks it and runs it from its own data directory. Then download a model; Waggle
suggests one that fits your computer. No separate Ollama install, Docker or administrator
rights are needed. If you already run Ollama, Waggle finds it.
### Option 2: Desktop App (Recommended)
In **Settings** → **Models** you also choose the default model, a fallback model and an optional
daily budget.
Download the latest release for your platform from the repository's Releases page (the public repository location is not decided yet).
## 4. Your first conversation
**Windows**: Run the `.msi` installer. Waggle appears in your Start menu.
Type in the chat. The agent streams its answer, and you see what it does along the way:
**macOS**: Open the `.dmg` and drag Waggle to Applications.
- **Tool steps**, such as reading a file, searching the web or saving a memory.
- **Approval requests** for actions that change something outside the chat, such as writing a
file or sending a message. The agent waits until you approve or deny. Settings →
**Permissions** sets how often Waggle asks.
- **Memory**: when you tell the agent something worth keeping, it saves it.
The desktop app bundles a Node.js sidecar that runs the local server automatically.
Good first messages:
### Option 3: CLI / Web
If you prefer a browser-based interface or want to run Waggle without the desktop shell:
```bash
# Clone the repository
git clone <repository-url> waggle
cd waggle
npm install
# Start the local server
cd packages/server
npx tsx src/local/start.ts
```
The server starts on http://localhost:3333. Open it in any browser.
### Option 4: CLI REPL
For a terminal-native experience:
```bash
cd packages/cli
npx tsx src/index.ts
```
## Step 1: Add Your API Key
Waggle needs at least one LLM provider key to function. Anthropic (Claude) is recommended.
### Desktop / Web UI
1. Open **Settings** (gear icon in the sidebar or press `Ctrl+,`)
2. Go to the **Models** tab
3. Click **Add Provider**
4. Select **Anthropic** and paste your API key (starts with `sk-ant-`)
5. Click **Save**
Your key is stored in the local vault (AES-256-GCM encrypted), never sent to Waggle's servers.
### CLI / Config File
Edit `~/.waggle/config.json`:
```json
{
"defaultModel": "claude-sonnet-4-6",
"providers": {
"anthropic": {
"apiKey": "sk-ant-your-key-here",
"models": ["claude-sonnet-4-6", "claude-haiku-3"]
}
}
}
```
### Verify Your Key
In Settings > Models, click **Test Key**. A green checkmark means you are ready.
## Step 2: Create Your First Workspace
Workspaces are the core organizational unit in Waggle. Each workspace has its own memory, sessions, files, and context. Think of a workspace as a dedicated brain for a project or topic.
1. Press **Ctrl+N** or click **New Workspace** in the sidebar
2. Enter a name (e.g., "Product Research" or "Q1 Planning")
3. Choose a group (e.g., "Work", "Personal", "Learning")
4. Optionally select a persona (Researcher, Writer, Coder, etc.)
5. Optionally link a directory on disk for file-aware operations
6. Click **Create**
You land on the **Workspace Home** screen. It shows a summary, suggested prompts, and recent threads.
## Step 3: Your First Conversation
Type a message in the input area. Here are good first messages:
- "Tell me about this project so I can remember it"
- "Help me think through what to work on first"
- "Here is what this project is about: …"
- "Help me plan what to work on first."
- "What can you do in this workspace?"
The agent responds with streaming output. You will see:
### Slash commands
- **Tool calls** shown as collapsible cards (file reads, web searches, memory saves)
- **Memory saves** happening automatically when the agent learns something important
- **Approval gates** for sensitive operations (the agent asks before executing risky actions)
Type `/` in the chat to see the commands, for example `/catchup` for a summary of where the
workspace stands, `/research <topic>`, `/draft <type> [topic]` or `/plan <goal>`. `/help` lists
them all; the [commands reference](../reference/commands.md) describes each one.
### Try a Slash Command
### Files
Type `/catchup` to get a workspace restart summary. Type `/help` to see all 14 commands.
Attach a file to the chat to let the agent read it: PDF, Word (`.docx`), PowerPoint (`.pptx`),
Excel (`.xlsx`), CSV, images, ZIP archives and text or code files, up to 10 MB each.
### Upload a File
## 5. How memory works
Click the paperclip icon or drag a file into the chat. Waggle supports:
Waggle keeps two kinds of memory, both on your computer:
- **Documents**: PDF, DOCX, PPTX
- **Spreadsheets**: XLSX, CSV
- **Images**: PNG, JPG, GIF, WebP, SVG
- **Code**: Any text-based source file
- **Archives**: ZIP (lists contents)
- **Personal memory** follows you across all workspaces: who you are, your preferences, facts
that are not tied to one project.
- **Workspace memory** belongs to one workspace: decisions, findings and project context.
Files are ingested into workspace memory and available to the agent.
Before it answers, the agent recalls what is relevant from personal memory and the current
workspace. Memories get there in three ways:
## Step 4: Understanding Memory
- **You ask**: "Remember that we chose PostgreSQL for the new service."
- **The agent decides** something is worth keeping and saves it.
- **Background extraction**: every few messages, Waggle picks out facts about you, such as your
role or how you like answers, and saves them to personal memory. Turn this off in **Settings**
→ **General** → **Memory**.
Memory is a core product primitive, not a side feature. Two memory layers work together:
Open **Memory** to browse, search, correct, confirm or forget memories. `/memory <query>` searches
from the chat. More detail: [memory.md](../memory.md).
### Personal Mind (`~/.waggle/default.mind`)
## 6. Come back later
Your personal knowledge base. Facts about you, your preferences, recurring context. Shared across all workspaces.
When you return to a workspace:
### Workspace Mind (`~/.waggle/workspaces/{id}/workspace.mind`)
- **Home** shows recent activity and suggests where to continue;
- `/catchup` gives a briefing on where the workspace stands;
- your earlier chats are listed in the workspace, ready to resume;
- the agent recalls the workspace's memory before its first answer.
Project-specific memory. Decisions, research findings, architectural choices, meeting notes. Scoped to one workspace.
## Personas
### How Memory Works
A persona tunes how the agent works: its instructions, preferred tools and suggested commands.
Waggle ships with personas such as Researcher, Writer, Analyst, Coder, Project Manager, Executive
Assistant, Marketer, Legal Counsel and General Purpose. Press `Ctrl+Shift+P` (`Cmd+Shift+P` on
macOS) to switch. See [workspaces.md](workspaces.md#personas).
1. **Auto-save**: The agent automatically saves important information during conversations -- decisions, facts, preferences, and findings.
2. **Explicit save**: You can say "Remember that we decided to use PostgreSQL" and the agent writes it to the appropriate mind.
3. **Memory search**: The agent searches memory before responding, giving you continuity across sessions.
4. **Memory browser**: Open the Memory tab in any workspace to browse, search, and manage stored frames.
## Interface levels
### Memory Frames
**Settings** → **General** offers three interface levels: **Essential**, **Standard** and
**Everything**. Essential shows the basics (Home, Chat, Memory, Files, Vault, Settings).
Everything adds agents, skills, connectors, the marketplace, automations and the system tools.
Each memory unit is a "frame" with:
- **Content**: The actual information
- **Importance**: critical, important, normal, temporary
- **Frame type**: Information (I), Decision (D), Preference (P), etc.
- **Timestamp**: When it was created
- **Access count**: How often it has been retrieved
## Keyboard shortcuts
## Step 5: Return Tomorrow
When you come back to a workspace, Waggle gives you an instant catch-up:
1. **Workspace Home** shows a summary of what happened, recent decisions, and suggested next prompts
2. **Type `/catchup`** for a detailed briefing
3. **Resume a thread** by clicking any recent session in the sidebar
4. **Context is automatic** -- the agent loads relevant memory before its first response
This is the core daily-use loop:
> Open workspace -> instant context -> real work help -> memory-first response -> visible progress -> return later without losing thread
## Next Steps
- **[Workspaces Guide](workspaces.md)** -- Workspace types, switching, home screen, personas
- **[Capabilities Guide](capabilities.md)** -- Install skill packs and browse the marketplace
- **[Connectors Guide](connectors.md)** -- Connect GitHub, Slack, Google, and 26 other services
- **[Commands Reference](../reference/commands.md)** -- All 14 slash commands with examples
- **[Team Mode Guide](team-mode.md)** -- Set up shared workspaces for your team
## File Locations
| Item | Path |
|------|------|
| Config | `~/.waggle/config.json` |
| Personal mind | `~/.waggle/default.mind` |
| Workspace minds | `~/.waggle/workspaces/{id}/workspace.mind` |
| Session logs | `~/.waggle/workspaces/{id}/sessions/*.jsonl` |
| Installed skills | `~/.waggle/skills/*.md` |
| Installed plugins | `~/.waggle/plugins/` |
| Marketplace DB | `~/.waggle/marketplace.db` |
| Vault (encrypted) | `~/.waggle/vault.db` |
| Server logs | Console output (stdout) |
## Keyboard Shortcuts
On macOS use `Cmd` instead of `Ctrl`.
| Shortcut | Action |
|----------|--------|
| `Ctrl+N` | New workspace |
| `Ctrl+,` | Settings |
| `Ctrl+K` | Quick switch workspace |
| `Ctrl+Shift+M` | Toggle memory browser |
| `Enter` | Send message |
| `Shift+Enter` | Newline in message |
| `/` | Start slash command |
|---|---|
| `Ctrl+K` | Search everything |
| `Ctrl+Shift+P` | Switch persona |
| `Ctrl+Tab` | Switch workspace |
| `Ctrl+Shift+N` | Open the chat of the active workspace |
| `Ctrl+/` or `?` | Show all shortcuts |
| `Enter` / `Shift+Enter` | Send / new line |
| `Ctrl+Shift+W` | Show or hide the desktop app window (desktop app only) |
## Next steps
- [Workspaces](workspaces.md): workspaces, sessions, personas and folders on disk
- [Skills, plugins and the marketplace](capabilities.md)
- [Connectors and channels](connectors.md)
- [Troubleshooting](troubleshooting.md)
- [Where your data lives](../install.md#where-your-data-lives)