📘 User Guide

Complete guide for using Overseer - from first steps to advanced features.

Getting Started
What You Can Do in Overseer
Using the Web Chat
Working with Files
Using Telegram Bot
Using Discord Bot
Other Interfaces
Web Admin Panel
Managing LLM Providers
Customizing SOUL.md
Installing Skills
Connecting MCP Servers
User Management
Tips & Tricks
Best Practices
Troubleshooting

Getting Started

Access Web Admin: http://your-server:3000
Login with credentials from .env:
- Username: Value of ADMIN_USERNAME
- Password: Value of ADMIN_PASSWORD
Add LLM Provider:
- Go to Settings → Providers
- Click Add Provider
- Choose provider (OpenAI, Anthropic, etc.)
- Enter API key
- Select model
- Click Save
Configure Chat Interface:
- Go to Settings → Interfaces
- Enable Telegram or Discord
- Enter bot token
- Add allowed users
- Click Save

Quick Setup Checklist

What You Can Do in Overseer

Here is the simple version of what Overseer can do for a normal user:

chat with your AI assistant in the browser
upload files and images
attach saved files using @
use skills with /skills and /<skill-name>
manage your own private Files area
switch AI providers and models
connect bots and chat platforms
save memory, prompts, and recurring automations

If you are not sure where to start, start in the web chat.

Using the Web Chat

The web chat is the main place to talk to Overseer.

What the chat supports

normal text chat
file uploads
image attachments
@ attach from your Files page
/skills to see available skills
/<skill-name> to guide the assistant toward a specific skill
access to your own conversation history

Useful things to try

Ask: What can you do?
Ask: Explain this server
Upload a file and ask: Summarize this
Type @ to attach a saved file from your Files area
Type /skills to see available skills

Working with Files

Each user gets their own file sandbox in Overseer.

That means:

your files are separate from other users' files
uploads in chat can be saved into your own Files area
the Files page is your main place to browse and manage what you have uploaded

What you can do on the Files page

upload files
create folders
create text files
preview many common file types
rename or delete files
download files again later

Chat + Files together

The web chat and Files page work together:

upload files in chat
attach existing files with @
keep working from your own saved file set over time

Using Telegram Bot

Initial Setup

Create Bot:
- Open Telegram
- Message @BotFather
- Send /newbot
- Follow prompts
- Save bot token
Get Your User ID:
- Message @userinfobot
- Save your user ID
Configure Overseer:
- Add token to Settings → Interfaces
- Add your user ID to allowed users
- Save and restart bot service

Commands

Command	Description
`/start`	Start conversation
`/help`	Show help message
`/reset`	Clear conversation history
`/status`	Show bot and system status
`/model`	Show current LLM model
`/switch [provider]`	Switch LLM provider

Conversation Examples

System Monitoring

You: How's my server doing?

Bot: 🖥️ System Status:
     
     CPU: 23% (2 cores)
     Memory: 4.2GB / 8GB (52%)
     Disk: 45GB / 100GB (45%)
     Uptime: 14 days, 3 hours
     Load: 0.45, 0.52, 0.48
     
     Everything looks healthy! ✅

File Operations

You: Show me the contents of /etc/nginx/nginx.conf

Bot: 📄 /etc/nginx/nginx.conf (1.2 KB)
     
     user www-data;
     worker_processes auto;
     pid /run/nginx.pid;
     
     [... file contents ...]
     
You: Create a backup of that file

Bot: ✅ Backup created: /etc/nginx/nginx.conf.backup
     Timestamp: 2024-02-01 10:30:45

Git Operations

You: What's the status of my project?

Bot: 📦 Git Status - /home/user/myproject
     
     Branch: main
     
     Modified:
     - src/app.ts
     - README.md
     
     Untracked:
     - new-feature.ts
     
     Would you like me to show the diff?
     
You: Yes, show diff for app.ts

