waggle-os/docs/guides/getting-started.md

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 https://raw.githubusercontent.com/marolinik/waggle-os/main/install.sh | bash

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 GitHub Releases.

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 https://github.com/marolinik/waggle.git
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

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:

{
  "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"
• "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

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.

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:

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