Marvin Manager

A Django-based AI assistant platform with multi-channel messaging support (Telegram, Slack) and multiple LLM backends (Anthropic Claude, Google Gemini, Ollama, vLLM).

Quick Start

# 1. Clone and install
git clone https://github.com/monkut/marvin-manager.git
cd marvin-manager
uv sync

# 2. Start PostgreSQL (using Docker)
docker-compose up -d

# 3. Run the setup wizard
cd mrvn
uv run python manage.py onboard

# 4. Start the development server
uv run python manage.py runserver

Access the admin panel at http://127.0.0.1:8000/admin/

Features

Multi-Channel Messaging: Telegram and Slack integration
Multiple LLM Providers: Anthropic, Google Gemini, Ollama, vLLM
Conversation Memory: Session persistence and message history
Auto-Reply: Configurable routing rules and response logic
Rate Limiting: Built-in rate limiting to avoid API throttling
Django Admin: Full management interface

Requirements

Python 3.14
PostgreSQL 14+
uv package manager

Ubuntu/Linux Setup

1. Install System Dependencies

# Update package list
sudo apt update

# Install build essentials and PostgreSQL
sudo apt install -y build-essential libpq-dev postgresql postgresql-contrib

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Reload shell or source the path
source ~/.bashrc  # or ~/.zshrc

2. Install Python 3.14

# uv can install Python for you
uv python install 3.14

3. Clone and Setup Project

# Clone the repository
git clone https://github.com/monkut/marvin-manager.git
cd marvin-manager

# Install dependencies
uv sync

# Setup pre-commit hooks (optional, for development)
uv tool install pre-commit
pre-commit install

4. Configure PostgreSQL

# Start PostgreSQL service
sudo systemctl start postgresql
sudo systemctl enable postgresql

# Create database and user
sudo -u postgres psql <<EOF
CREATE USER mrvn WITH PASSWORD 'your_secure_password';
CREATE DATABASE mrvn OWNER mrvn;
GRANT ALL PRIVILEGES ON DATABASE mrvn TO mrvn;
EOF

5. Environment Configuration

Create a .env file or export environment variables:

# Database
export DB_NAME=mrvn
export DB_USER=mrvn
export DB_PASS=your_secure_password
export DB_HOST=127.0.0.1
export DB_PORT=5432

# Django
export DEBUG=True
export IS_LOCAL_DEVELOPMENT=True
export SECRET_KEY='your-secret-key-here'

# Rate Limiting (optional)
export RATE_LIMIT_ENABLED=True
export RATE_LIMIT_DEFAULT_RPM=60

6. Initialize the Application

Option A: Interactive Setup Wizard (Recommended)

cd mrvn
uv run python manage.py onboard

The wizard will:

Check system requirements
Run database migrations
Create an admin superuser
Configure a default LLM agent

Option B: Manual Setup

cd mrvn
uv run python manage.py migrate
uv run python manage.py createsuperuser

7. Run Development Server

uv run python manage.py runserver

Access the admin at: http://127.0.0.1:8000/admin/

LLM Provider Configuration

Anthropic (Claude)

Get API key from https://console.anthropic.com/
In Django Admin, create an Agent with:
- Provider: anthropic
- Model: claude-sonnet-4-20250514 (or other Claude model)
- Add credentials with your API key

Google Gemini

Get API key from https://aistudio.google.com/
In Django Admin, create an Agent with:
- Provider: gemini
- Model: gemini-2.0-flash
- Add credentials with your API key

Ollama (Local)

Install Ollama: https://ollama.ai/download

curl -fsSL https://ollama.ai/install.sh | sh
ollama pull llama3.2

In Django Admin, create an Agent with:
- Provider: ollama
- Model: llama3.2
- Base URL: http://localhost:11434
- No credentials needed

vLLM (Local)

Install and run vLLM:

pip install vllm
vllm serve meta-llama/Llama-3.2-8B --port 8000

In Django Admin, create an Agent with:
- Provider: vllm
- Model: meta-llama/Llama-3.2-8B
- Base URL: http://localhost:8000/v1

Channel Configuration