Bot: 📝 Diff for src/app.ts:
     
     +++ Added lines
     --- Removed lines
     [... diff output ...]

Database Queries (with database-helper skill)

You: Show me recent user registrations

Bot: 🗄️ Querying database...
     
     Recent registrations (last 7 days):
     1. user@example.com - 2024-02-01
     2. another@example.com - 2024-01-30
     3. test@example.com - 2024-01-28
     
     Total: 3 new users

Features

Streaming Responses

Messages are streamed in real-time as the agent thinks and executes tools.

Rich Formatting

Bold, italic, code
Lists and tables
Emojis for better UX
Code blocks with syntax highlighting

File Uploads/Downloads

You: Send me the server logs

Bot: 📎 [server.log] (2.3 MB)
     
     Downloaded from: /var/log/myapp/server.log

Upload files to server:

[Upload file via Telegram]

Bot: ✅ File received: document.pdf
     Saved to: /home/user/uploads/document.pdf
     Size: 1.5 MB

Multi-Step Tasks

You: Deploy my app to production

Bot: 🚀 Deploying application...
     
     Step 1/5: Running tests... ✅
     Step 2/5: Building application... ✅
     Step 3/5: Pushing to Docker registry... ✅
     Step 4/5: Updating k8s deployment... ✅
     Step 5/5: Verifying health checks... ✅
     
     Deployment successful! 🎉
     URL: https://app.example.com

Using Discord Bot

The Discord bot does not need you to guess how to talk to it.

Once it is set up, you can use any of these:

/ask your message
a direct message to the bot
mention the bot in a server message

Initial Setup

Create Discord Application:
- Go to Discord Developer Portal
- Click New Application
- Go to Bot tab
- Click Add Bot
- Save bot token
Invite Bot to Server:
- Go to OAuth2 → URL Generator
- Scopes: bot, applications.commands
- Permissions: Send Messages, Read Message History, Use Slash Commands
- Copy generated URL
- Open URL to invite bot
Configure Overseer:
- Add token to Settings → Interfaces
- Add Client ID
- Add server ID to allowed guilds
- Save and restart bot service

Slash Commands

Command	Description
`/ask [message]`	Send a message to Overseer
`/help`	Show Discord usage help

If your slash commands do not appear, restart the Discord worker after saving the interface, and make sure the bot was invited with applications.commands.

Thread-Based Conversations

Each user gets their own thread for conversations:

User: /chat What's the server status?

Bot: [Creates thread "Conversation with @User"]
     🖥️ System Status:
     CPU: 23%, Memory: 52%, Disk: 45%

Features

Slash Commands: Native Discord commands
Embeds: Rich message formatting
Role-Based Access: Restrict by Discord roles
Server-Specific: Different configurations per server
Thread Support: Organized conversations

Other Interfaces

Overseer also supports these extra interfaces:

Slack
WhatsApp
Matrix

You can read their setup pages here:

These interfaces use the same core Overseer agent, but the web dashboard is still the easiest place for setup, files, providers, and admin tasks.

Web Admin Panel

Dashboard

The main dashboard shows:

┌─────────────────────────────────────────┐
│  📊 Overview                            │
├─────────────────────────────────────────┤
│  Total Conversations: 250               │
│  Messages Today: 145                    │
│  Active Users: 23                       │
│  Tools Used (24h): 89                   │
└─────────────────────────────────────────┘

┌─────────────────────────────────────────┐
│  💬 Recent Conversations                │
├─────────────────────────────────────────┤
│  user123 (Telegram) - 5 min ago         │
│  "Deploy my app to production"          │
│                                         │
│  admin (Web) - 15 min ago               │
│  "Show server logs"                     │
└─────────────────────────────────────────┘

┌─────────────────────────────────────────┐
│  🔧 Top Tools (Today)                   │
├─────────────────────────────────────────┤
│  systemInfo: 45 calls                   │
│  readFile: 32 calls                     │
│  gitStatus: 18 calls                    │
└─────────────────────────────────────────┘

