LLM/pocketpaw
1
0
Fork 0
mirror of https://github.com/pocketpaw/pocketpaw.git synced 2026-05-13 21:21:53 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(seo): add guides section, FAQ schema, and internal linking

Browse Source 
5 SEO-targeted tutorial guides for long-tail keyword traffic:
- Self-host an AI agent on your laptop
- Build a Telegram AI bot in 5 minutes
- Add AI to your Discord server
- Run AI with Ollama (no API key)
- AI agents vs chatbots comparison

Landing page: FAQ section with FAQPage JSON-LD schema markup
(targets Google "People Also Ask" snippets).

Internal linking: cross-links from channels, backends, and
introduction pages back to relevant guides. Updated navbar
dropdown and footer with guide links.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Prakash
2026-03-08 17:14:47 +05:30
parent 73e110aabe
commit 0deaddec7c
11 changed files with 979 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files

130
docs/_landing/index.html
View File

@@ -87,6 +87,62 @@
}
}
</script>
<script type="application/ld+json">
{
"@context": "https://schema.org",
"@type": "FAQPage",
"mainEntity": [
{
"@type": "Question",
"name": "What is a self-hosted AI agent?",
"acceptedAnswer": {
"@type": "Answer",
"text": "A self-hosted AI agent is software that runs on your own computer or server instead of in the cloud. It can answer questions, execute code, browse the web, manage files, and take actions on your behalf — all while keeping your data private. PocketPaw is an open-source self-hosted AI agent that connects to Telegram, Discord, Slack, WhatsApp, and more."
}
},
{
"@type": "Question",
"name": "Can I run an AI agent without an API key?",
"acceptedAnswer": {
"@type": "Answer",
"text": "Yes. PocketPaw works with Ollama, which runs open-source language models (like Llama, Qwen, Mistral) directly on your hardware. No API keys, no accounts, no usage fees. You need at least 4GB of RAM for a 7B parameter model."
}
},
{
"@type": "Question",
"name": "What messaging platforms does PocketPaw support?",
"acceptedAnswer": {
"@type": "Answer",
"text": "PocketPaw connects to 9+ platforms: Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Microsoft Teams, Google Chat, and a built-in web dashboard. All channels share the same AI agent, tools, and conversation memory."
}
},
{
"@type": "Question",
"name": "Is PocketPaw free to use?",
"acceptedAnswer": {
"@type": "Answer",
"text": "PocketPaw is completely free and open-source under the MIT license. The software itself has no cost. If you use cloud AI providers like Anthropic or OpenAI, their standard API pricing applies. For zero-cost operation, use Ollama with free local models."
}
},
{
"@type": "Question",
"name": "What's the difference between an AI agent and a chatbot?",
"acceptedAnswer": {
"@type": "Answer",
"text": "A chatbot generates text responses to questions. An AI agent can take actions: browsing websites, executing code, managing files, sending emails, and completing multi-step tasks autonomously. PocketPaw is an AI agent with 50+ built-in tools that can act on your behalf across multiple platforms."
}
},
{
"@type": "Question",
"name": "How do I install PocketPaw?",
"acceptedAnswer": {
"@type": "Answer",
"text": "Run 'pip install pocketpaw' or use the interactive installer: 'curl -fsSL https://pocketpaw.xyz/install.sh | sh'. Then run 'pocketpaw' to start the web dashboard. The whole process takes under 5 minutes. PocketPaw requires Python 3.11 or higher."
}
}
]
}
</script>
<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
@@ -3172,6 +3228,71 @@
</div>
</section>
<!-- ───────────── FAQ ───────────── -->
<section style="padding: 80px 0; background: var(--bg, #f9f8f6);">
<div class="wrap" style="max-width: 800px;">
<h2 class="heading scroll-text" style="text-align: center; margin-bottom: 48px; font-size: clamp(1.6rem, 3vw, 2.2rem);">
Frequently Asked Questions
</h2>
<div style="display: flex; flex-direction: column; gap: 16px;">
<details style="border: 1px solid rgba(26,26,46,0.08); border-radius: 12px; padding: 20px 24px; background: var(--card, #fff);">
<summary style="cursor: pointer; font-weight: 600; font-size: 1.05rem; font-family: 'Plus Jakarta Sans', sans-serif; color: var(--text, #1a1a2e); list-style: none; display: flex; justify-content: space-between; align-items: center;">
What is a self-hosted AI agent?
</summary>
<p style="margin-top: 12px; line-height: 1.7; color: rgba(26,26,46,0.7); font-size: 0.95rem;">
A self-hosted AI agent runs on your own computer or server instead of in the cloud. It can answer questions, execute code, browse the web, manage files, and take actions on your behalf. Your data stays on your machine. PocketPaw is an open-source self-hosted AI agent that connects to Telegram, Discord, Slack, WhatsApp, and more.
</p>
</details>
<details style="border: 1px solid rgba(26,26,46,0.08); border-radius: 12px; padding: 20px 24px; background: var(--card, #fff);">
<summary style="cursor: pointer; font-weight: 600; font-size: 1.05rem; font-family: 'Plus Jakarta Sans', sans-serif; color: var(--text, #1a1a2e); list-style: none; display: flex; justify-content: space-between; align-items: center;">
Can I run PocketPaw without an API key?
</summary>
<p style="margin-top: 12px; line-height: 1.7; color: rgba(26,26,46,0.7); font-size: 0.95rem;">
Yes. PocketPaw works with <a href="/guides/local-llm-agent" style="color: #0A84FF;">Ollama</a>, which runs open-source models (Llama, Qwen, Mistral) directly on your hardware. No API keys, no accounts, no usage fees. You need at least 4GB of RAM for a 7B parameter model.
</p>
</details>
<details style="border: 1px solid rgba(26,26,46,0.08); border-radius: 12px; padding: 20px 24px; background: var(--card, #fff);">
<summary style="cursor: pointer; font-weight: 600; font-size: 1.05rem; font-family: 'Plus Jakarta Sans', sans-serif; color: var(--text, #1a1a2e); list-style: none; display: flex; justify-content: space-between; align-items: center;">
What messaging platforms does PocketPaw support?
</summary>
<p style="margin-top: 12px; line-height: 1.7; color: rgba(26,26,46,0.7); font-size: 0.95rem;">
PocketPaw connects to 9+ platforms: Telegram, Discord, Slack, WhatsApp, Signal, Matrix, Microsoft Teams, Google Chat, and a built-in web dashboard. All channels share the same AI agent, tools, and conversation memory.
</p>
</details>
<details style="border: 1px solid rgba(26,26,46,0.08); border-radius: 12px; padding: 20px 24px; background: var(--card, #fff);">
<summary style="cursor: pointer; font-weight: 600; font-size: 1.05rem; font-family: 'Plus Jakarta Sans', sans-serif; color: var(--text, #1a1a2e); list-style: none; display: flex; justify-content: space-between; align-items: center;">
Is PocketPaw free?
</summary>
<p style="margin-top: 12px; line-height: 1.7; color: rgba(26,26,46,0.7); font-size: 0.95rem;">
Completely free and open-source under the MIT license. If you use cloud providers like Anthropic or OpenAI, their standard API pricing applies. For zero-cost operation, use Ollama with local models.
</p>
</details>
<details style="border: 1px solid rgba(26,26,46,0.08); border-radius: 12px; padding: 20px 24px; background: var(--card, #fff);">
<summary style="cursor: pointer; font-weight: 600; font-size: 1.05rem; font-family: 'Plus Jakarta Sans', sans-serif; color: var(--text, #1a1a2e); list-style: none; display: flex; justify-content: space-between; align-items: center;">
What's the difference between an AI agent and a chatbot?
</summary>
<p style="margin-top: 12px; line-height: 1.7; color: rgba(26,26,46,0.7); font-size: 0.95rem;">
A chatbot generates text responses. An AI agent can take real actions: browsing websites, writing code, managing files, sending emails, and completing multi-step tasks. PocketPaw ships with <a href="/tools" style="color: #0A84FF;">50+ built-in tools</a> that let it act on your behalf. <a href="/guides/ai-agent-vs-chatbot" style="color: #0A84FF;">Read the full comparison</a>.
</p>
</details>
<details style="border: 1px solid rgba(26,26,46,0.08); border-radius: 12px; padding: 20px 24px; background: var(--card, #fff);">
<summary style="cursor: pointer; font-weight: 600; font-size: 1.05rem; font-family: 'Plus Jakarta Sans', sans-serif; color: var(--text, #1a1a2e); list-style: none; display: flex; justify-content: space-between; align-items: center;">
How do I install PocketPaw?
</summary>
<p style="margin-top: 12px; line-height: 1.7; color: rgba(26,26,46,0.7); font-size: 0.95rem;">
Run <code style="background: rgba(10,132,255,0.08); padding: 2px 6px; border-radius: 4px; font-family: 'JetBrains Mono', monospace; font-size: 0.85rem;">pip install pocketpaw</code> or use the interactive installer. Then run <code style="background: rgba(10,132,255,0.08); padding: 2px 6px; border-radius: 4px; font-family: 'JetBrains Mono', monospace; font-size: 0.85rem;">pocketpaw</code> to start the web dashboard. Takes under 5 minutes. Requires Python 3.11+. See the <a href="/getting-started/installation" style="color: #0A84FF;">full installation guide</a>.
</p>
</details>
</div>
</div>
</section>
<!-- ───────────── FOOTER ───────────── -->
<footer>
<div class="wrap foot">
@@ -3185,11 +3306,12 @@
<span class="foot-sm">Built by You &amp; Us</span>
</div>
<div class="foot-links">
<a href="/getting-started/install" class="foot-a">Get Started</a>
<a href="/getting-started/installation" class="foot-a">Get Started</a>
<a href="/introduction" class="foot-a">Docs</a>
<a href="/channels/overview" class="foot-a">Channels</a>
<a href="/tools/overview" class="foot-a">Tools</a>
<a href="/backends/overview" class="foot-a">Backends</a>
<a href="/guides" class="foot-a">Guides</a>
<a href="/channels" class="foot-a">Channels</a>
<a href="/tools" class="foot-a">Tools</a>
<a href="/backends" class="foot-a">Backends</a>
<a
href="https://github.com/pocketpaw/pocketpaw"
target="_blank"

