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