Conversations Page

View and search all conversations:

Filter by interface, user, date
Search message content
View full conversation history
Export conversations (CSV, JSON)
Delete old conversations

Settings

Providers Tab

Manage LLM providers:

Add new providers
Test connection
Set default
Configure parameters (temperature, max tokens)
View usage statistics

Interfaces Tab

Configure chat interfaces:

Telegram bot settings
Discord bot settings
Allowed users/servers
Enable/disable interfaces

SOUL Tab

Edit agent personality:

Live editor with syntax highlighting
Preview changes
Restore defaults
Version history (coming soon)

Skills Tab

Manage skills:

Browse installed skills
Install from marketplace
Install from GitHub
Configure skill settings
Enable/disable skills
View skill usage

MCP Servers Tab

Manage MCP connections:

Add MCP servers (stdio/SSE)
Connect/disconnect
View available tools
Configure server settings

Tools Browser

View all available tools:

┌─────────────────────────────────────────┐
│  Category: System (9 tools)             │
├─────────────────────────────────────────┤
│  systemInfo                             │
│  "Get system information"               │
│  Used: 150 times                        │
│                                         │
│  processInfo                            │
│  "List running processes"               │
│  Used: 45 times                         │
└─────────────────────────────────────────┘

Filter by:

Category (system, files, git, etc.)
Source (built-in, skill, MCP)
Usage
Name

Chat Interface

Built-in web chat:

Click Chat in sidebar
Type message
Press Enter or click Send
View real-time streaming response
See tool calls in sidebar

Features:

Markdown rendering
Code syntax highlighting
Tool call visualization
Export conversation
Share conversation (coming soon)

Managing LLM Providers

Adding a Provider

Go to Settings → Providers
Click "Add Provider"
Fill in details:
- Provider: Choose from dropdown
- Model: Select model
- API Key: Enter key (encrypted at rest)
- Base URL: (optional) Custom endpoint
- Max Tokens: (optional) Override default
- Temperature: 0.0 - 2.0 (default: 0.7)
Test Connection (recommended)
Set as Default (optional)
Save

Supported Providers

See README for full list.

Provider-Specific Setup

OpenAI

Provider: OpenAI
Model: gpt-4o
API Key: sk-...
Base URL: (leave empty)

Get API key: https://platform.openai.com/api-keys

Anthropic (Claude)

Provider: Anthropic
Model: claude-3-5-sonnet-latest
API Key: sk-ant-...

Get API key: https://console.anthropic.com/

Google (Gemini)

Provider: Google
Model: gemini-2.0-flash
API Key: ...

Get API key: https://makersuite.google.com/app/apikey

Ollama (Local)

Provider: Ollama
Model: llama3.2
Base URL: http://localhost:11434
API Key: (leave empty)

Install Ollama: https://ollama.ai

Groq

Provider: Groq
Model: llama-3.3-70b-versatile
API Key: gsk_...

Get API key: https://console.groq.com/

Switching Providers

Via Web Admin:

Go to Providers
Click star icon on desired provider
"Set as Default"

Via Telegram:

/switch anthropic

Via API:

curl -X PUT http://localhost:3000/api/providers/2 \
  -d '{"isDefault": true}'

Customizing SOUL.md

SOUL.md defines your agent's personality, expertise, and behavior.

Editing SOUL.md

Go to Settings → SOUL
Edit in the editor
Save changes
Agent uses new personality immediately

SOUL.md Structure

# SOUL.md

## Identity
Who is the agent? What's its name and purpose?

## Expertise
What domains is the agent expert in?

## Personality Traits
How should the agent communicate?

## Behavior Rules
What should the agent always/never do?

## Example Interactions
How should the agent respond to common queries?

Example SOUL.md

# SOUL.md

