disco-sh

A Discord bot for system administration and Docker management, written in Go.

Features

• System Monitoring: Real-time system stats (CPU, Memory, Disk, Network)
• Docker Management: Raw Docker CLI command execution via Discord
• Shell Command Execution: Execute arbitrary shell commands (PowerShell on Windows)
• Permission System: User ID whitelist-based authorization
• Periodic Status Updates: Automatic system status reports to a Discord channel
• Smart Output Handling: Long outputs automatically sent as files with tail preview
• ANSI Code Stripping: Clean, readable output in Discord embeds
• MCP Server (Planned): Model Context Protocol integration for AI agents

Quick Start

Prerequisites

• Go 1.21 or higher
• Discord Bot Token (Create one here)
• Docker (if you want to manage containers)

Installation

1. Clone the repository:

git clone https://github.com/merith-tk/disco-sh.git
cd disco-sh

2. Install dependencies:

go mod download

3. Configure the bot:

cp configs/config.yaml configs/config.yaml
# Edit configs/config.yaml with your settings

4. Run the bot:

go run cmd/bot/main.go

Configuration

Edit configs/config.yaml:

discord:
  token: "YOUR_BOT_TOKEN"
  status_channel: "CHANNEL_ID_FOR_STATUS_UPDATES"

system:
  update_interval: 60  # Seconds between status updates

docker:
  host: ""  # Leave empty for default Docker socket

permissions:
  authorized_users: ["YOUR_USER_ID"]  # User IDs allowed to use the bot

Environment Variables

You can also configure via environment variables:

• DISCO_DISCORD_TOKEN
• DISCO_DISCORD_STATUS_CHANNEL
• DISCO_DOCKER_HOST

Commands

Status Commands

• /status - Get current system status
• /system info - Detailed system information
• /system resources - Current resource usage
• /system disk - Disk usage information

Docker Commands (Requires Authorization)

• /docker <command> - Execute any Docker command on the host
  • Examples:
    • /docker ps - List running containers
    • /docker ps -a - List all containers
    • /docker logs container_name - View container logs
    • /docker start container_name - Start a container
    • /docker stop container_name - Stop a container
    • /docker exec -it container_name bash - Execute commands in container

Shell Commands (Requires Authorization)

• /sh-c <command> - Execute arbitrary PowerShell commands on the host
  • Examples:
    • /sh-c Get-Process - List all processes
    • /sh-c Get-Service - List all services
    • /sh-c dir C:\ - List directory contents
    • /sh-c netstat -an - Show network connections

⚠️ Security Warning: Both docker and shell commands execute with the bot's privileges and have no restrictions. Only add trusted users to authorized_users.

Permissions

Access control is simple: Whitelist Only

Only users whose Discord User IDs are listed in authorized_users can use the bot. All authorized users have full access to all commands.

To get your Discord User ID:

1. Enable Developer Mode in Discord (User Settings → Advanced)
2. Right-click your username
3. Click "Copy User ID"

Development

Project Structure

disco-sh/
├── cmd/bot/          # Bot entry point
├── internal/
│   ├── bot/          # Discord bot logic
│   ├── core/         # Shared Docker/System operations
│   ├── config/       # Configuration management
│   └── permissions/  # RBAC system
├── configs/          # Config files
└── docs/             # Documentation

Building

go build -o disco-sh cmd/bot/main.go

Documentation

• Architecture
• Configuration Guide
• Security & Permissions
• MCP Integration
• Features Roadmap

License

MIT

Contributing

Contributions welcome! Please open an issue or PR.