11
docs/backends/index.mdx
View File

@@ -88,3 +88,14 @@ The following backends have been removed but their config values are automatical
| `gemini_cli` | `google_adk` | Feb 2026 |
If your config still uses a legacy backend name, PocketPaw will silently redirect to the mapped backend.
## Guides
<CardGroup>
<Card title="Run AI with Ollama" icon="lucide:hard-drive" href="/guides/local-llm-agent">
Set up free local models with no API key needed.
</Card>
<Card title="Self-Host Guide" icon="lucide:server" href="/guides/self-host-ai-agent">
Full walkthrough for running PocketPaw on your own hardware.
</Card>
</CardGroup>

16
docs/channels/index.mdx
View File

@@ -129,3 +129,19 @@ export POCKETPAW_SLACK_ALLOWED_CHANNEL_IDS="C01,C02"
# WhatsApp
export POCKETPAW_WHATSAPP_ALLOWED_PHONE_NUMBERS="+1234567890"
```
## Guides
Step-by-step tutorials for setting up specific channels:
<CardGroup>
<Card title="Build a Telegram AI Bot" icon="lucide:send" href="/guides/telegram-ai-bot">
Create a personal AI assistant on Telegram in 5 minutes.
</Card>
<Card title="Discord AI Bot" icon="lucide:gamepad-2" href="/guides/discord-ai-bot">
Add an AI assistant to your Discord server with slash commands.
</Card>
<Card title="Self-Host Guide" icon="lucide:server" href="/guides/self-host-ai-agent">
Run your own AI agent on a laptop or home server.
</Card>
</CardGroup>

68
docs/docs-config.json
View File

@@ -42,24 +42,29 @@
"type": "dropdown",
"items": [
{
"label": "Channels",
"href": "/channels",
"description": "Connect to 9+ messaging platforms"
"label": "Self-Host an AI Agent",
"href": "/guides/self-host-ai-agent",
"description": "Run your own AI assistant on a laptop or server"
},
{
"label": "Integrations",
"href": "/integrations",
"description": "Gmail, Calendar, Drive, Spotify, and more"
"label": "Telegram AI Bot",
"href": "/guides/telegram-ai-bot",
"description": "Build a personal AI bot on Telegram in 5 minutes"
},
{
"label": "Tools",
"href": "/tools",
"description": "50+ built-in tools and custom tool creation"
"label": "Discord AI Bot",
"href": "/guides/discord-ai-bot",
"description": "Add AI to your Discord server with slash commands"
},
{
"label": "API Reference",
"href": "/api",
"description": "REST and WebSocket APIs"
"label": "Run AI with Ollama",
"href": "/guides/local-llm-agent",
"description": "Free, private AI using local models — no API key"
},
{
"label": "All Guides",
"href": "/guides",
"description": "Browse all tutorials and walkthroughs"
}
]
}
@@ -83,7 +88,7 @@
"label": "Documentation",
"href": "/introduction",
"icon": "lucide:book-open",
"groups": ["Introduction", "Getting Started", "Core Concepts", "Channels", "Agent Backends", "Tools", "Integrations", "Security", "Memory", "Advanced", "Deployment"]
"groups": ["Introduction", "Getting Started", "Guides", "Core Concepts", "Channels", "Agent Backends", "Tools", "Integrations", "Security", "Memory", "Advanced", "Deployment"]
},
{
"label": "API Reference",
@@ -140,6 +145,41 @@
}
]
},
{
"label": "Guides",
"items": [
{
"label": "Overview",
"href": "/guides",
"icon": "lucide:compass"
},
{
"label": "Self-Host an AI Agent",
"href": "/guides/self-host-ai-agent",
"icon": "lucide:server"
},
{
"label": "Build a Telegram AI Bot",
"href": "/guides/telegram-ai-bot",
"icon": "lucide:send"
},
{
"label": "Discord AI Bot",
"href": "/guides/discord-ai-bot",
"icon": "lucide:gamepad-2"
},
{
"label": "Run AI with Ollama",
"href": "/guides/local-llm-agent",
"icon": "lucide:hard-drive"
},
{
"label": "AI Agents vs Chatbots",
"href": "/guides/ai-agent-vs-chatbot",
"icon": "lucide:scale"
}
]
},
{
"label": "Core Concepts",
"items": [
@@ -772,8 +812,8 @@
"title": "Documentation",
"items": [
{ "label": "Getting Started", "href": "/getting-started/installation" },
{ "label": "Guides & Tutorials", "href": "/guides" },
{ "label": "Architecture", "href": "/concepts/architecture" },
{ "label": "Channels", "href": "/channels" },
{ "label": "API Reference", "href": "/api" }
]
},

114
docs/guides/ai-agent-vs-chatbot.mdx Normal file
View File

@@ -0,0 +1,114 @@
---
title: "AI Agents vs Chatbots: What's the Difference?"
description: "AI agents can take actions, use tools, and work autonomously. Chatbots just generate text. Here's a practical breakdown of the differences and when to use each."
section: Guides
ogType: article
keywords: ["ai agent vs chatbot", "difference between ai agent and chatbot", "what is an ai agent", "ai agent explained", "chatbot vs agent"]
tags: ["guide", "concepts", "comparison", "educational"]
---
# AI Agents vs Chatbots: What's the Difference?
The terms get used interchangeably, but they describe very different capabilities. Understanding the distinction helps you pick the right tool for your use case.
## The Short Version
**Chatbots** generate text responses based on input. That's it. They can't browse websites, create files, check your email, or take any action in the real world.
**AI agents** can think, plan, and act. They use tools to accomplish tasks: browsing the web, writing code, managing files, calling APIs. They break complex requests into steps and execute them.
## A Practical Comparison
| Capability | Chatbot | AI Agent |
|-----------|---------|----------|
| Answer questions | Yes | Yes |
| Remember past conversations | Sometimes | Yes |
| Search the web | No | Yes |
| Read and write files | No | Yes |
| Execute code | No | Yes |
| Send emails | No | Yes |
| Browse websites | No | Yes |
| Break down complex tasks | No | Yes |
| Work across platforms | Rarely | Yes |
| Learn from interactions | No | Yes (via memory) |
## What Makes an Agent an Agent?
Three things separate agents from chatbots:
### 1. Tool Use
An agent has access to tools, functions it can call to interact with the outside world. When you ask "what's trending on Hacker News?", a chatbot guesses based on its training data. An agent opens a browser, navigates to the site, and reads the actual current page.
PocketPaw ships with 50+ tools:
- Web search (Tavily, Brave)
- Browser automation (Playwright)
- File system operations
- Image generation
- Gmail, Calendar, Drive integration
- Code execution
- Desktop automation, OCR, voice synthesis
### 2. Planning and Reasoning
Ask a chatbot to "organize my downloads folder by file type." It'll tell you how to do it. An agent figures out the steps, lists the files, creates folders, and moves everything.
Agents maintain an internal plan:
1. List files in ~/Downloads
2. Identify file types
3. Create folders (images/, documents/, videos/)
4. Move each file to the right folder
5. Report what was done
### 3. Memory
Chatbots typically start fresh each conversation. Agents remember context across sessions and platforms.
Tell your agent "I prefer dark mode in all my apps" on Telegram. It remembers that preference when you chat through Discord later.
## When to Use a Chatbot
Chatbots are fine when you just need:
- Quick answers to simple questions
- Text generation (drafting emails, brainstorming)
- Translation
- Summarization
If your use case is "ask question, get text back," a chatbot works.
## When to Use an Agent
Switch to an agent when you need:
- **Actions taken on your behalf**: file management, web browsing, email handling
- **Multi-step workflows**: research a topic, compile findings, create a report
- **Persistent context**: an assistant that knows your preferences and history
- **Cross-platform access**: same assistant on phone, desktop, and web
- **Privacy**: self-hosted, your data stays on your machine
## How PocketPaw Fits In
PocketPaw is an AI agent framework. It connects to an LLM (Claude, GPT, Gemini, or local Ollama models) and wraps it with tools, memory, security, and multi-channel access.
The LLM provides intelligence. PocketPaw provides agency.
```
Chatbot: User → LLM → Text Response
Agent: User → LLM + Tools + Memory + Planning → Actions + Response
↕ ↕ ↕
Web Search File System Past Context
```
## Try It Yourself
<CardGroup>
<Card title="Install PocketPaw" icon="lucide:download" href="/getting-started/installation">
Go from chatbot to agent in under 5 minutes.
</Card>
<Card title="Self-Host Guide" icon="lucide:server" href="/guides/self-host-ai-agent">
Run your own AI agent on your laptop or home server.
</Card>
<Card title="Run Free with Ollama" icon="lucide:hard-drive" href="/guides/local-llm-agent">
No API keys needed. Run entirely on your hardware.
</Card>
</CardGroup>

133
docs/guides/discord-ai-bot.mdx Normal file
View File

@@ -0,0 +1,133 @@
---
title: "Add an AI Assistant to Your Discord Server"
description: "Set up a self-hosted AI bot for your Discord server with slash commands, DM support, streaming responses, and 50+ tools. No monthly fees, runs on your machine."
section: Guides
ogType: article
keywords: ["discord ai bot", "discord ai assistant", "self-hosted discord bot", "ai bot for discord server", "discord chatbot python"]
tags: ["guide", "discord", "bot", "community"]
---
# Add an AI Assistant to Your Discord Server
Discord bots are everywhere, but most are wrappers around a single API call. No memory, no tools, no ability to actually do things. PocketPaw gives your Discord server a proper AI agent that can search the web, analyze files, generate images, and remember conversations.
This guide gets a PocketPaw-powered Discord bot running in your server.
## What You'll Build
- `/paw` slash command for interacting with the AI
- DM support for private conversations
- @mention support in channels
- Streaming responses (edits in real-time as the AI thinks)
- Persistent memory across conversations
- Access to 50+ tools (web search, image gen, file handling, and more)
## Prerequisites
- **PocketPaw installed** (follow the [installation guide](/getting-started/installation))
- **A Discord account** with permission to add bots to a server
- **An AI provider**: Anthropic API key or [Ollama](/guides/local-llm-agent)
## Setting Up the Bot
<Steps>
<Step title="Create a Discord Application">
1. Go to the [Discord Developer Portal](https://discord.com/developers/applications)
2. Click "New Application" and give it a name
3. Go to the **Bot** section in the sidebar
4. Click "Reset Token" and copy the bot token
Under **Privileged Gateway Intents**, enable:
- **Message Content Intent** (required for reading messages)
</Step>
<Step title="Invite the bot to your server">
1. Go to **OAuth2 > URL Generator**
2. Select scopes: `bot`, `applications.commands`
3. Select permissions: `Send Messages`, `Read Message History`, `Use Slash Commands`, `Embed Links`, `Attach Files`
4. Copy the generated URL and open it in your browser
5. Select your server and authorize
</Step>
<Step title="Install the Discord extra">
```bash
pip install pocketpaw[discord]
```
</Step>
<Step title="Configure environment variables">
```bash
export POCKETPAW_DISCORD_BOT_TOKEN="your-bot-token"
export POCKETPAW_ANTHROPIC_API_KEY="sk-ant-..." # or use Ollama
# Optional: restrict to specific servers and users
export POCKETPAW_DISCORD_ALLOWED_GUILD_IDS="111222333444"
export POCKETPAW_DISCORD_ALLOWED_USER_IDS="555666777888"
```
</Step>
<Step title="Start PocketPaw">
```bash
pocketpaw
```
The web dashboard starts at localhost:8888, and your Discord bot comes online automatically. You can also run headless:
```bash
pocketpaw --discord
```
</Step>
<Step title="Test in Discord">
- Type `/paw what can you do?` in any channel
- DM the bot directly for private conversations
- @mention the bot in a channel message
The bot streams its response in real-time, editing the message as new text arrives.
</Step>
</Steps>
## How Streaming Works
Discord has rate limits on message edits (roughly one edit per 1.5 seconds). PocketPaw buffers chunks and updates the message at safe intervals, so responses appear smoothly without hitting rate limits.
## Access Control
Control who can use the bot and where:
```bash
# Only specific servers
export POCKETPAW_DISCORD_ALLOWED_GUILD_IDS="111222333,444555666"
# Only specific users
export POCKETPAW_DISCORD_ALLOWED_USER_IDS="123456789,987654321"
```
Without these restrictions, anyone in the server can use the bot. For public communities, setting allowed user IDs is strongly recommended.
## Running Multiple Channels
PocketPaw handles multiple channels from a single instance. Add Telegram alongside Discord:
```bash
pip install pocketpaw[telegram,discord]
export POCKETPAW_TELEGRAM_BOT_TOKEN="your-telegram-token"
export POCKETPAW_DISCORD_BOT_TOKEN="your-discord-token"
pocketpaw
```
Both bots share the same agent, tools, and memory system. A conversation started on Discord can be continued on Telegram (through the shared memory).
## Next Steps
<CardGroup>
<Card title="Discord Channel Docs" icon="lucide:book-open" href="/channels/discord">
Full reference for Discord-specific features, events, and configuration.
</Card>
<Card title="Add Telegram" icon="lucide:send" href="/guides/telegram-ai-bot">
Give your agent mobile access through Telegram.
</Card>
<Card title="Self-Hosting Guide" icon="lucide:server" href="/guides/self-host-ai-agent">
Run your bot 24/7 on a home server or VPS.
</Card>
</CardGroup>

55
docs/guides/index.mdx Normal file
View File

@@ -0,0 +1,55 @@
---
title: Guides & Tutorials
description: "Step-by-step guides for setting up PocketPaw: self-hosting, Telegram bots, Discord bots, local LLMs with Ollama, and more. Each guide gets you running in under 10 minutes."
section: Guides
ogType: article
keywords: ["pocketpaw tutorial", "ai agent guide", "self-hosted ai setup", "telegram bot tutorial", "discord bot guide", "ollama local ai"]
tags: ["guides", "tutorials", "getting-started"]
---
# Guides & Tutorials
Practical walkthroughs for common PocketPaw setups. Each guide covers a specific use case from scratch, with working configurations you can copy-paste.
## Getting Started Guides
<CardGroup>
<Card title="Self-Host an AI Agent" icon="lucide:server" href="/guides/self-host-ai-agent">
Run your own AI assistant on a laptop or home server. Full control, no cloud dependency, works offline with Ollama.
</Card>
<Card title="Build a Telegram AI Bot" icon="lucide:send" href="/guides/telegram-ai-bot">
Create a personal AI assistant on Telegram with file handling, voice messages, and persistent memory.
</Card>
<Card title="Add AI to Your Discord Server" icon="lucide:gamepad-2" href="/guides/discord-ai-bot">
Set up an AI bot for your Discord community with slash commands, DMs, and real-time streaming responses.
</Card>
<Card title="Run AI Locally with Ollama" icon="lucide:hard-drive" href="/guides/local-llm-agent">
Use open-source models like Llama, Qwen, or Mistral. No API keys, no usage fees, runs entirely on your hardware.
</Card>
<Card title="AI Agents vs Chatbots" icon="lucide:scale" href="/guides/ai-agent-vs-chatbot">
What makes an AI agent different from a chatbot? When should you use which? A practical comparison.
</Card>
</CardGroup>
## What Makes These Guides Different
Most AI tutorials show you how to call an API. These guides show you how to deploy a complete agent that can:
- **Act on your behalf**: browse the web, manage files, send emails
- **Remember conversations**: persistent memory across sessions and platforms
- **Work across channels**: same agent on Telegram, Discord, Slack, or your browser
- **Run on your terms**: self-hosted, private, no data leaves your machine
## Looking for Reference Docs?
<CardGroup>
<Card title="Installation" icon="lucide:download" href="/getting-started/installation">
Package installation, extras, and environment setup.
</Card>
<Card title="Configuration" icon="lucide:settings" href="/getting-started/configuration">
All configuration options and environment variables.
</Card>
<Card title="API Reference" icon="lucide:code" href="/api">
REST and WebSocket API documentation.
</Card>
</CardGroup>

151
docs/guides/local-llm-agent.mdx Normal file
View File

@@ -0,0 +1,151 @@
---
title: "Run an AI Agent with Ollama (No API Key Needed)"
description: "Set up a completely free, private AI agent using Ollama and open-source models. No API keys, no usage fees, no data leaving your machine. Works on Mac, Linux, and Windows."
section: Guides
ogType: article
keywords: ["ollama ai agent", "local llm agent", "free ai agent", "run ai without api key", "private ai assistant ollama", "self-hosted llm"]
tags: ["guide", "ollama", "local-ai", "privacy", "free"]
---
# Run an AI Agent with Ollama (No API Key Needed)
Cloud AI services charge per token, require API keys, and send your data to external servers. If you want a private AI agent that costs nothing to run, Ollama lets you run open-source models directly on your hardware.
This guide sets up PocketPaw with Ollama for a completely self-contained AI agent. No accounts, no API keys, no internet needed for inference.
## Hardware Requirements
Ollama runs models on your CPU or GPU. Here's what you need:
| Model Size | RAM Needed | Speed | Quality |
|-----------|-----------|-------|---------|
| 3B (e.g., phi-3) | 2-4 GB | Fast | Basic tasks, simple Q&A |
| 7B (e.g., qwen2.5:7b) | 4-8 GB | Good | General purpose, recommended starting point |
| 14B (e.g., qwen2.5:14b) | 8-16 GB | Moderate | Better reasoning, code generation |
| 32B+ (e.g., qwen2.5:32b) | 16-32 GB | Slower | Near cloud-quality for most tasks |
<Callout type="info">
GPU acceleration makes a huge difference. With a decent NVIDIA or Apple Silicon GPU, even 14B models respond in seconds. CPU-only works but expect longer wait times on larger models.
</Callout>
## Setup
<Steps>
<Step title="Install Ollama">
**macOS or Linux:**
```bash
curl -fsSL https://ollama.com/install.sh | sh
```
**Windows:**
Download from [ollama.com/download](https://ollama.com/download)
Verify it's running:
```bash
ollama --version
```
</Step>
<Step title="Pull a model">
Start with a 7B model for a good balance of speed and quality:
```bash
ollama pull qwen2.5:7b
```
Other good options:
```bash
ollama pull llama3.1:8b # Meta's Llama 3.1
ollama pull mistral:7b # Mistral AI's flagship
ollama pull gemma2:9b # Google's Gemma 2
ollama pull deepseek-r1:7b # DeepSeek reasoning model
```
</Step>
<Step title="Install PocketPaw">
```bash
pip install pocketpaw
```
</Step>
<Step title="Configure for Ollama">
```bash
export POCKETPAW_LLM_PROVIDER="ollama"
export POCKETPAW_OLLAMA_MODEL="qwen2.5:7b"
```
That's all the configuration you need. No API keys.
</Step>
<Step title="Start your agent">
```bash
pocketpaw
```
Open `http://localhost:8888` and start chatting. Everything runs on your machine.
</Step>
</Steps>
## Choosing the Right Model
Different models suit different tasks:
| Use Case | Recommended Model | Why |
|----------|------------------|-----|
| General assistant | `qwen2.5:7b` | Good all-rounder, fast, handles most tasks |
| Code generation | `deepseek-coder-v2:16b` | Purpose-built for code, understands many languages |
| Reasoning & math | `deepseek-r1:7b` | Chain-of-thought reasoning, step-by-step problem solving |
| Creative writing | `llama3.1:8b` | Strong at narrative, varied writing styles |
| Quick responses | `phi-3:3.8b` | Smallest useful model, very fast on modest hardware |
You can switch models anytime by changing the environment variable:
```bash
export POCKETPAW_OLLAMA_MODEL="deepseek-coder-v2:16b"
```
## Tool Support with Local Models
PocketPaw's tools (web search, file management, browser) work with Ollama models, but tool-calling quality depends on the model. Larger models handle tools more reliably.
For the best tool-calling experience with local models, use:
- `qwen2.5:14b` or larger
- `llama3.1:8b` (good tool-calling support)
- `mistral:7b` (decent tool support)
Smaller models (3B) may struggle with complex multi-tool tasks.
## Mixing Local and Cloud
You can use Ollama for most tasks and a cloud provider for complex ones:
```bash
# Default to Ollama
export POCKETPAW_LLM_PROVIDER="ollama"
export POCKETPAW_OLLAMA_MODEL="qwen2.5:7b"
# Optional: add cloud key for the model router to use on hard tasks
export POCKETPAW_ANTHROPIC_API_KEY="sk-ant-..."
```
PocketPaw's [model router](/advanced/model-router) can automatically escalate complex tasks to a cloud model while keeping simple queries local.
## Performance Tips
1. **Use GPU acceleration.** Ollama auto-detects NVIDIA CUDA and Apple Metal.
2. **Keep the model loaded.** First response is slow (loading), subsequent ones are fast.
3. **Match model to RAM.** If the model is larger than available RAM, it spills to disk and gets very slow.
4. **Close other heavy apps.** ML inference is memory-hungry.
## Next Steps
<CardGroup>
<Card title="Self-Hosting Guide" icon="lucide:server" href="/guides/self-host-ai-agent">
Full guide to running PocketPaw on your own hardware.
</Card>
<Card title="Ollama Backend Docs" icon="lucide:book-open" href="/backends/ollama">
Detailed Ollama configuration, model management, and troubleshooting.
</Card>
<Card title="Model Router" icon="lucide:route" href="/advanced/model-router">
Automatically route between local and cloud models based on task complexity.
</Card>
</CardGroup>

