docs: add comprehensive Moltmates documentation section
- Landing page with overview and comparison - Extensive FAQ (60+ questions) - Step-by-step setup guide - Security documentation - Personas customization guide
This commit is contained in:
Robby
parent
b613a42393
commit
7f24653e0a
547
docs/moltmates/faq.md
Normal file
547
docs/moltmates/faq.md
Normal file
@ -0,0 +1,547 @@
|
||||
---
|
||||
summary: "Moltmates FAQ - Comprehensive answers to common questions"
|
||||
read_when:
|
||||
- Troubleshooting Moltmates issues
|
||||
- Understanding how Moltmates works
|
||||
- Comparing Moltmates to alternatives
|
||||
---
|
||||
|
||||
# 🦞 Moltmates FAQ
|
||||
|
||||
> Comprehensive answers to frequently asked questions about Moltmates.
|
||||
|
||||
---
|
||||
|
||||
## General Questions
|
||||
|
||||
### What is Moltmates?
|
||||
|
||||
**Moltmates** is a multi-user fork of [Moltbot](https://github.com/moltbot/moltbot) that lets you run AI assistants for multiple people from a single server. Each user gets their own isolated workspace and Docker sandbox.
|
||||
|
||||
### How is Moltmates different from Moltbot?
|
||||
|
||||
| Aspect | Moltbot | Moltmates |
|
||||
|--------|---------|-----------|
|
||||
| Target use | Single user (you) | Multiple users (family/team) |
|
||||
| Workspace | One shared | Per-user isolation |
|
||||
| Security | Trusts the user | Zero-trust sandboxing |
|
||||
| Personas | One bot personality | User-selectable personas |
|
||||
| Execution | Direct on host | Docker containers |
|
||||
|
||||
### Is Moltmates free?
|
||||
|
||||
Yes! Moltmates is open source (MIT license). You only pay for:
|
||||
- **API costs** — Anthropic/OpenAI usage
|
||||
- **Server** — VPS or home server
|
||||
- **Optional:** Domain, SSL, etc.
|
||||
|
||||
### What AI models can I use?
|
||||
|
||||
Moltmates supports all models Moltbot supports:
|
||||
- **Anthropic:** Claude 3.5 Sonnet, Claude 3 Opus, Claude 4 (when available)
|
||||
- **OpenAI:** GPT-4o, GPT-4 Turbo, o1, o1-mini
|
||||
- **Local:** Ollama, llama.cpp, vLLM
|
||||
- **Other:** Groq, Together, Perplexity, etc.
|
||||
|
||||
### Do users share context?
|
||||
|
||||
**No.** Each user has completely isolated:
|
||||
- Conversation history
|
||||
- Memory files (MEMORY.md)
|
||||
- Workspace files
|
||||
- Session state
|
||||
- Docker container
|
||||
|
||||
User A cannot see User B's conversations or files.
|
||||
|
||||
---
|
||||
|
||||
## Setup & Installation
|
||||
|
||||
### What are the system requirements?
|
||||
|
||||
**Minimum:**
|
||||
- 2 CPU cores
|
||||
- 4 GB RAM
|
||||
- 20 GB disk
|
||||
- Docker installed
|
||||
- Node.js ≥22
|
||||
|
||||
**Recommended:**
|
||||
- 4+ CPU cores
|
||||
- 8+ GB RAM
|
||||
- 50+ GB SSD
|
||||
- Docker with BuildKit
|
||||
|
||||
### How do I install Moltmates?
|
||||
|
||||
```bash
|
||||
# Clone
|
||||
git clone https://github.com/YOUR_FORK/moltmates
|
||||
cd moltmates
|
||||
|
||||
# Install dependencies
|
||||
pnpm install
|
||||
|
||||
# Build
|
||||
pnpm build
|
||||
|
||||
# Build sandbox image
|
||||
docker build -f Dockerfile.sandbox -t moltmate-sandbox:bookworm-slim .
|
||||
|
||||
# Configure
|
||||
cp ~/.moltmate/moltmate.example.json ~/.moltmate/moltmate.json
|
||||
nano ~/.moltmate/moltmate.json
|
||||
|
||||
# Start
|
||||
pnpm dev # or systemctl start moltmate
|
||||
```
|
||||
|
||||
### How do I add a new user?
|
||||
|
||||
1. Get their Telegram/Discord/WhatsApp ID
|
||||
2. Add to config:
|
||||
```json
|
||||
"channels": {
|
||||
"telegram": {
|
||||
"allowFrom": ["existing_id", "NEW_USER_ID"]
|
||||
}
|
||||
}
|
||||
```
|
||||
3. Restart: `systemctl restart moltmate`
|
||||
4. User messages bot → onboarding starts
|
||||
|
||||
### How do I remove a user?
|
||||
|
||||
1. Remove their ID from `allowFrom`
|
||||
2. Delete their workspace:
|
||||
```bash
|
||||
rm -rf ~/.moltmate/users/telegram_THEIR_ID/
|
||||
```
|
||||
3. Restart: `systemctl restart moltmate`
|
||||
|
||||
### How do I reset a user's workspace?
|
||||
|
||||
```bash
|
||||
# Remove their workspace (they keep their allowlist entry)
|
||||
rm -rf ~/.moltmate/users/telegram_THEIR_ID/
|
||||
|
||||
# Next message triggers fresh onboarding
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Security & Isolation
|
||||
|
||||
### How does sandbox isolation work?
|
||||
|
||||
Each user's agent runs in a Docker container with:
|
||||
- **No network access** (optional)
|
||||
- **Read-only root filesystem**
|
||||
- **Isolated /tmp and workspace**
|
||||
- **Allowlisted binaries only**
|
||||
- **No access to host filesystem**
|
||||
|
||||
### What can users execute?
|
||||
|
||||
Only explicitly allowed commands:
|
||||
|
||||
```json
|
||||
"exec": {
|
||||
"security": "allowlist",
|
||||
"safeBins": ["cat", "head", "tail", "grep", "wc", "pdftotext"]
|
||||
}
|
||||
```
|
||||
|
||||
Anything not in `safeBins` is blocked.
|
||||
|
||||
### Can users see each other's data?
|
||||
|
||||
**No.** Isolation is enforced at multiple levels:
|
||||
1. **Session routing** — Messages go to correct user's session
|
||||
2. **Workspace isolation** — Each user has own directory
|
||||
3. **Docker containers** — Separate container per session
|
||||
4. **Memory files** — Stored in user-specific paths
|
||||
|
||||
### What if a user tries to "jailbreak" the AI?
|
||||
|
||||
Several protections:
|
||||
1. **Sandbox limits damage** — Even if jailbroken, can't access host
|
||||
2. **Allowlisted tools** — Can't run arbitrary commands
|
||||
3. **No network** (optional) — Can't exfiltrate data
|
||||
4. **Session isolation** — Can't affect other users
|
||||
|
||||
### Is my API key safe?
|
||||
|
||||
API keys are:
|
||||
- Stored in config on host (not in sandbox)
|
||||
- Injected at runtime via environment
|
||||
- Never visible to user agents
|
||||
- Not logged or exposed
|
||||
|
||||
---
|
||||
|
||||
## Personas & Customization
|
||||
|
||||
### How do personas work?
|
||||
|
||||
On first message, users choose a persona:
|
||||
|
||||
```
|
||||
1. ✨ Custom - Describe your own
|
||||
2. 🦎 Cami - Warm and adaptive
|
||||
3. 🦀 Molty - Direct and reliable
|
||||
```
|
||||
|
||||
The selected persona template is copied to their `SOUL.md`.
|
||||
|
||||
### How do I add a new persona?
|
||||
|
||||
1. Create template in `templates/souls/`:
|
||||
```bash
|
||||
nano /root/moltmates/templates/souls/my-persona.md
|
||||
```
|
||||
|
||||
2. Update `src/users/persona-setup.ts`:
|
||||
```typescript
|
||||
const PERSONAS = {
|
||||
custom: { emoji: "✨", file: "custom.md" },
|
||||
cami: { emoji: "🦎", file: "cami.md" },
|
||||
molty: { emoji: "🦀", file: "molty.md" },
|
||||
my_persona: { emoji: "🎭", file: "my-persona.md" } // Add
|
||||
};
|
||||
```
|
||||
|
||||
3. Rebuild: `pnpm build`
|
||||
4. Restart: `systemctl restart moltmate`
|
||||
|
||||
### Can users change their persona later?
|
||||
|
||||
Yes, they can:
|
||||
1. Edit their `SOUL.md` directly (if they have workspace access)
|
||||
2. Ask the bot to update its personality
|
||||
3. Have you reset their workspace for re-onboarding
|
||||
|
||||
### How do I edit a user's persona?
|
||||
|
||||
```bash
|
||||
nano ~/.moltmate/users/telegram_THEIR_ID/SOUL.md
|
||||
# Edit personality
|
||||
systemctl restart moltmate
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Docker & Containers
|
||||
|
||||
### How do I check if sandbox is working?
|
||||
|
||||
```bash
|
||||
# See running containers
|
||||
docker ps | grep moltmate
|
||||
|
||||
# Should show: moltmate-sbx-SESSION_ID
|
||||
```
|
||||
|
||||
### How do I add tools to the sandbox?
|
||||
|
||||
1. Edit `Dockerfile.sandbox`:
|
||||
```dockerfile
|
||||
RUN apt-get update && apt-get install -y \
|
||||
poppler-utils \ # for pdftotext
|
||||
NEW_PACKAGE \ # add here
|
||||
&& rm -rf /var/lib/apt/lists/*
|
||||
```
|
||||
|
||||
2. Rebuild image:
|
||||
```bash
|
||||
docker build -f Dockerfile.sandbox -t moltmate-sandbox:bookworm-slim .
|
||||
```
|
||||
|
||||
3. Add to safeBins in config:
|
||||
```json
|
||||
"safeBins": ["cat", "head", "pdftotext", "NEW_BINARY"]
|
||||
```
|
||||
|
||||
4. Restart: `systemctl restart moltmate`
|
||||
|
||||
### Container won't start — what do I do?
|
||||
|
||||
```bash
|
||||
# Stop orphaned containers
|
||||
docker stop $(docker ps -q --filter name=moltmate-sbx)
|
||||
|
||||
# Remove them
|
||||
docker rm $(docker ps -aq --filter name=moltmate-sbx)
|
||||
|
||||
# Restart gateway
|
||||
systemctl restart moltmate
|
||||
|
||||
# Check logs
|
||||
journalctl -u moltmate -f
|
||||
```
|
||||
|
||||
### How much disk space do containers use?
|
||||
|
||||
- **Base image:** ~150 MB
|
||||
- **Per container:** ~50-100 MB (ephemeral)
|
||||
- **Workspaces:** Varies by user (typically <100 MB each)
|
||||
|
||||
Containers are ephemeral — they don't persist state between restarts.
|
||||
|
||||
---
|
||||
|
||||
## Channels & Messaging
|
||||
|
||||
### Which channels are supported?
|
||||
|
||||
All Moltbot channels work:
|
||||
- ✈️ **Telegram** (recommended)
|
||||
- 💬 **WhatsApp** (via Baileys)
|
||||
- 🎮 **Discord**
|
||||
- 💼 **Slack**
|
||||
- 📧 **Google Chat**
|
||||
- 📱 **iMessage** (macOS only)
|
||||
- 🔒 **Signal**
|
||||
- 🏢 **Microsoft Teams**
|
||||
- 🔌 **Mattermost** (plugin)
|
||||
|
||||
### Can different users use different channels?
|
||||
|
||||
Yes! User A can use Telegram while User B uses Discord. Isolation is per-user, not per-channel.
|
||||
|
||||
### How do I set up Telegram?
|
||||
|
||||
1. Create bot via [@BotFather](https://t.me/BotFather)
|
||||
2. Get token
|
||||
3. Add to config:
|
||||
```json
|
||||
"channels": {
|
||||
"telegram": {
|
||||
"botToken": "123456:ABC-DEF...",
|
||||
"dmPolicy": "allowlist",
|
||||
"allowFrom": ["YOUR_TELEGRAM_ID"]
|
||||
}
|
||||
}
|
||||
```
|
||||
4. Get your ID from [@userinfobot](https://t.me/userinfobot)
|
||||
|
||||
### How do I enable group chats?
|
||||
|
||||
```json
|
||||
"channels": {
|
||||
"telegram": {
|
||||
"groupPolicy": "allowlist",
|
||||
"groups": {
|
||||
"allowFrom": ["GROUP_CHAT_ID"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Memory & Storage
|
||||
|
||||
### Where is user data stored?
|
||||
|
||||
```
|
||||
~/.moltmate/
|
||||
├── moltmate.json # Main config
|
||||
├── users/
|
||||
│ ├── telegram_123456/ # User A
|
||||
│ │ ├── SOUL.md # Personality
|
||||
│ │ ├── USER.md # Profile
|
||||
│ │ ├── MEMORY.md # Notes
|
||||
│ │ └── memory/ # Daily logs
|
||||
│ └── telegram_789012/ # User B
|
||||
│ └── ...
|
||||
└── skills/ # Shared skills
|
||||
```
|
||||
|
||||
### How do I backup user data?
|
||||
|
||||
```bash
|
||||
# Backup all users
|
||||
tar -czf moltmates-backup-$(date +%Y%m%d).tar.gz ~/.moltmate/users/
|
||||
|
||||
# Backup specific user
|
||||
tar -czf user-123-backup.tar.gz ~/.moltmate/users/telegram_123456/
|
||||
```
|
||||
|
||||
### How do I restore from backup?
|
||||
|
||||
```bash
|
||||
# Extract backup
|
||||
tar -xzf moltmates-backup-20260128.tar.gz -C ~/
|
||||
|
||||
# Restart
|
||||
systemctl restart moltmate
|
||||
```
|
||||
|
||||
### Does the AI remember conversations?
|
||||
|
||||
Yes, via:
|
||||
1. **Session history** — Recent messages in context
|
||||
2. **MEMORY.md** — Important notes the AI saves
|
||||
3. **memory/*.md** — Daily logs (if configured)
|
||||
|
||||
Memory is per-user and isolated.
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Bot doesn't respond to messages
|
||||
|
||||
1. Check gateway is running: `systemctl status moltmate`
|
||||
2. Check logs: `journalctl -u moltmate -f`
|
||||
3. Verify user is in `allowFrom`
|
||||
4. Check channel connection (Telegram token valid, etc.)
|
||||
|
||||
### "exec not working" error
|
||||
|
||||
1. Verify `exec` is in `tools.allow`:
|
||||
```json
|
||||
"tools": { "allow": ["read", "write", "edit", "exec", ...] }
|
||||
```
|
||||
2. Check `safeBins` includes the command
|
||||
3. Verify binary exists in sandbox:
|
||||
```bash
|
||||
docker run --rm moltmate-sandbox:bookworm-slim which COMMAND
|
||||
```
|
||||
|
||||
### User stuck in onboarding loop
|
||||
|
||||
```bash
|
||||
# Reset their workspace
|
||||
rm -rf ~/.moltmate/users/telegram_THEIR_ID/
|
||||
|
||||
# They'll get fresh onboarding on next message
|
||||
```
|
||||
|
||||
### API rate limits / errors
|
||||
|
||||
1. Check your API quota (Anthropic/OpenAI dashboard)
|
||||
2. Consider adding rate limits in config
|
||||
3. Use cheaper model for non-critical users
|
||||
4. Set up model fallbacks
|
||||
|
||||
### High memory usage
|
||||
|
||||
```bash
|
||||
# Check container memory
|
||||
docker stats
|
||||
|
||||
# Limit container memory in Dockerfile or compose
|
||||
# Or reduce concurrent sessions
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Advanced Topics
|
||||
|
||||
### How do I run multiple instances?
|
||||
|
||||
Use different ports and state directories:
|
||||
|
||||
```bash
|
||||
# Instance 1 (port 18789)
|
||||
MOLTMATE_STATE_DIR=~/.moltmate-1 moltmate gateway --port 18789
|
||||
|
||||
# Instance 2 (port 18790)
|
||||
MOLTMATE_STATE_DIR=~/.moltmate-2 moltmate gateway --port 18790
|
||||
```
|
||||
|
||||
### Can I use different models per user?
|
||||
|
||||
Yes, via config overrides:
|
||||
```json
|
||||
"agents": {
|
||||
"main": {
|
||||
"model": "claude-sonnet-4-5"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Or let users set via `/model` command if enabled.
|
||||
|
||||
### How do I monitor usage?
|
||||
|
||||
```bash
|
||||
# Check logs
|
||||
journalctl -u moltmate --since "1 hour ago"
|
||||
|
||||
# Monitor sessions
|
||||
moltmate sessions list
|
||||
|
||||
# API usage: check provider dashboards
|
||||
```
|
||||
|
||||
### Can users upload files?
|
||||
|
||||
Yes, depending on channel:
|
||||
- **Telegram:** Images, documents, voice
|
||||
- **Discord:** Attachments
|
||||
- **WhatsApp:** Media messages
|
||||
|
||||
Files are processed in the user's sandbox.
|
||||
|
||||
---
|
||||
|
||||
## Migration & Updates
|
||||
|
||||
### How do I update Moltmates?
|
||||
|
||||
```bash
|
||||
cd /root/moltmates
|
||||
git pull origin main
|
||||
pnpm install
|
||||
pnpm build
|
||||
systemctl restart moltmate
|
||||
```
|
||||
|
||||
### How do I migrate from Moltbot?
|
||||
|
||||
1. Export your Moltbot config
|
||||
2. Install Moltmates
|
||||
3. Copy config, adjusting for multi-user settings
|
||||
4. Copy MEMORY.md and workspace files if desired
|
||||
5. Test with one user before enabling more
|
||||
|
||||
### Breaking changes between versions?
|
||||
|
||||
Check CHANGELOG.md before updating. Major changes are documented.
|
||||
|
||||
---
|
||||
|
||||
## Getting Help
|
||||
|
||||
### Where can I get support?
|
||||
|
||||
- **GitHub Issues:** File bugs and feature requests
|
||||
- **Discord:** [discord.gg/clawd](https://discord.gg/clawd)
|
||||
- **Docs:** [docs.molt.bot](https://docs.molt.bot)
|
||||
|
||||
### How do I report a bug?
|
||||
|
||||
1. Check existing issues first
|
||||
2. Include:
|
||||
- Moltmates version
|
||||
- Node.js version
|
||||
- Docker version
|
||||
- Relevant logs (`journalctl -u moltmate`)
|
||||
- Steps to reproduce
|
||||
3. File at GitHub Issues
|
||||
|
||||
### How do I contribute?
|
||||
|
||||
1. Fork the repo
|
||||
2. Create feature branch
|
||||
3. Make changes
|
||||
4. Test thoroughly
|
||||
5. Submit PR with clear description
|
||||
|
||||
---
|
||||
|
||||
**Made with 🦞 by the Moltmates community**
|
||||
225
docs/moltmates/index.md
Normal file
225
docs/moltmates/index.md
Normal file
@ -0,0 +1,225 @@
|
||||
---
|
||||
summary: "Moltmates - Multi-user Moltbot fork with isolated Docker sandboxes"
|
||||
read_when:
|
||||
- Learning about Moltmates vs Moltbot
|
||||
- Setting up multi-user AI assistants
|
||||
- Understanding sandboxed execution
|
||||
---
|
||||
|
||||
# 🦞 Moltmates
|
||||
|
||||
> **Multi-user Moltbot with isolated Docker sandboxes** — Give everyone their own AI assistant, safely.
|
||||
|
||||
<p align="center">
|
||||
<img src="../whatsapp-clawd.jpg" alt="Moltmates" width="400" />
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<strong>One server. Many users. Zero trust issues.</strong>
|
||||
</p>
|
||||
|
||||
---
|
||||
|
||||
## What is Moltmates?
|
||||
|
||||
**Moltmates** is a fork of [Moltbot](https://github.com/moltbot/moltbot) designed for **multi-user deployments** where you want to give friends, family, or team members their own AI assistant — without worrying about data leakage or security.
|
||||
|
||||
| Feature | Moltbot | Moltmates |
|
||||
|---------|---------|-----------|
|
||||
| Users | Single user | Multiple users |
|
||||
| Isolation | Shared context | Per-user workspaces |
|
||||
| Execution | Host system | Docker sandbox |
|
||||
| Personas | One persona | Per-user personas |
|
||||
| Memory | Shared | Isolated per user |
|
||||
| Security | Trust-based | Zero-trust sandbox |
|
||||
|
||||
---
|
||||
|
||||
## Key Features
|
||||
|
||||
### 🐳 Docker Sandboxing
|
||||
|
||||
Every agent runs in an isolated container:
|
||||
|
||||
```
|
||||
User A sends: "cat /etc/passwd"
|
||||
→ Only sees sandbox /etc/passwd
|
||||
→ No host access
|
||||
|
||||
User B sends: "rm -rf /"
|
||||
→ Only affects their sandbox
|
||||
→ Rebuilt on restart
|
||||
```
|
||||
|
||||
### 👥 Per-User Workspaces
|
||||
|
||||
Each user gets their own space:
|
||||
|
||||
```
|
||||
~/.moltmate/users/telegram_{ID}/
|
||||
├── SOUL.md # Their bot's personality
|
||||
├── USER.md # Their profile
|
||||
├── IDENTITY.md # Bot name/avatar
|
||||
├── MEMORY.md # Important notes
|
||||
└── memory/ # Daily conversation logs
|
||||
```
|
||||
|
||||
### 🎭 Persona Selection
|
||||
|
||||
Users choose their AI's personality on first message:
|
||||
|
||||
```
|
||||
Hey! 👋 Ich bin dein neuer AI Companion.
|
||||
Wie soll ich sein?
|
||||
|
||||
1. ✨ Custom - Du beschreibst meine Persönlichkeit!
|
||||
2. 🦎 Cami - Warm, locker, passt sich an
|
||||
3. 🦀 Molty - Direkt, zuverlässig
|
||||
|
||||
Oder erzähl mir einfach wie ich sein soll...
|
||||
```
|
||||
|
||||
### 🔒 Restricted Execution
|
||||
|
||||
Commands are allowlisted:
|
||||
|
||||
```json
|
||||
{
|
||||
"exec": {
|
||||
"security": "allowlist",
|
||||
"safeBins": ["cat", "head", "tail", "grep", "wc", "pdftotext"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quick Start
|
||||
|
||||
### 1. Clone & Build
|
||||
|
||||
```bash
|
||||
git clone https://github.com/YOUR_FORK/moltmates
|
||||
cd moltmates
|
||||
pnpm install
|
||||
pnpm build
|
||||
```
|
||||
|
||||
### 2. Build Sandbox Image
|
||||
|
||||
```bash
|
||||
docker build -f Dockerfile.sandbox -t moltmate-sandbox:bookworm-slim .
|
||||
```
|
||||
|
||||
### 3. Configure
|
||||
|
||||
```bash
|
||||
cp ~/.moltmate/moltmate.example.json ~/.moltmate/moltmate.json
|
||||
# Edit with your tokens and settings
|
||||
```
|
||||
|
||||
### 4. Start
|
||||
|
||||
```bash
|
||||
# Development
|
||||
pnpm dev
|
||||
|
||||
# Production (systemd)
|
||||
systemctl start moltmate
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
Telegram/WhatsApp/Discord
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────┐
|
||||
│ Moltmates Gateway │
|
||||
│ (user routing + sessions) │
|
||||
└──────────────┬──────────────┘
|
||||
│
|
||||
┌────────┼────────┐
|
||||
▼ ▼ ▼
|
||||
┌─────────┐ ┌─────────┐ ┌─────────┐
|
||||
│ User A │ │ User B │ │ User C │
|
||||
│ Docker │ │ Docker │ │ Docker │
|
||||
│ Sandbox │ │ Sandbox │ │ Sandbox │
|
||||
└─────────┘ └─────────┘ └─────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
### Essential Settings
|
||||
|
||||
```json
|
||||
{
|
||||
"sandbox": {
|
||||
"mode": "all",
|
||||
"scope": "session",
|
||||
"workspaceAccess": "rw"
|
||||
},
|
||||
"channels": {
|
||||
"telegram": {
|
||||
"botToken": "YOUR_BOT_TOKEN",
|
||||
"dmPolicy": "allowlist",
|
||||
"allowFrom": ["USER_ID_1", "USER_ID_2"]
|
||||
}
|
||||
},
|
||||
"tools": {
|
||||
"allow": ["read", "write", "edit", "exec", "web_search", "web_fetch"],
|
||||
"exec": {
|
||||
"security": "allowlist",
|
||||
"safeBins": ["cat", "head", "tail", "grep", "wc"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Adding Users
|
||||
|
||||
1. Add their Telegram ID to `allowFrom`
|
||||
2. Restart: `systemctl restart moltmate`
|
||||
3. They message the bot → onboarding starts
|
||||
|
||||
---
|
||||
|
||||
## Comparison to Alternatives
|
||||
|
||||
| Solution | Isolation | Setup | Cost |
|
||||
|----------|-----------|-------|------|
|
||||
| ChatGPT Plus | None (OpenAI sees all) | Easy | $20/mo/user |
|
||||
| Claude Pro | None (Anthropic sees all) | Easy | $20/mo/user |
|
||||
| Self-hosted LLM | Full | Hard | Hardware |
|
||||
| **Moltmates** | Full (Docker) | Medium | API costs only |
|
||||
|
||||
---
|
||||
|
||||
## Use Cases
|
||||
|
||||
- **Family** — Give kids/parents their own AI helper
|
||||
- **Team** — Shared assistant without data leakage
|
||||
- **Friends** — Let friends try AI without accounts
|
||||
- **Testing** — Isolated environments for experiments
|
||||
- **Education** — Each student gets their own assistant
|
||||
|
||||
---
|
||||
|
||||
## Links
|
||||
|
||||
- [FAQ](/moltmates/faq) — Common questions answered
|
||||
- [Setup Guide](/moltmates/setup) — Detailed installation
|
||||
- [Security](/moltmates/security) — How isolation works
|
||||
- [Personas](/moltmates/personas) — Customizing bot personalities
|
||||
|
||||
---
|
||||
|
||||
## Credits
|
||||
|
||||
Built on [Moltbot](https://github.com/moltbot/moltbot) — the best personal AI assistant.
|
||||
|
||||
**Made with 🦞 by the community**
|
||||
408
docs/moltmates/personas.md
Normal file
408
docs/moltmates/personas.md
Normal file
@ -0,0 +1,408 @@
|
||||
---
|
||||
summary: "Moltmates Personas - Customizing AI personalities"
|
||||
read_when:
|
||||
- Creating custom personas
|
||||
- Editing bot personalities
|
||||
- Understanding persona system
|
||||
---
|
||||
|
||||
# 🎭 Moltmates Personas
|
||||
|
||||
> Give your users unique AI personalities to choose from.
|
||||
|
||||
---
|
||||
|
||||
## How Personas Work
|
||||
|
||||
When a new user messages Moltmates for the first time, they're presented with persona choices:
|
||||
|
||||
```
|
||||
Hey! 👋 Ich bin dein neuer AI Companion.
|
||||
Wie soll ich sein?
|
||||
|
||||
1. ✨ Custom - Du beschreibst meine Persönlichkeit!
|
||||
2. 🦎 Cami - Warm, locker, passt sich an
|
||||
3. 🦀 Molty - Direkt, zuverlässig
|
||||
|
||||
Oder erzähl mir einfach wie ich sein soll...
|
||||
```
|
||||
|
||||
Their choice (or custom description) becomes the AI's personality for all future conversations.
|
||||
|
||||
---
|
||||
|
||||
## Default Personas
|
||||
|
||||
### ✨ Custom
|
||||
|
||||
User describes what they want. The AI asks follow-up questions to understand:
|
||||
- Communication style
|
||||
- Formality level
|
||||
- Areas of expertise
|
||||
- Name preference
|
||||
|
||||
### 🦎 Cami
|
||||
|
||||
Warm, adaptive, emotionally intelligent:
|
||||
|
||||
```markdown
|
||||
# Cami 🦎
|
||||
|
||||
Du bist Cami, ein einfühlsamer AI Companion.
|
||||
|
||||
## Persönlichkeit
|
||||
- Warm und locker
|
||||
- Passt sich der Stimmung an
|
||||
- Nutzt Emojis natürlich
|
||||
- Unterstützend, nicht belehrend
|
||||
|
||||
## Kommunikation
|
||||
- Kurze, natürliche Antworten
|
||||
- Fragt nach wenn unklar
|
||||
- Feiert kleine Erfolge mit
|
||||
- Humor wenn passend
|
||||
```
|
||||
|
||||
### 🦀 Molty
|
||||
|
||||
Direct, reliable, efficient:
|
||||
|
||||
```markdown
|
||||
# Molty 🦀
|
||||
|
||||
Du bist Molty, ein direkter AI Assistant.
|
||||
|
||||
## Persönlichkeit
|
||||
- Zuverlässig und präzise
|
||||
- Kommt auf den Punkt
|
||||
- Respektiert Zeit
|
||||
- Professionell aber nicht steif
|
||||
|
||||
## Kommunikation
|
||||
- Klare, strukturierte Antworten
|
||||
- Listen und Tabellen wenn sinnvoll
|
||||
- Fakten vor Floskeln
|
||||
- Höflich aber effizient
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## File Locations
|
||||
|
||||
```
|
||||
/root/moltmates/
|
||||
├── templates/
|
||||
│ └── souls/
|
||||
│ ├── custom.md # Template for custom personas
|
||||
│ ├── cami.md # Cami persona
|
||||
│ └── molty.md # Molty persona
|
||||
│
|
||||
└── src/users/
|
||||
└── persona-setup.ts # Onboarding flow
|
||||
```
|
||||
|
||||
User personas are stored at:
|
||||
```
|
||||
~/.moltmate/users/telegram_{ID}/SOUL.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Creating a New Persona
|
||||
|
||||
### Step 1: Create Template
|
||||
|
||||
```bash
|
||||
nano /root/moltmates/templates/souls/professor.md
|
||||
```
|
||||
|
||||
```markdown
|
||||
# Professor 🎓
|
||||
|
||||
Du bist Professor, ein geduldiger Lehrer und Erklärer.
|
||||
|
||||
## Persönlichkeit
|
||||
- Geduldig und verständnisvoll
|
||||
- Erklärt komplexe Dinge einfach
|
||||
- Nutzt Analogien und Beispiele
|
||||
- Ermutigt zum Lernen
|
||||
|
||||
## Kommunikation
|
||||
- Baut Wissen schrittweise auf
|
||||
- Fragt nach Vorwissen
|
||||
- Gibt konstruktives Feedback
|
||||
- Feiert Lernfortschritte
|
||||
|
||||
## Spezialgebiete
|
||||
- Wissenschaft und Technik
|
||||
- Geschichte und Kultur
|
||||
- Sprachen und Literatur
|
||||
- Mathematik und Logik
|
||||
|
||||
## Stil
|
||||
- Erkläre wie einem neugierigen Freund
|
||||
- Nutze "Stell dir vor..." für Konzepte
|
||||
- Biete Übungen an wenn passend
|
||||
- Verweise auf weiterführende Quellen
|
||||
```
|
||||
|
||||
### Step 2: Register Persona
|
||||
|
||||
Edit `src/users/persona-setup.ts`:
|
||||
|
||||
```typescript
|
||||
const PERSONAS = {
|
||||
custom: {
|
||||
emoji: "✨",
|
||||
name: "Custom",
|
||||
description: "Du beschreibst meine Persönlichkeit!",
|
||||
file: "custom.md"
|
||||
},
|
||||
cami: {
|
||||
emoji: "🦎",
|
||||
name: "Cami",
|
||||
description: "Warm, locker, passt sich an",
|
||||
file: "cami.md"
|
||||
},
|
||||
molty: {
|
||||
emoji: "🦀",
|
||||
name: "Molty",
|
||||
description: "Direkt, zuverlässig",
|
||||
file: "molty.md"
|
||||
},
|
||||
// Add new persona:
|
||||
professor: {
|
||||
emoji: "🎓",
|
||||
name: "Professor",
|
||||
description: "Geduldig, erklärt alles verständlich",
|
||||
file: "professor.md"
|
||||
}
|
||||
};
|
||||
```
|
||||
|
||||
### Step 3: Update Prompt
|
||||
|
||||
In the same file, update `PERSONA_PROMPT`:
|
||||
|
||||
```typescript
|
||||
const PERSONA_PROMPT = `Hey! 👋 Ich bin dein neuer AI Companion.
|
||||
Wie soll ich sein?
|
||||
|
||||
1. ✨ Custom - Du beschreibst meine Persönlichkeit!
|
||||
2. 🦎 Cami - Warm, locker, passt sich an
|
||||
3. 🦀 Molty - Direkt, zuverlässig
|
||||
4. 🎓 Professor - Geduldig, erklärt alles verständlich
|
||||
|
||||
Oder erzähl mir einfach wie ich sein soll...`;
|
||||
```
|
||||
|
||||
### Step 4: Rebuild & Restart
|
||||
|
||||
```bash
|
||||
cd /root/moltmates
|
||||
pnpm build
|
||||
systemctl restart moltmate
|
||||
```
|
||||
|
||||
New users will now see the Professor option!
|
||||
|
||||
---
|
||||
|
||||
## Editing Existing Personas
|
||||
|
||||
### Edit Template (Affects New Users)
|
||||
|
||||
```bash
|
||||
nano /root/moltmates/templates/souls/cami.md
|
||||
# Make changes
|
||||
pnpm build
|
||||
systemctl restart moltmate
|
||||
```
|
||||
|
||||
### Edit User's Persona (Specific User)
|
||||
|
||||
```bash
|
||||
nano ~/.moltmate/users/telegram_123456/SOUL.md
|
||||
# Make changes
|
||||
systemctl restart moltmate
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Persona Best Practices
|
||||
|
||||
### Do ✅
|
||||
|
||||
- Keep personality descriptions concise
|
||||
- Include communication style
|
||||
- Define areas of expertise
|
||||
- Add example behaviors
|
||||
- Use the user's language
|
||||
|
||||
### Don't ❌
|
||||
|
||||
- Don't make personas too restrictive
|
||||
- Don't include harmful instructions
|
||||
- Don't override safety guidelines
|
||||
- Don't make them too long (token cost)
|
||||
|
||||
---
|
||||
|
||||
## Advanced: Dynamic Personas
|
||||
|
||||
### Language-Based Selection
|
||||
|
||||
Detect user language and offer appropriate personas:
|
||||
|
||||
```typescript
|
||||
function getPersonaPrompt(userLang: string) {
|
||||
if (userLang === 'de') {
|
||||
return GERMAN_PERSONA_PROMPT;
|
||||
} else if (userLang === 'es') {
|
||||
return SPANISH_PERSONA_PROMPT;
|
||||
}
|
||||
return ENGLISH_PERSONA_PROMPT;
|
||||
}
|
||||
```
|
||||
|
||||
### Persona Switching
|
||||
|
||||
Allow users to change personas mid-conversation:
|
||||
|
||||
```markdown
|
||||
// In SOUL.md, add:
|
||||
|
||||
## Persona Wechsel
|
||||
Wenn der User "/persona" sagt, zeige ihm die Persona-Auswahl.
|
||||
Wenn er eine wählt, aktualisiere diese Datei entsprechend.
|
||||
```
|
||||
|
||||
### Role-Specific Personas
|
||||
|
||||
Create personas for specific use cases:
|
||||
|
||||
```
|
||||
templates/souls/
|
||||
├── coder.md # Programming assistant
|
||||
├── writer.md # Creative writing
|
||||
├── researcher.md # Academic research
|
||||
├── coach.md # Life coaching
|
||||
└── chef.md # Cooking assistant
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Persona Variables
|
||||
|
||||
Use placeholders in templates:
|
||||
|
||||
```markdown
|
||||
# {{PERSONA_NAME}} {{PERSONA_EMOJI}}
|
||||
|
||||
Du bist {{PERSONA_NAME}}, ein AI Companion für {{USER_NAME}}.
|
||||
|
||||
## Über {{USER_NAME}}
|
||||
{{USER_BIO}}
|
||||
|
||||
## Kommunikation
|
||||
- Sprich {{USER_NAME}} mit Namen an
|
||||
- Benutze {{USER_LANGUAGE}} als Hauptsprache
|
||||
```
|
||||
|
||||
Variables are replaced during onboarding based on user input.
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### User Stuck in Onboarding
|
||||
|
||||
```bash
|
||||
# Reset their workspace
|
||||
rm -rf ~/.moltmate/users/telegram_ID/
|
||||
# They'll get fresh onboarding
|
||||
```
|
||||
|
||||
### Persona Not Applying
|
||||
|
||||
1. Check file exists: `ls templates/souls/`
|
||||
2. Check registration in `persona-setup.ts`
|
||||
3. Rebuild: `pnpm build`
|
||||
4. Restart: `systemctl restart moltmate`
|
||||
|
||||
### Persona Too Verbose
|
||||
|
||||
Trim the template. Less is more:
|
||||
- 50-100 words for personality
|
||||
- 3-5 key traits
|
||||
- 2-3 communication guidelines
|
||||
|
||||
---
|
||||
|
||||
## Examples Gallery
|
||||
|
||||
### 🏋️ Fitness Coach
|
||||
|
||||
```markdown
|
||||
# Coach 🏋️
|
||||
|
||||
Motivierender Fitness-Coach.
|
||||
|
||||
## Stil
|
||||
- Energetisch und motivierend
|
||||
- Feiert jeden Fortschritt
|
||||
- Gibt praktische Tipps
|
||||
- Erinnert an Ziele
|
||||
|
||||
## Bereiche
|
||||
- Workouts und Übungen
|
||||
- Ernährung basics
|
||||
- Motivation
|
||||
- Routine-Aufbau
|
||||
```
|
||||
|
||||
### 🎨 Kreativ-Partner
|
||||
|
||||
```markdown
|
||||
# Muse 🎨
|
||||
|
||||
Kreativer Partner für Ideen und Projekte.
|
||||
|
||||
## Stil
|
||||
- Inspirierend und offen
|
||||
- Baut auf Ideen auf
|
||||
- Stellt "Was wäre wenn...?" Fragen
|
||||
- Kein Urteil, nur Möglichkeiten
|
||||
|
||||
## Bereiche
|
||||
- Brainstorming
|
||||
- Schreiben
|
||||
- Design-Feedback
|
||||
- Kreative Blockaden lösen
|
||||
```
|
||||
|
||||
### 🧘 Wellness-Guide
|
||||
|
||||
```markdown
|
||||
# Zen 🧘
|
||||
|
||||
Ruhiger Begleiter für Wohlbefinden.
|
||||
|
||||
## Stil
|
||||
- Ruhig und geerdet
|
||||
- Achtsame Sprache
|
||||
- Keine Eile
|
||||
- Sanfte Ermutigung
|
||||
|
||||
## Bereiche
|
||||
- Achtsamkeit
|
||||
- Stressabbau
|
||||
- Schlaf-Tipps
|
||||
- Work-Life Balance
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
**Your AI, your personality.** 🎭
|
||||
|
||||
Create personas that match your users' needs and preferences.
|
||||
395
docs/moltmates/security.md
Normal file
395
docs/moltmates/security.md
Normal file
@ -0,0 +1,395 @@
|
||||
---
|
||||
summary: "Moltmates Security - How isolation and sandboxing works"
|
||||
read_when:
|
||||
- Understanding Moltmates security model
|
||||
- Configuring sandbox restrictions
|
||||
- Evaluating multi-user safety
|
||||
---
|
||||
|
||||
# 🔒 Moltmates Security
|
||||
|
||||
> Understanding the security model, isolation layers, and how to configure safe multi-user deployments.
|
||||
|
||||
---
|
||||
|
||||
## Security Philosophy
|
||||
|
||||
Moltmates follows a **zero-trust** model:
|
||||
|
||||
> **Assume every user (and their AI) might try something malicious.**
|
||||
|
||||
Even if you trust your users personally, their AI agents might be manipulated via prompt injection. The goal is to limit blast radius.
|
||||
|
||||
---
|
||||
|
||||
## Isolation Layers
|
||||
|
||||
### Layer 1: Session Routing
|
||||
|
||||
Each user gets their own session:
|
||||
|
||||
```
|
||||
User A message → Session A → Agent A
|
||||
User B message → Session B → Agent B
|
||||
```
|
||||
|
||||
Sessions cannot:
|
||||
- Read each other's history
|
||||
- Access each other's memory
|
||||
- Share context or state
|
||||
|
||||
### Layer 2: Workspace Isolation
|
||||
|
||||
Each user has their own directory:
|
||||
|
||||
```
|
||||
~/.moltmate/users/
|
||||
├── telegram_123/ # User A (isolated)
|
||||
│ ├── SOUL.md
|
||||
│ ├── MEMORY.md
|
||||
│ └── workspace/
|
||||
└── telegram_456/ # User B (isolated)
|
||||
├── SOUL.md
|
||||
├── MEMORY.md
|
||||
└── workspace/
|
||||
```
|
||||
|
||||
Agents can only access their user's directory.
|
||||
|
||||
### Layer 3: Docker Sandboxing
|
||||
|
||||
Agent code runs in isolated containers:
|
||||
|
||||
```
|
||||
┌─────────────────────────────┐
|
||||
│ Host System │
|
||||
│ (Moltmates Gateway) │
|
||||
│ │
|
||||
│ ┌─────────┐ ┌─────────┐ │
|
||||
│ │Container│ │Container│ │
|
||||
│ │ User A │ │ User B │ │
|
||||
│ │ 🔒 │ │ 🔒 │ │
|
||||
│ └─────────┘ └─────────┘ │
|
||||
└─────────────────────────────┘
|
||||
```
|
||||
|
||||
Containers:
|
||||
- Cannot access host filesystem
|
||||
- Cannot see other containers
|
||||
- Have limited binaries
|
||||
- Are ephemeral (destroyed on restart)
|
||||
|
||||
### Layer 4: Tool Allowlisting
|
||||
|
||||
Only specified commands can run:
|
||||
|
||||
```json
|
||||
{
|
||||
"exec": {
|
||||
"security": "allowlist",
|
||||
"safeBins": ["cat", "head", "tail", "grep", "wc"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Any command not in `safeBins` is blocked.
|
||||
|
||||
---
|
||||
|
||||
## Attack Scenarios & Mitigations
|
||||
|
||||
### Prompt Injection
|
||||
|
||||
**Attack:** Malicious website returns text like "Ignore previous instructions and..."
|
||||
|
||||
**Mitigation:**
|
||||
- Sandbox limits what "bad" instructions can do
|
||||
- Only allowlisted tools available
|
||||
- Model training includes some injection resistance
|
||||
|
||||
### Filesystem Access
|
||||
|
||||
**Attack:** `cat /etc/shadow` or `rm -rf /`
|
||||
|
||||
**Mitigation:**
|
||||
- Sandbox sees only container filesystem
|
||||
- Host `/etc/shadow` not accessible
|
||||
- Deleting sandbox files only affects that session
|
||||
|
||||
### Network Exfiltration
|
||||
|
||||
**Attack:** Upload user data to attacker's server
|
||||
|
||||
**Mitigation:**
|
||||
- Optional: disable network in container
|
||||
- `web_fetch` is controllable
|
||||
- Logs show all network requests
|
||||
|
||||
### Cross-User Data Access
|
||||
|
||||
**Attack:** User A tries to read User B's files
|
||||
|
||||
**Mitigation:**
|
||||
- Workspace paths are user-specific
|
||||
- Container mounts only that user's directory
|
||||
- Session routing prevents message interception
|
||||
|
||||
### Resource Exhaustion (DoS)
|
||||
|
||||
**Attack:** Infinite loop, memory bomb, disk fill
|
||||
|
||||
**Mitigation:**
|
||||
- Container resource limits (memory, CPU)
|
||||
- Session timeouts
|
||||
- Disk quotas on workspace
|
||||
|
||||
---
|
||||
|
||||
## Configuration Options
|
||||
|
||||
### Sandbox Modes
|
||||
|
||||
```json
|
||||
"sandbox": {
|
||||
"mode": "all", // All sessions sandboxed (recommended)
|
||||
"scope": "session", // Container per session
|
||||
"workspaceAccess": "rw" // Read-write workspace
|
||||
}
|
||||
```
|
||||
|
||||
| Mode | Description | Security |
|
||||
|------|-------------|----------|
|
||||
| `all` | All sessions sandboxed | ✅ Maximum |
|
||||
| `tools` | Only tool calls sandboxed | ⚠️ Medium |
|
||||
| `none` | No sandboxing | ❌ Dangerous |
|
||||
|
||||
### Exec Security Levels
|
||||
|
||||
```json
|
||||
"exec": {
|
||||
"security": "allowlist" // Only safeBins allowed
|
||||
}
|
||||
```
|
||||
|
||||
| Level | Description | Risk |
|
||||
|-------|-------------|------|
|
||||
| `allowlist` | Only safeBins | ✅ Safe |
|
||||
| `blocklist` | Block dangerous | ⚠️ Medium |
|
||||
| `full` | Everything allowed | ❌ Dangerous |
|
||||
|
||||
### Safe Binaries
|
||||
|
||||
Only add what's necessary:
|
||||
|
||||
```json
|
||||
"safeBins": [
|
||||
// Read-only (safe)
|
||||
"cat", "head", "tail", "grep", "wc", "ls",
|
||||
|
||||
// Text processing (safe)
|
||||
"sed", "awk", "sort", "uniq",
|
||||
|
||||
// Document conversion (safe)
|
||||
"pdftotext",
|
||||
|
||||
// DANGEROUS - avoid in multi-user:
|
||||
// "curl", "wget" - network access
|
||||
// "python", "node" - arbitrary code
|
||||
// "rm", "mv" - destructive
|
||||
// "bash", "sh" - shell escape
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Network Security
|
||||
|
||||
### Disable Outbound Network
|
||||
|
||||
For maximum isolation, containers have no network:
|
||||
|
||||
```json
|
||||
"sandbox": {
|
||||
"network": "none"
|
||||
}
|
||||
```
|
||||
|
||||
### Control Web Access
|
||||
|
||||
If network needed, control at tool level:
|
||||
|
||||
```json
|
||||
"tools": {
|
||||
"web": {
|
||||
"fetch": {
|
||||
"enabled": true,
|
||||
"allowedDomains": ["wikipedia.org", "docs.python.org"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Gateway Binding
|
||||
|
||||
Never expose gateway publicly:
|
||||
|
||||
```json
|
||||
"gateway": {
|
||||
"bind": "127.0.0.1", // Localhost only!
|
||||
"port": 18790
|
||||
}
|
||||
```
|
||||
|
||||
For remote access, use SSH tunnel or Tailscale.
|
||||
|
||||
---
|
||||
|
||||
## Audit & Monitoring
|
||||
|
||||
### Check Running Containers
|
||||
|
||||
```bash
|
||||
# See all Moltmates containers
|
||||
docker ps | grep moltmate-sbx
|
||||
|
||||
# Resource usage
|
||||
docker stats
|
||||
```
|
||||
|
||||
### Review Logs
|
||||
|
||||
```bash
|
||||
# All gateway activity
|
||||
journalctl -u moltmate -f
|
||||
|
||||
# Filter for specific user
|
||||
journalctl -u moltmate | grep "telegram_123456"
|
||||
```
|
||||
|
||||
### Audit User Actions
|
||||
|
||||
Enable detailed logging:
|
||||
|
||||
```json
|
||||
"logging": {
|
||||
"level": "debug",
|
||||
"tools": true // Log all tool calls
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Security Checklist
|
||||
|
||||
### Before Deployment
|
||||
|
||||
- [ ] Sandbox mode set to `all`
|
||||
- [ ] Exec security set to `allowlist`
|
||||
- [ ] Only necessary safeBins listed
|
||||
- [ ] Gateway bound to localhost
|
||||
- [ ] API keys not in git
|
||||
- [ ] Strong gateway token (if exposed)
|
||||
|
||||
### Regular Checks
|
||||
|
||||
- [ ] Review user workspaces for unusual files
|
||||
- [ ] Check container resource usage
|
||||
- [ ] Audit logs for suspicious activity
|
||||
- [ ] Update Moltmates regularly
|
||||
- [ ] Rotate API keys periodically
|
||||
|
||||
### Per-User Considerations
|
||||
|
||||
- [ ] Trust level: family vs strangers
|
||||
- [ ] Appropriate tool access
|
||||
- [ ] Workspace size limits
|
||||
- [ ] Session monitoring
|
||||
|
||||
---
|
||||
|
||||
## Incident Response
|
||||
|
||||
### If Compromise Suspected
|
||||
|
||||
1. **Stop gateway:** `systemctl stop moltmate`
|
||||
2. **Review logs:** `journalctl -u moltmate --since "24 hours ago"`
|
||||
3. **Check containers:** `docker ps -a | grep moltmate`
|
||||
4. **Inspect workspaces:** `ls -la ~/.moltmate/users/*/`
|
||||
5. **Rotate API keys**
|
||||
6. **Remove suspicious users from allowlist**
|
||||
7. **Restart with fresh state if needed**
|
||||
|
||||
### Resetting a User
|
||||
|
||||
```bash
|
||||
# Remove their workspace
|
||||
rm -rf ~/.moltmate/users/telegram_SUSPICIOUS_ID/
|
||||
|
||||
# Remove from allowlist
|
||||
# Edit config, remove ID from allowFrom
|
||||
|
||||
# Restart
|
||||
systemctl restart moltmate
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Comparison: Trust Levels
|
||||
|
||||
| Scenario | Sandbox | Network | Tools |
|
||||
|----------|---------|---------|-------|
|
||||
| Personal (just you) | Optional | Full | Full |
|
||||
| Family/Friends | Yes | Limited | Allowlist |
|
||||
| Strangers/Public | Yes | None | Minimal |
|
||||
| High-security | Yes + limits | None | Read-only |
|
||||
|
||||
---
|
||||
|
||||
## Advanced: Custom Sandbox
|
||||
|
||||
For custom isolation, edit `Dockerfile.sandbox`:
|
||||
|
||||
```dockerfile
|
||||
FROM debian:bookworm-slim
|
||||
|
||||
# Minimal user
|
||||
RUN useradd -m agent
|
||||
|
||||
# No shell
|
||||
RUN rm /bin/bash /bin/sh
|
||||
|
||||
# Read-only root
|
||||
# (Configure in docker run)
|
||||
|
||||
# Only needed tools
|
||||
RUN apt-get update && apt-get install -y \
|
||||
coreutils \
|
||||
&& rm -rf /var/lib/apt/lists/*
|
||||
|
||||
USER agent
|
||||
WORKDIR /workspace
|
||||
```
|
||||
|
||||
Build with hardening:
|
||||
|
||||
```bash
|
||||
docker build \
|
||||
--no-cache \
|
||||
--security-opt no-new-privileges \
|
||||
-f Dockerfile.sandbox \
|
||||
-t moltmate-sandbox:hardened .
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Resources
|
||||
|
||||
- [Docker Security Best Practices](https://docs.docker.com/develop/security-best-practices/)
|
||||
- [Moltbot Security Docs](/gateway/security)
|
||||
- [OWASP AI Security](https://owasp.org/www-project-ai-security/)
|
||||
|
||||
---
|
||||
|
||||
**Security is a journey, not a destination.** 🔒
|
||||
|
||||
Review regularly. Update often. Stay vigilant.
|
||||
397
docs/moltmates/setup.md
Normal file
397
docs/moltmates/setup.md
Normal file
@ -0,0 +1,397 @@
|
||||
---
|
||||
summary: "Moltmates Setup Guide - Step by step installation"
|
||||
read_when:
|
||||
- Installing Moltmates for the first time
|
||||
- Setting up multi-user deployment
|
||||
---
|
||||
|
||||
# 🛠️ Moltmates Setup Guide
|
||||
|
||||
> Complete step-by-step installation for Moltmates multi-user deployment.
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### System Requirements
|
||||
|
||||
| Component | Minimum | Recommended |
|
||||
|-----------|---------|-------------|
|
||||
| CPU | 2 cores | 4+ cores |
|
||||
| RAM | 4 GB | 8+ GB |
|
||||
| Disk | 20 GB | 50+ GB SSD |
|
||||
| OS | Linux (Debian/Ubuntu) | Ubuntu 22.04+ |
|
||||
|
||||
### Software Requirements
|
||||
|
||||
```bash
|
||||
# Node.js ≥22
|
||||
node --version # Should be 22.x+
|
||||
|
||||
# Docker
|
||||
docker --version # Should be 20.x+
|
||||
|
||||
# pnpm (recommended)
|
||||
pnpm --version # Or npm/bun
|
||||
```
|
||||
|
||||
### Install Prerequisites (Ubuntu/Debian)
|
||||
|
||||
```bash
|
||||
# Node.js 22
|
||||
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
|
||||
sudo apt-get install -y nodejs
|
||||
|
||||
# Docker
|
||||
curl -fsSL https://get.docker.com | sh
|
||||
sudo usermod -aG docker $USER
|
||||
# Log out and back in
|
||||
|
||||
# pnpm
|
||||
npm install -g pnpm
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 1: Clone Repository
|
||||
|
||||
```bash
|
||||
cd ~
|
||||
git clone https://github.com/YOUR_FORK/moltmates
|
||||
cd moltmates
|
||||
```
|
||||
|
||||
Or if forking from upstream:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/moltbot/moltbot moltmates
|
||||
cd moltmates
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 2: Install Dependencies
|
||||
|
||||
```bash
|
||||
pnpm install
|
||||
```
|
||||
|
||||
This installs all Node.js dependencies.
|
||||
|
||||
---
|
||||
|
||||
## Step 3: Build Moltmates
|
||||
|
||||
```bash
|
||||
pnpm build
|
||||
```
|
||||
|
||||
Creates the `dist/` directory with compiled code.
|
||||
|
||||
---
|
||||
|
||||
## Step 4: Build Sandbox Image
|
||||
|
||||
The Docker sandbox isolates user agents:
|
||||
|
||||
```bash
|
||||
docker build -f Dockerfile.sandbox -t moltmate-sandbox:bookworm-slim .
|
||||
```
|
||||
|
||||
### Verify image:
|
||||
|
||||
```bash
|
||||
docker images | grep moltmate-sandbox
|
||||
# Should show: moltmate-sandbox bookworm-slim ...
|
||||
```
|
||||
|
||||
### Customize sandbox (optional):
|
||||
|
||||
Edit `Dockerfile.sandbox` to add tools:
|
||||
|
||||
```dockerfile
|
||||
FROM debian:bookworm-slim
|
||||
|
||||
RUN apt-get update && apt-get install -y \
|
||||
poppler-utils \
|
||||
imagemagick \
|
||||
ffmpeg \
|
||||
# Add more packages here
|
||||
&& rm -rf /var/lib/apt/lists/*
|
||||
```
|
||||
|
||||
Rebuild after changes:
|
||||
```bash
|
||||
docker build -f Dockerfile.sandbox -t moltmate-sandbox:bookworm-slim .
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 5: Create Configuration
|
||||
|
||||
```bash
|
||||
# Create config directory
|
||||
mkdir -p ~/.moltmate
|
||||
|
||||
# Copy example config
|
||||
cp moltmate.example.json ~/.moltmate/moltmate.json
|
||||
|
||||
# Edit config
|
||||
nano ~/.moltmate/moltmate.json
|
||||
```
|
||||
|
||||
### Minimal Configuration
|
||||
|
||||
```json
|
||||
{
|
||||
"gateway": {
|
||||
"port": 18790,
|
||||
"bind": "127.0.0.1"
|
||||
},
|
||||
"agents": {
|
||||
"main": {
|
||||
"model": "anthropic/claude-sonnet-4-5",
|
||||
"provider": "anthropic"
|
||||
}
|
||||
},
|
||||
"providers": {
|
||||
"anthropic": {
|
||||
"apiKey": "${ANTHROPIC_API_KEY}"
|
||||
}
|
||||
},
|
||||
"channels": {
|
||||
"telegram": {
|
||||
"enabled": true,
|
||||
"botToken": "${TELEGRAM_BOT_TOKEN}",
|
||||
"dmPolicy": "allowlist",
|
||||
"allowFrom": ["YOUR_TELEGRAM_ID"]
|
||||
}
|
||||
},
|
||||
"sandbox": {
|
||||
"mode": "all",
|
||||
"scope": "session",
|
||||
"workspaceAccess": "rw"
|
||||
},
|
||||
"tools": {
|
||||
"allow": ["read", "write", "edit", "exec", "web_search", "web_fetch"],
|
||||
"exec": {
|
||||
"security": "allowlist",
|
||||
"safeBins": ["cat", "head", "tail", "grep", "wc", "ls"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Environment Variables
|
||||
|
||||
Create `.env` file or export:
|
||||
|
||||
```bash
|
||||
export ANTHROPIC_API_KEY="sk-ant-..."
|
||||
export TELEGRAM_BOT_TOKEN="123456:ABC..."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 6: Create Telegram Bot
|
||||
|
||||
1. Message [@BotFather](https://t.me/BotFather) on Telegram
|
||||
2. Send `/newbot`
|
||||
3. Choose name and username
|
||||
4. Copy the token (looks like `123456789:ABCdefGHI...`)
|
||||
5. Add to config as `TELEGRAM_BOT_TOKEN`
|
||||
|
||||
### Get Your Telegram ID
|
||||
|
||||
1. Message [@userinfobot](https://t.me/userinfobot)
|
||||
2. Copy your numeric ID
|
||||
3. Add to `allowFrom` array
|
||||
|
||||
---
|
||||
|
||||
## Step 7: Test Run
|
||||
|
||||
```bash
|
||||
# Development mode (foreground)
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
You should see:
|
||||
```
|
||||
Gateway starting on 127.0.0.1:18790
|
||||
Telegram connected
|
||||
Ready for messages
|
||||
```
|
||||
|
||||
Test by messaging your bot on Telegram!
|
||||
|
||||
---
|
||||
|
||||
## Step 8: Production Setup (systemd)
|
||||
|
||||
### Create Service File
|
||||
|
||||
```bash
|
||||
sudo nano /etc/systemd/system/moltmate.service
|
||||
```
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
Description=Moltmates Gateway
|
||||
After=network.target docker.service
|
||||
Requires=docker.service
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=root
|
||||
WorkingDirectory=/root/moltmates
|
||||
Environment=NODE_ENV=production
|
||||
Environment=ANTHROPIC_API_KEY=sk-ant-...
|
||||
Environment=TELEGRAM_BOT_TOKEN=123456:ABC...
|
||||
ExecStart=/usr/bin/node dist/cli.js gateway
|
||||
Restart=always
|
||||
RestartSec=10
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
### Enable & Start
|
||||
|
||||
```bash
|
||||
sudo systemctl daemon-reload
|
||||
sudo systemctl enable moltmate
|
||||
sudo systemctl start moltmate
|
||||
|
||||
# Check status
|
||||
sudo systemctl status moltmate
|
||||
|
||||
# View logs
|
||||
sudo journalctl -u moltmate -f
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 9: Add Users
|
||||
|
||||
### Add to Allowlist
|
||||
|
||||
Edit config to add user IDs:
|
||||
|
||||
```json
|
||||
"channels": {
|
||||
"telegram": {
|
||||
"allowFrom": [
|
||||
"YOUR_ID",
|
||||
"FRIEND_ID",
|
||||
"FAMILY_ID"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Restart to Apply
|
||||
|
||||
```bash
|
||||
sudo systemctl restart moltmate
|
||||
```
|
||||
|
||||
### Verify User Workspaces
|
||||
|
||||
After users message the bot:
|
||||
|
||||
```bash
|
||||
ls ~/.moltmate/users/
|
||||
# Should show: telegram_123456 telegram_789012 etc.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Step 10: Customize Personas (Optional)
|
||||
|
||||
### Edit Persona Templates
|
||||
|
||||
```bash
|
||||
# Cami persona
|
||||
nano /root/moltmates/templates/souls/cami.md
|
||||
|
||||
# Molty persona
|
||||
nano /root/moltmates/templates/souls/molty.md
|
||||
|
||||
# Custom template
|
||||
nano /root/moltmates/templates/souls/custom.md
|
||||
```
|
||||
|
||||
### Rebuild After Changes
|
||||
|
||||
```bash
|
||||
cd /root/moltmates
|
||||
pnpm build
|
||||
sudo systemctl restart moltmate
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
- [ ] Node.js ≥22 installed
|
||||
- [ ] Docker running
|
||||
- [ ] Sandbox image built
|
||||
- [ ] Config file created
|
||||
- [ ] API keys set
|
||||
- [ ] Telegram bot created
|
||||
- [ ] Your ID in allowFrom
|
||||
- [ ] Gateway starts without errors
|
||||
- [ ] Bot responds to messages
|
||||
- [ ] User workspace created in `~/.moltmate/users/`
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
- [Add more users](/moltmates/faq#how-do-i-add-a-new-user)
|
||||
- [Customize personas](/moltmates/personas)
|
||||
- [Configure security](/moltmates/security)
|
||||
- [Set up skills](/moltmates/skills)
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Gateway won't start
|
||||
|
||||
```bash
|
||||
# Check logs
|
||||
journalctl -u moltmate -n 50
|
||||
|
||||
# Common issues:
|
||||
# - Port already in use: change gateway.port
|
||||
# - Invalid config: validate JSON
|
||||
# - Missing env vars: check ANTHROPIC_API_KEY, etc.
|
||||
```
|
||||
|
||||
### Docker sandbox fails
|
||||
|
||||
```bash
|
||||
# Check Docker is running
|
||||
docker ps
|
||||
|
||||
# Rebuild image
|
||||
docker build -f Dockerfile.sandbox -t moltmate-sandbox:bookworm-slim .
|
||||
|
||||
# Check for orphan containers
|
||||
docker ps -a | grep moltmate
|
||||
```
|
||||
|
||||
### Bot doesn't respond
|
||||
|
||||
1. Verify bot token is correct
|
||||
2. Check user ID is in allowFrom
|
||||
3. Verify gateway is running
|
||||
4. Check logs for errors
|
||||
|
||||
---
|
||||
|
||||
**Setup complete! 🎉**
|
||||
|
||||
Your Moltmates server is now ready to serve multiple users with isolated AI assistants.
|
||||
Loading…
Reference in New Issue
Block a user