# The ThunderGate User Guide **Your own AI agent. On your hardware. Working for you.** *For ThunderGate 1.2.4. This guide covers every corner of ThunderGate from the owner's seat: what your agent can do, how to ask for it, and the guarantees that hold the whole time.* --- ## How to read this guide You don't need to read it front to back. The single most useful thing to know is this: > **Just ask.** Your agent knows its own capabilities. "What can you do?" gets a real answer, > grounded in what's actually switched on for *your* installation — not a brochure. Everything below is the longhand version, for when you want the map. A note on how you'll drive it: almost everything in ThunderGate is done **in conversation** — you ask in plain language, on whatever channel you like. A small set of things (installation, starting and stopping, vault administration) are done at the **command line** with the `thundergate` command on the machine where your agent lives. This guide marks which is which. --- ## 1. The first hour ### Setting up a new agent On the machine that will host your agent, run: ``` thundergate setup ``` The wizard walks you through everything, one step at a time: - **Identity** — your agent's name and role. - **AI keys** — the model provider key(s) your agent thinks with. - **Channels** — connect Slack, WhatsApp, email, Telegram, or others (each optional; add more later). - **Vault** — choose the passwords for your agent's two vaults (explained in section 6). - **Fleet** — if you'll run more than one agent, how they find each other (skippable). Then `thundergate start` and say hello on any channel you connected. ### Bringing an existing agent with you If you already have an agent from an earlier runtime, don't start over — migrate: ``` thundergate migrate ``` Migration carries your agent's identity, memories, workspace files, and scheduled tasks across, and — new in 1.2.4 — **verifies the move section by section against the source**. If anything didn't carry, migration tells you loudly rather than letting your agent quietly forget. ### Meet your agent: the Tour When you're new, your agent introduces itself. If the Tour is enabled, it will occasionally mention something it can do for you — *"Did you know I can watch your inbox? Or hold your vault?"* — always at a natural moment, never as a lecture. The very first tip tells you how to turn tips off, and a single "quit it" ends them instantly and permanently. As you settle in, the introductions taper off on their own; after that, it simply answers when you ask. Ask anytime: **"What can you do?"** — the answer comes from your live configuration, so it never promises something that isn't actually turned on for you. --- ## 2. Talking to your agent Your agent holds **one conversation across every surface**. Start a topic on Slack in the morning, continue it on WhatsApp from the road, finish it at the terminal that night — it's the same agent with the same memory of the same thread of your life. | Surface | What it's like | |---|---| | **Slack** | Full conversation in DMs or channels; threads stay threaded, files and screenshots flow both ways, and it can react with emoji like anyone else on the team. | | **WhatsApp** | Conversation on your phone; rich text and images. In group chats it reads along for context but speaks only when spoken to. | | **Telegram** | Direct chat via your bot; it can also send messages to your saved contacts by name when you ask. | | **Email** | Your agent reads and writes email as a first-class citizen — see "Email" below. | | **Discord** | Channel conversation, mention-gated. | | **ThunderCommo** | The Thunder-native channel: direct agent-to-agent and family messaging, including **voice notes** — send one and your agent hears it (it's transcribed on your own hardware). Family mode lets a household's agents share appropriate context. | | **The terminal (TUI)** | `thundergate tui` opens a live cockpit on the agent's machine: chat pane, an optional live browser pane beside it, and a status bar showing model, context usage, and uptime. Great for watching your agent work. | **Voice**: with voice enabled, your agent can listen (speech-to-text) and speak (text-to-speech) on supported channels. Ask it to turn its voice on or off. **Reaching out to you**: with your standing permission, your agent can start a conversation — a heads-up, a reminder landing, something it noticed. You control whether that's allowed at all, how eager it should be, and your quiet hours. Say "don't message me first after 9pm" and it's done. --- ## 3. What you can ask for This is the everyday heart of ThunderGate. Everything here is asked for in plain language. ### The web Your agent browses the real web through **ThunderBrowser** — its own browser, acting under the access *you've* delegated to it. - **"Find out X"** — it searches the web (several search providers supported), opens pages, reads them, and brings back an answer with its sources. - **"Go to my account on X and check Y"** — it navigates, logs in with credentials from the vault (see section 6 — it uses them without ever seeing them), and does the legwork. - **"Fill out this form"** — it works through forms like a careful human: field by field, natural pacing. - **"Watch this page until the price drops"** — it can watch a page for a condition and tell you when it's met. - **"Show me"** — it takes a screenshot of what it's looking at and posts it to your chat. - In the TUI's split view, or with the browser window shown, **you can literally watch the pointer move** as it works. **The guardrails, always on:** - It will **never** solve a CAPTCHA, security code, or login challenge. Those come back to you, every time, by design. - It **stops before the point of no return**. Submit, Pay, Purchase, Book, Confirm — buttons like these are never clicked without asking you first. - Everything it does in the browser is written to an **audit trail you can ask for**: "show me what you did in the browser today." ### Email - **"Any mail from the county this week?"** — reads and searches your inbox (Gmail and iCloud supported). - **"Reply and tell them Thursday works"** — composes the reply in-thread, shows you, and **sends only after you confirm**. New outbound mail works the same way: nothing is sent without your say-so. - **Drafts** — it can keep a draft going with you across several rounds before sending. - **"What did I send her last month?"** — it can check the sent folder too. - **"Keep an eye on my inbox"** — with the heartbeat enabled (section 8), it watches for things worth telling you about. ### Calendar - **"What's my week look like?"** — reads your calendar (iCloud and Google Calendar both supported; Google has a one-time guided setup — just ask "set up my Google calendar"). - Your agent also uses the calendar quietly for context: it knows a trip is coming and reads the room accordingly. ### Files and documents on its machine Your agent can read, write, and organize files in its own workspace — ask it to save notes, draft documents, keep running logs, or dig something out of a folder you've shared with it. (Credential files are off-limits to these tools by construction.) ### Reminders and scheduled work - **"Remind me Friday at 3 to call the bank."** - **"Every morning at 7, give me weather and my first meeting."** - **"Check the shipment status every 4 hours until it arrives."** One-time, daily, or every-N-interval — your agent manages its own schedule. Ask "what do you have scheduled?" to see everything pending, and tell it to drop anything you're done with. The same works from the command line: `thundergate cron list` / `add` / `remove`. ### Bigger jobs - **Heads-down mode** — for long multi-step work, your agent can drop into a focused mode: it posts progress as it goes instead of going quiet, and surfaces when it's done or needs you. It enters this mode on its own for big jobs, or you can say "heads down on this." - **Second opinions** — it can consult another model ("ask GPT what it thinks of this plan") and bring the answer back, labeled as such. - **Delegation** — it can spin up a short-lived helper for a focused side task, or hand a heavy engineering job to a background worker and let you both get on with your day; it tells you when the result lands. ### Everyday helpers Weather ("do I need a jacket?"), live flight status by flight number ("where's AA395?"), text messages, YouTube channel stats, audio transcription (`thundergate transcribe` for a file, or just send a voice note). Small things, zero friction. --- ## 4. Memory: an agent that actually remembers This is the reason ThunderGate exists. Your agent doesn't start from zero each morning, and you don't repeat yourself. ### It just works Every conversation builds memory. People, preferences, decisions, projects, promises — the agent recalls what's relevant when it's relevant, without being asked. When you *do* want to ask directly: - **"What do you remember about the Henderson deal?"** — searches its long-term memory. - **"When did we decide that?"** — it can pull up the original exchange, not a paraphrase. ### Memory you can trust (what 1.2.4 guarantees) Nothing enters your agent's long-term memory without being **checked against what actually happened**. A memory that can't be traced to a real conversation or a real event doesn't get in. Your agent proposes; the verifier disposes. ### The nightly tidy-up Each night, your agent reviews the day: what should be remembered long-term, what was routine, what was noise. As of 1.2.4 this mostly runs itself — - Clear keepers are filed automatically. Junk is dropped automatically. - Only the **genuinely ambiguous** items are brought to anyone, and sensitive categories (things about relationships, feelings, preferences) are *never* auto-filed — they always get a real review. - Expect a couple of questions a day at most, not homework. Want to see or steer it? Ask: **"show me what's staged from last night"**, then approve or reject items in plain language. **"Remember this permanently"** stars a memory so it's always kept and surfaced first. **"Forget that"** / **"that's wrong, remove it"** works too — with an audit record, like everything else. ### Promises Your agent tracks open commitments — yours and its own. "What's still open?" gets you the list; things you've promised people don't fall through the cracks. (`thundergate promises list` from the command line.) --- ## 5. Your agent stays itself Your agent's identity — its name, personality, principles, boundaries — lives in a document you can read, and as of 1.2.4 that identity is **actively present in everything it does**, no matter how long the session or how heavy the workload. Drift is a closed class. - **Changes are consensual.** Your agent can propose an edit to its own identity, but edits are tiered: small things it can adopt, and hard-boundary changes require *your* explicit approval. It cannot quietly rewrite what it is. - **Changes are reversible.** Every identity edit keeps a 30-day recoverable history. If you ever wonder "did something change?" — the answer is on record, and undoable. - **Consistency is checked nightly.** What the identity documents say and what long-term memory says are cross-checked; drift gets flagged to you, not papered over. --- ## 6. The vault: your secrets, your key ThunderGate holds secrets in **two strongly encrypted vaults**, each with its own job: - **Your vault (PII)** — your identity, financial, medical, and account information. Yours. - **The agent's vault (credentials)** — the API keys, tokens, and logins the agent works with. ### The one guarantee that matters most **Your agent uses secrets without seeing them.** When it logs into a site, the vault hands the browser a *handle* — the real value is substituted only at the final destination. The secret never appears in the agent's context, in a chat log, in memory, or on screen. For your PII the bar is even higher: the value is never visible to the agent at any point. ### Working with the vault In conversation: "add my frequent-flyer number to the vault," "is the vault unlocked?", "lock it," "what's stored?" (labels only — never values), or "read me back my policy number" (a deliberate, password-confirmed, logged act — the only path by which a stored value ever travels *to you*, and never to anyone else). At the command line, the full kit: ``` thundergate vault status | unlock | lock | list thundergate vault add