Telegram

Option A: Using the Setup Command (Recommended)

cd mrvn
uv run python manage.py setup_telegram --owner <your-username>

The command will guide you through:

Entering your bot token from @BotFather
Configuring webhook or polling mode
Validating the bot connection

Option B: Manual Setup via Django Admin

Create a bot via @BotFather
In Django Admin, create a Channel with type telegram
Add credentials with your bot token

Running the Telegram Bot

# Development (foreground)
uv run python manage.py run_telegram

# Production (via systemd)
sudo systemctl start marvin-telegram

Slack

Option A: Using the Setup Command (Recommended)

cd mrvn
uv run python manage.py setup_slack --owner <your-username>

The command will guide you through:

Entering your bot token (xoxb-...)
Entering your signing secret
Optionally configuring Socket Mode with app token (xapp-...)

Option B: Manual Setup via Django Admin

Create a Slack App at https://api.slack.com/apps
Enable Socket Mode and get tokens
In Django Admin, create a Channel with type slack
Add credentials with bot token and signing secret

Running the Slack Bot

# Development (foreground, requires Socket Mode)
uv run python manage.py run_slack

# Production (via systemd)
sudo systemctl start marvin-slack

Required Slack Permissions

When configuring your Slack App, add these bot scopes:

chat:write - Send messages
app_mentions:read - Respond to @mentions
im:history - Read direct messages
im:read - Access direct message channels

Management Commands

Command	Description
`onboard`	Interactive setup wizard for initial configuration
`setup_telegram`	Configure a Telegram bot channel
`setup_slack`	Configure a Slack bot channel
`run_telegram`	Run the Telegram bot daemon
`run_slack`	Run the Slack bot daemon

Examples:

cd mrvn

# Initial setup
uv run python manage.py onboard

# Setup channels
uv run python manage.py setup_telegram --owner admin
uv run python manage.py setup_slack --owner admin

# Run bots (development)
uv run python manage.py run_telegram
uv run python manage.py run_slack

# Non-interactive mode (for automation/CI)
uv run python manage.py onboard --non-interactive
uv run python manage.py setup_telegram --owner admin --bot-token "123:ABC" --non-interactive

Development

Add New Packages

uv add <package-name>

Run Linters

uv run poe check

Run Type Checker

uv run pyright

Run Tests

uv run poe test

Docker Setup (Alternative)

# Start PostgreSQL with Docker Compose
docker-compose up -d

# Run migrations
cd mrvn && uv run python manage.py migrate

Production Deployment

System Requirements

Ubuntu 20.04+ or Debian 11+
Python 3.14+
PostgreSQL 14+
systemd (for service management)

Quick Install

# Clone repository and run install script
git clone https://github.com/monkut/marvin-manager.git
cd marvin-manager
sudo bash deploy/install.sh

Manual Installation

1. Create System User

sudo useradd --system --home-dir /opt/marvin --shell /bin/bash marvin
sudo mkdir -p /opt/marvin /var/log/marvin
sudo chown -R marvin:marvin /opt/marvin /var/log/marvin

2. Install Application

# Clone to /opt/marvin
sudo -u marvin git clone https://github.com/monkut/marvin-manager.git /opt/marvin

# Install dependencies
cd /opt/marvin
sudo -u marvin uv sync

3. Configure Environment

# Copy environment template
sudo cp /opt/marvin/deploy/marvin.env.example /opt/marvin/.env
sudo chmod 600 /opt/marvin/.env
sudo chown marvin:marvin /opt/marvin/.env

# Edit with your settings
sudo nano /opt/marvin/.env

Key settings to configure:

SECRET_KEY - Generate with: python -c "import secrets; print(secrets.token_urlsafe(50))"
DB_PASS - Your PostgreSQL password
ALLOWED_HOSTS - Your domain name(s)

4. Initialize Database

cd /opt/marvin/mrvn
sudo -u marvin uv run python manage.py onboard --non-interactive

5. Install Systemd Services