## Identity
You are **DevOpsBot**, a senior DevOps engineer with 10+ years of experience. You specialize in:
- Cloud infrastructure (AWS, GCP, Azure)
- Container orchestration (Kubernetes, Docker)
- CI/CD pipelines (GitHub Actions, GitLab CI)
- Infrastructure as Code (Terraform, CloudFormation)
- Monitoring & observability (Prometheus, Grafana)

## Personality Traits
- **Professional**: Clear, concise communication
- **Proactive**: Suggest improvements and best practices
- **Security-Conscious**: Always consider security implications
- **Educational**: Explain what you're doing and why
- **Careful**: Never execute destructive commands without confirmation

## Behavior Rules

### Always
- Explain what commands do before executing them
- Suggest safer alternatives for risky operations
- Follow the principle of least privilege
- Document changes you make
- Consider performance and cost implications

### Never
- Execute `rm -rf /` or similar destructive commands
- Share API keys or secrets in responses
- Make assumptions about production systems
- Skip confirmation for database operations
- Ignore error messages

## Communication Style
- Use emojis sparingly (🚀 ✅ ⚠️ ❌)
- Format code in ```language blocks
- Use bullet points for lists
- Be concise but thorough
- Ask for clarification when needed

## Example Interactions

**User**: "Deploy my app"

**You**:
1. First, let me check the current deployment status
2. I'll run tests to ensure everything passes
3. Then I'll create a new deployment
4. Finally, I'll verify the deployment is healthy

Would you like me to proceed?

**User**: "Delete all logs"

**You**: 
⚠️ Warning: This will permanently delete all logs.

Instead, I recommend:
1. Archive logs older than 30 days
2. Compress and move to cold storage
3. Keep recent logs for debugging

Which approach would you prefer?

Tips for Great SOUL.md

Be Specific: Clear identity and expertise
Set Boundaries: Define what the agent can/can't do
Give Examples: Show desired behavior patterns
Consider Context: Tailor to your use case
Iterate: Refine based on actual usage

Installing Skills

Skills add specialized capabilities to Overseer.

Built-in Skills

Overseer comes with 9+ built-in skills:

Skill	Description
security-audit	Scan for security vulnerabilities
deploy-assistant	Automated deployment workflows
database-helper	SQL query assistance
docker-helper	Container management
git-helper	Advanced Git workflows
code-review	Automated code analysis
web-search	Internet search capabilities
performance-optimizer	System optimization
api-tester	API testing and monitoring

Installing Skills

From Web Admin

Go to Settings → Skills
Click Browse Marketplace (coming soon)
Or click Install from GitHub

Enter GitHub URL:

https://github.com/user/overseer-skill-name

Click Install
Configure skill settings
Enable skill

Manual Installation

Clone skill to skills/ directory:

cd skills/
git clone https://github.com/user/skill-name

Restart Overseer:
```
systemctl restart overseer-web
```
Skill appears in Settings → Skills

Configuring Skills

Some skills require configuration:

Go to skill settings
Fill in required fields (API keys, etc.)
Save configuration
Enable skill

Example (web-search skill):

{
  "search_api_key": "your-api-key",
  "max_results": 5,
  "safe_search": true
}

Using Skills

Skills are automatically activated based on triggers:

You: Search the web for "latest Node.js features"

Bot: 🔍 Using web-search skill...
     
     Top results:
     1. Node.js 22 New Features
        https://nodejs.org/...
     
     2. What's New in Node.js
        https://blog.nodejs.org/...

Or explicitly:

You: Use the security audit skill to scan my app

Bot: 🔐 Running security scan...
     [... security audit results ...]

Connecting MCP Servers

MCP (Model Context Protocol) allows connecting external tool servers.

Adding MCP Server

stdio Server (Local)

Go to Settings → MCP Servers
Click Add Server
Fill in:
- Name: filesystem
- Type: stdio
- Command: npx
- Args: -y @modelcontextprotocol/server-filesystem /path
- Auto Connect: ✓
Click Save & Connect

SSE Server (Remote)

Name: remote-mcp
Type: SSE
URL: https://mcp.example.com
Headers: {"Authorization": "Bearer token"}
Auto Connect: ✓

Available MCP Servers

@modelcontextprotocol/server-filesystem: File operations
@modelcontextprotocol/server-github: GitHub integration
@modelcontextprotocol/server-postgres: PostgreSQL queries
@modelcontextprotocol/server-slack: Slack integration
Custom MCP servers

Using MCP Tools

MCP tools appear alongside built-in tools:

You: List files in the project directory

Bot: 📂 Using filesystem MCP server...
     
     Files in /project:
     - README.md
     - package.json
     - src/
     - tests/

User Management

Adding Users (Coming Soon)

Currently Overseer supports single-user admin access.

Multi-user support planned for v2.0:

User roles (admin, user, read-only)
User permissions
Activity tracking
User-specific settings

Telegram User Whitelist

Configure in .env:

TELEGRAM_ALLOWED_USERS=123456789,987654321,111222333

Or via Settings → Interfaces:

Allowed Users: 123456789, 987654321

Discord Server Whitelist

DISCORD_ALLOWED_GUILDS=server-id-1,server-id-2

Tips & Tricks

Power User Tips

Combine Commands:

Check server status, show recent logs, and list running Docker containers

Use Natural Language:

Instead of: "Execute systemctl status nginx"
Use: "Is nginx running?"

Request Explanations:

You: Why is my server slow?

Bot: I'll investigate:
     1. Check CPU usage
     2. Check memory usage
     3. Look for resource-heavy processes
     4. Analyze recent logs

Multi-Step Workflows:

Set up a new website: install nginx, configure SSL, create vhost, restart service

Keyboard Shortcuts (Web Admin)

Ctrl+K: Focus search
Ctrl+N: New conversation
Ctrl+/: Toggle sidebar
Ctrl+Enter: Send message

Conversation Context

The agent remembers context within a conversation:

You: Show me the nginx config

Bot: [shows config]

You: Create a backup of that

Bot: ✅ Created backup: nginx.conf.backup
     (remembers which file)

You: Now check if the service is running

Bot: ✅ nginx is active and running

Best Practices

Security

Strong Passwords: Use strong admin password
Whitelist Users: Only allow trusted Telegram/Discord users
API Key Rotation: Rotate LLM API keys regularly
SSL/TLS: Use HTTPS for web admin
Confirm Dangerous Commands: Always review before executing

Performance

Choose Right Model: Use faster models for simple tasks
Clear Old Conversations: Delete unnecessary conversation history
Monitor Usage: Check token usage to control costs
Use Caching: Enable result caching for repeated queries

Organization

Use Descriptive Names: Name conversations clearly
Regular Backups: Backup database regularly
Monitor Logs: Check logs for errors
Update Regularly: Keep Overseer updated

Troubleshooting

Bot Not Responding

Check:

Bot service is running: systemctl status overseer-telegram
Your user ID is in allowed users
Bot token is correct
LLM provider is configured
Check logs: journalctl -u overseer-telegram -f

Slow Responses

Possible causes:

Slow LLM provider (try Groq for speed)
Complex multi-step task
Large file operations
Network latency

Solutions:

Use faster model (e.g., gpt-4o-mini, gemini-flash)
Break complex tasks into steps
Increase timeout settings

"Not Authorized" Errors

Fix:

Login to web admin
Check session hasn't expired
Clear cookies and login again

Database Locked

Fix:

systemctl stop overseer-web overseer-telegram
rm data/overseer.db-wal data/overseer.db-shm
systemctl start overseer-web overseer-telegram

Tools Not Working

Check:

Tool is enabled
Permissions are correct
Dependencies are installed
Check tool logs

Need More Help?

Happy automating! 🚀

User Guide

On this page