Sample data in tests, prompts and UI placeholders uses Alex Morgan instead of the maintainer's name; decision attributions say "owner". Personal details in two test fixtures are replaced. Local paths (D:/Projects/...) and paths into the maintainer's planning repository are reworded. Clone and install URLs in CONTRIBUTING.md and the getting started guide use placeholders until the public repository location is decided (Q9). The Benchmarks page no longer names the maintainer's hive-mind repository, and the upstream fixes log names the main Waggle repository instead of an internal git host.
7.6 KiB
Getting Started with Waggle
This guide walks you through installing Waggle, configuring your API key, creating your first workspace, having your first conversation, and understanding how memory works.
Prerequisites
- 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)
Installation
Option 1: One-line self-host (Linux / macOS)
Best for a VPS or homelab, where you want a headless server rather than the desktop app:
curl -fsSL <repository-raw-url>/main/install.sh | bash # the public repository location is not decided yet
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.
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.
Option 2: Desktop App (Recommended)
Download the latest release for your platform from the repository's Releases page (the public repository location is not decided yet).
Windows: Run the .msi installer. Waggle appears in your Start menu.
macOS: Open the .dmg and drag Waggle to Applications.
The desktop app bundles a Node.js sidecar that runs the local server automatically.
Option 3: CLI / Web
If you prefer a browser-based interface or want to run Waggle without the desktop shell:
# 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:
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
- Open Settings (gear icon in the sidebar or press
Ctrl+,) - Go to the Models tab
- Click Add Provider
- Select Anthropic and paste your API key (starts with
sk-ant-) - 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:
{
"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.
- Press Ctrl+N or click New Workspace in the sidebar
- Enter a name (e.g., "Product Research" or "Q1 Planning")
- Choose a group (e.g., "Work", "Personal", "Learning")
- Optionally select a persona (Researcher, Writer, Coder, etc.)
- Optionally link a directory on disk for file-aware operations
- 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"
- "What can you do in this workspace?"
The agent responds with streaming output. You will see:
- 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)
Try a Slash Command
Type /catchup to get a workspace restart summary. Type /help to see all 14 commands.
Upload a File
Click the paperclip icon or drag a file into the chat. Waggle supports:
- Documents: PDF, DOCX, PPTX
- Spreadsheets: XLSX, CSV
- Images: PNG, JPG, GIF, WebP, SVG
- Code: Any text-based source file
- Archives: ZIP (lists contents)
Files are ingested into workspace memory and available to the agent.
Step 4: Understanding Memory
Memory is a core product primitive, not a side feature. Two memory layers work together:
Personal Mind (~/.waggle/default.mind)
Your personal knowledge base. Facts about you, your preferences, recurring context. Shared across all workspaces.
Workspace Mind (~/.waggle/workspaces/{id}/workspace.mind)
Project-specific memory. Decisions, research findings, architectural choices, meeting notes. Scoped to one workspace.
How Memory Works
- Auto-save: The agent automatically saves important information during conversations -- decisions, facts, preferences, and findings.
- Explicit save: You can say "Remember that we decided to use PostgreSQL" and the agent writes it to the appropriate mind.
- Memory search: The agent searches memory before responding, giving you continuity across sessions.
- Memory browser: Open the Memory tab in any workspace to browse, search, and manage stored frames.
Memory Frames
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
Step 5: Return Tomorrow
When you come back to a workspace, Waggle gives you an instant catch-up:
- Workspace Home shows a summary of what happened, recent decisions, and suggested next prompts
- Type
/catchupfor a detailed briefing - Resume a thread by clicking any recent session in the sidebar
- 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 -- Workspace types, switching, home screen, personas
- Capabilities Guide -- Install skill packs and browse the marketplace
- Connectors Guide -- Connect GitHub, Slack, Google, and 26 other services
- Commands Reference -- All 14 slash commands with examples
- Team Mode Guide -- 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
| 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 |