164
docs/guides/self-host-ai-agent.mdx Normal file
View File

@@ -0,0 +1,164 @@
---
title: "How to Self-Host an AI Agent on Your Laptop"
description: "Set up a self-hosted AI agent that runs on your laptop or home server. No cloud subscriptions, full privacy, works with Claude, GPT, or free local models via Ollama."
section: Guides
ogType: article
keywords: ["self-hosted ai agent", "run ai locally", "private ai assistant", "local ai agent setup", "ai agent on laptop"]
tags: ["guide", "self-hosting", "privacy", "local-ai"]
---
# How to Self-Host an AI Agent on Your Laptop
Most AI tools run in someone else's cloud. Your prompts, your files, your data, all passing through third-party servers. Self-hosting puts you back in control.
This guide covers setting up PocketPaw as a private AI agent on your own machine. By the end, you'll have a working assistant that can browse the web, manage files, search the internet, and talk to you through a clean web interface. All running locally.
## What You'll Need
- A computer running **macOS, Linux, or Windows** (even an older laptop works)
- **Python 3.11+** installed
- Either an **API key** (Anthropic, OpenAI, or Google) or **Ollama** for free local models
- About **10 minutes**
## Step-by-Step Setup
<Steps>
<Step title="Install PocketPaw">
The quickest path is the interactive installer:
```bash
curl -fsSL https://pocketpaw.xyz/install.sh | sh
```
Or install directly with pip:
```bash
pip install pocketpaw
```
For the full feature set (browser automation, memory, desktop tools):
```bash
pip install pocketpaw[recommended]
```
</Step>
<Step title="Choose your AI provider">
You have two paths: cloud models (smarter, costs money) or local models (free, private, needs decent hardware).
**Cloud option, Anthropic Claude (recommended):**
```bash
export POCKETPAW_ANTHROPIC_API_KEY="sk-ant-your-key-here"
```
**Free option, Ollama (runs on your machine):**
```bash
# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh
# Pull a model
ollama pull qwen2.5:7b
# Tell PocketPaw to use it
export POCKETPAW_LLM_PROVIDER="ollama"
export POCKETPAW_OLLAMA_MODEL="qwen2.5:7b"
```
<Callout type="tip">
Ollama models run entirely on your hardware. A 7B parameter model needs about 4GB of RAM. For better results, try a 14B or 32B model if your machine can handle it.
</Callout>
</Step>
<Step title="Start PocketPaw">
```bash
pocketpaw
```
That's it. The web dashboard opens at `http://localhost:8888`. You're now running your own AI agent.
</Step>
<Step title="Try it out">
Open the dashboard and try these prompts:
- "Search the web for the latest Python release notes"
- "Create a file called notes.txt with today's date"
- "What files are in my home directory?"
PocketPaw can execute code, browse websites, read/write files, and use 50+ built-in tools, all from your local machine.
</Step>
</Steps>
## What You Get
A self-hosted PocketPaw instance gives you:
| Feature | What it does |
|---------|-------------|
| **Web dashboard** | Chat interface at localhost:8888 with session history |
| **50+ tools** | Web search, file management, browser, image gen, voice, OCR |
| **Memory** | Conversations persist across sessions |
| **Multiple channels** | Add Telegram, Discord, Slack later without reinstalling |
| **Security** | Injection scanning, audit logs, Guardian AI safety checks |
## Adding Channels Later
Once your agent is running, you can connect messaging platforms:
```bash
# Add Telegram
pip install pocketpaw[telegram]
export POCKETPAW_TELEGRAM_BOT_TOKEN="your-bot-token"
# Add Discord
pip install pocketpaw[discord]
export POCKETPAW_DISCORD_BOT_TOKEN="your-bot-token"
```
Restart PocketPaw and all configured channels start automatically. Same agent, same memory, multiple platforms.
## Running on a Home Server
For always-on access, run PocketPaw as a system service:
```bash
# Using systemd (Linux)
sudo cp pocketpaw.service /etc/systemd/system/
sudo systemctl enable pocketpaw
sudo systemctl start pocketpaw
```
Or use Docker for a contained setup:
```bash
git clone https://github.com/pocketpaw/pocketpaw.git
cd pocketpaw
cp .env.example .env # Add your API keys
docker compose up -d
```
See the full [deployment guide](/deployment/self-hosting) for production configurations.
## Privacy and Security
Self-hosting means:
- **No data leaves your machine** (unless you use a cloud LLM provider)
- **No usage tracking**: PocketPaw collects zero telemetry
- **Full audit trail**: every tool execution is logged locally
- **You control updates**: upgrade when you want, not when a vendor decides
For maximum privacy, use Ollama with local models. Your conversations never touch the internet.
## Next Steps
<CardGroup>
<Card title="Add Telegram" icon="lucide:send" href="/guides/telegram-ai-bot">
Connect your self-hosted agent to Telegram for mobile access.
</Card>
<Card title="Run with Ollama" icon="lucide:hard-drive" href="/guides/local-llm-agent">
Set up free local models for completely offline operation.
</Card>
<Card title="Security Model" icon="lucide:shield" href="/security">
Learn about PocketPaw's 7-layer security architecture.
</Card>
</CardGroup>