# Copy service files
sudo cp /opt/marvin/deploy/marvin-web.service /etc/systemd/system/
sudo cp /opt/marvin/deploy/marvin-telegram.service /etc/systemd/system/
sudo cp /opt/marvin/deploy/marvin-slack.service /etc/systemd/system/

# Reload systemd
sudo systemctl daemon-reload

6. Start Services

# Enable and start web server
sudo systemctl enable --now marvin-web

# (Optional) Enable Telegram bot
sudo systemctl enable --now marvin-telegram

# (Optional) Enable Slack bot
sudo systemctl enable --now marvin-slack

Nginx Reverse Proxy (Recommended)

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location /static/ {
        alias /opt/marvin/mrvn/static/;
    }
}

Service Management

# View status
sudo systemctl status marvin-web
sudo systemctl status marvin-telegram
sudo systemctl status marvin-slack

# View logs
sudo journalctl -u marvin-web -f
sudo journalctl -u marvin-telegram -f
sudo journalctl -u marvin-slack -f

# Restart services
sudo systemctl restart marvin-web
sudo systemctl restart marvin-telegram
sudo systemctl restart marvin-slack

Updating

cd /opt/marvin
sudo -u marvin git pull
sudo -u marvin uv sync
cd mrvn && sudo -u marvin uv run python manage.py migrate
sudo systemctl restart marvin-web marvin-telegram marvin-slack

Project Structure

marvin-manager/
├── mrvn/                   # Django application
│   ├── mrvn/               # Django project settings
│   ├── accounts/           # User authentication
│   ├── agents/             # LLM agent configuration
│   ├── channels/           # Messaging integrations (Telegram, Slack)
│   ├── memory/             # Conversation storage and sessions
│   ├── autoreply/          # Response routing and rules
│   └── commons/            # Shared utilities and rate limiting
├── deploy/                 # Production deployment files
│   ├── marvin-web.service  # Systemd service for web server
│   ├── marvin-telegram.service
│   ├── marvin-slack.service
│   ├── marvin.env.example  # Environment template
│   └── install.sh          # Installation script
├── docker-compose.yaml     # PostgreSQL for development
└── pyproject.toml          # Project dependencies

Environment Variables Reference

Variable	Default	Description
`DB_NAME`	`mrvn`	PostgreSQL database name
`DB_USER`	`postgres`	PostgreSQL username
`DB_PASS`	`mysecretpassword`	PostgreSQL password
`DB_HOST`	`127.0.0.1`	PostgreSQL host
`DB_PORT`	`5432`	PostgreSQL port
`DEBUG`	`False`	Django debug mode
`SECRET_KEY`	(generated)	Django secret key
`RATE_LIMIT_ENABLED`	`True`	Enable rate limiting
`RATE_LIMIT_DEFAULT_RPM`	`60`	Default requests per minute

License

See LICENSE file.

Name		Name	Last commit message	Last commit date
Latest commit History 9 Commits
.circleci		.circleci
.github/workflows		.github/workflows
.idea		.idea
data		data
deploy		deploy
mrvn		mrvn
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
LICENSE		LICENSE
README.md		README.md
docker-compose.yaml		docker-compose.yaml
pyproject.toml		pyproject.toml
uv.lock		uv.lock

Folders and files

Latest commit

History

Repository files navigation

Marvin Manager

Quick Start

Features

Requirements

Ubuntu/Linux Setup

1. Install System Dependencies

2. Install Python 3.14

3. Clone and Setup Project

4. Configure PostgreSQL

5. Environment Configuration

6. Initialize the Application

7. Run Development Server

LLM Provider Configuration

Anthropic (Claude)

Google Gemini

Ollama (Local)

vLLM (Local)

Channel Configuration

Telegram

Slack

Required Slack Permissions

Management Commands

Development

Add New Packages

Run Linters

Run Type Checker

Run Tests

Docker Setup (Alternative)

Production Deployment

System Requirements

Quick Install

Manual Installation

1. Create System User

2. Install Application

3. Configure Environment

4. Initialize Database

5. Install Systemd Services

6. Start Services

Nginx Reverse Proxy (Recommended)

Service Management

Updating

Project Structure

Environment Variables Reference

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages