# Getting started This guide takes you from a fresh install to your first conversation, and explains how Waggle remembers things between chats. ## 1. Install 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. ## 2. Go through the setup The first launch walks you through a short setup: 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. ## 3. Connect a model Waggle needs at least one working model. Choose one of two ways, in the setup or later in **Settings** → **Models**: - **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. In **Settings** → **Models** you also choose the default model, a fallback model and an optional daily budget. ## 4. Your first conversation Type in the chat. The agent streams its answer, and you see what it does along the way: - **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. Good first messages: - "Here is what this project is about: …" - "Help me plan what to work on first." - "What can you do in this workspace?" ### Slash commands Type `/` in the chat to see the commands, for example `/catchup` for a summary of where the workspace stands, `/research `, `/draft [topic]` or `/plan `. `/help` lists them all; the [commands reference](../reference/commands.md) describes each one. ### Files 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. ## 5. How memory works Waggle keeps two kinds of memory, both on your computer: - **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. Before it answers, the agent recalls what is relevant from personal memory and the current workspace. Memories get there in three ways: - **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**. Open **Memory** to browse, search, correct, confirm or forget memories. `/memory ` searches from the chat. More detail: [memory.md](../memory.md). ## 6. Come back later When you return to a workspace: - **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. ## Personas 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). ## Interface levels **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. ## Keyboard shortcuts On macOS use `Cmd` instead of `Ctrl`. | Shortcut | Action | |---|---| | `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)