152
docs/guides/telegram-ai-bot.mdx Normal file
View File

@@ -0,0 +1,152 @@
---
title: "Build a Telegram AI Bot in 5 Minutes"
description: "Create a personal AI assistant on Telegram using PocketPaw. Supports text, voice messages, files, persistent memory, and 50+ tools. Self-hosted and private."
section: Guides
ogType: article
keywords: ["telegram ai bot", "telegram ai assistant", "build telegram bot python", "self-hosted telegram bot", "ai chatbot telegram"]
tags: ["guide", "telegram", "bot", "messaging"]
---
# Build a Telegram AI Bot in 5 Minutes
Telegram bots are useful for quick access to an AI assistant from your phone. But most Telegram bot tutorials wire up a basic GPT wrapper with no memory, no tools, and no real capabilities.
This guide sets up a Telegram bot backed by PocketPaw, a full AI agent that can search the web, manage files, generate images, remember past conversations, and run 50+ tools. All self-hosted on your machine.
## What You'll Build
A Telegram bot that:
- Responds to text messages with AI-powered answers
- Handles voice messages (speech-to-text, then responds)
- Accepts file uploads and can read/analyze them
- Remembers conversations across sessions
- Can search the web, generate images, manage your calendar, and more
- Runs on your machine with your choice of AI model
## Prerequisites
- **PocketPaw installed** (follow the [installation guide](/getting-started/installation) if you haven't)
- **Telegram account** (you need one to create a bot)
- **An AI provider**: Anthropic API key or [Ollama for free local models](/guides/local-llm-agent)
## Creating Your Bot
<Steps>
<Step title="Get a bot token from BotFather">
1. Open Telegram and search for `@BotFather`
2. Send `/newbot`
3. Choose a name (e.g., "My AI Assistant")
4. Choose a username (e.g., `my_ai_paw_bot`)
5. BotFather will give you a token like `7123456789:AAF...`
Copy that token. You'll need it next.
<Callout type="tip">
Send `/setdescription` to BotFather to add a description that appears when users open your bot for the first time.
</Callout>
</Step>
<Step title="Install the Telegram extra">
```bash
pip install pocketpaw[telegram]
```
</Step>
<Step title="Configure the bot token">
```bash
export POCKETPAW_TELEGRAM_BOT_TOKEN="7123456789:AAF..."
export POCKETPAW_ANTHROPIC_API_KEY="sk-ant-..." # or use Ollama
```
To restrict who can use the bot (recommended):
```bash
# Your Telegram user ID (get it from @userinfobot)
export POCKETPAW_ALLOWED_TELEGRAM_IDS="123456789"
```
</Step>
<Step title="Start PocketPaw">
**Option A: With web dashboard (recommended)**
```bash
pocketpaw
```
This starts the dashboard at localhost:8888 AND your Telegram bot simultaneously. Manage both from the dashboard.
**Option B: Telegram-only (headless)**
```bash
pocketpaw --telegram
```
</Step>
<Step title="Test your bot">
Open Telegram, find your bot, and send a message. Try:
- "What's the weather like?" (triggers web search)
- Send a voice message (auto-transcribed and answered)
- Send a photo (analyzed with vision)
- "Remember that my favorite color is blue" (stored in memory)
- "What's my favorite color?" (recalled from memory)
</Step>
</Steps>
## Features That Work Out of the Box
| Feature | How it works |
|---------|-------------|
| **Text messages** | Processed through the full agent pipeline with tool access |
| **Voice messages** | Auto-transcribed via speech-to-text, then processed as text |
| **Photos & files** | Analyzed with vision models or read as documents |
| **Streaming** | Responses appear progressively via edit-in-place |
| **Topic support** | Each forum topic gets its own conversation thread |
| **Memory** | Conversations persist. Your bot remembers across sessions |
| **Inline keyboards** | Confirmation prompts for sensitive actions |
## Securing Your Bot
By default, anyone who finds your bot can message it. Lock it down:
```bash
# Only allow specific Telegram user IDs
export POCKETPAW_ALLOWED_TELEGRAM_IDS="123456789,987654321"
```
Get your user ID by messaging `@userinfobot` on Telegram.
PocketPaw also has built-in security features:
- **Injection scanning**: blocks prompt injection attempts
- **Guardian AI**: secondary LLM checks for dangerous requests
- **Audit logging**: every tool execution is logged
## Running Your Bot 24/7
Your bot only works when PocketPaw is running. For always-on access:
**Option 1: systemd (Linux servers)**
```bash
sudo systemctl enable pocketpaw
sudo systemctl start pocketpaw
```
**Option 2: Docker**
```bash
docker compose up -d
```
**Option 3: Keep your laptop open** (works for personal use)
See the [deployment guide](/deployment/self-hosting) for production setups.
## Next Steps
<CardGroup>
<Card title="Add Discord Too" icon="lucide:gamepad-2" href="/guides/discord-ai-bot">
Same agent, now on Discord. One PocketPaw instance handles both.
</Card>
<Card title="Telegram Channel Docs" icon="lucide:book-open" href="/channels/telegram">
Full reference for Telegram-specific features and configuration.
</Card>
<Card title="Tools Overview" icon="lucide:wrench" href="/tools">
Browse all 50+ tools available to your Telegram bot.
</Card>
</CardGroup>

3
docs/introduction/index.mdx
View File

@@ -85,4 +85,7 @@ Every message flows through the bus, regardless of which channel it comes from.
<Card title="Why PocketPaw?" icon="lucide:sparkles" href="/introduction/why-pocketpaw">
Learn what makes PocketPaw different from other AI assistants.
</Card>
<Card title="Guides & Tutorials" icon="lucide:compass" href="/guides">
Step-by-step walkthroughs for Telegram bots, Discord bots, Ollama, and more.
</Card>
</CardGroup>