slop.unturf.com/slop-terminal

SLOP Terminal Server

A comprehensive SLOP (Streamlined Language Operations Protocol) server implementation with AI model integration, sandboxed code execution, and gaming capabilities.

Features

🤖 AI Integration

• Multi-Model Support: Dynamic discovery of OpenAI-compatible endpoints (vLLM, Ollama, etc.)
• Tool Calling: AI can automatically invoke tools to assist with tasks
• Chat Interface: Full conversation support with context management

🛡️ Security & Sandboxing

• Firecracker Sandboxes: Secure microVM-based code execution
• User Isolation: Per-user sandbox environments with persistent state
• Permission Controls: Configurable security policies and access controls

🔧 Terminal Tools

• File Operations: Read, write, and manage files safely
• Code Execution: Python and shell command execution in sandboxes
• System Information: Access to system stats and environment details
• Directory Management: Navigate and explore filesystem

🎮 Gaming Features

• Casino Games: Slots and Blackjack with persistent wallets
• Agent Support: Multi-agent gaming with individual statistics
• Persistent State: Game history and balances stored across sessions

💾 Data Management

• Memory System: Key-value storage with query capabilities
• Resource Management: Hierarchical resource storage and retrieval
• Persistent Storage: File-based data persistence with locking

Quick Start

Prerequisites

• Linux/WSL2 (Ubuntu 18.04+ recommended)
• Python 3.8+
• KVM support (for Firecracker sandboxes)
• Root/sudo access (for initial setup)

Installation

1. Clone the repository:

   git clone <repository-url>
   cd slop-terminal
   

2. Run the setup:

   make setup
   

   This will automatically:

   • Install system dependencies
   • Download and configure Firecracker
   • Set up KVM permissions
   • Install Python packages
   • Configure environment variables

3. Test the installation:

   ./Scripts/test_firecracker.sh  # Auto-generated by setup
   

4. Start the server:

   make run
   

Configuration

Environment Variables

The server supports extensive configuration through environment variables. Copy the template and customize:

cp config/.env.example .env
nano .env

Model Endpoints

export MODEL_ENDPOINT_0="https://your-model-endpoint.com/v1"
export MODEL_API_KEY_0="your-api-key-or-not-needed"
# Add more endpoints with incrementing numbers

Server Settings

export SLOP_PORT="31337"                    # Server port
export SLOP_DATA_DIR="./data"               # Data directory
export SLOP_LOG_LEVEL="INFO"                # Logging level
export FLASK_DEBUG="true"                   # Debug mode

Security Settings

export ENABLE_FIRECRACKER="true"            # Enable sandbox
export ALLOW_DANGEROUS_TOOLS="false"        # Allow unsafe tools
export REQUIRE_USER_ID="true"               # Require user identification
export DEFAULT_TIMEOUT="60"                 # Default execution timeout

Firecracker Settings

export FIRECRACKER_KERNEL="./firecracker/kernel/vmlinux.bin"
export FIRECRACKER_ROOTFS="./firecracker/rootfs/rootfs.ext4"
export FIRECRACKER_MEMORY="512"             # Memory in MB
export FIRECRACKER_VCPU="1"                 # Virtual CPU count

API Endpoints

Chat & AI

• POST /chat - Chat with AI models with tool calling support
• GET /models - List available AI models

Tools

• GET /tools - List all available tools
• GET /tools/{tool_id} - Get tool details
• POST /tools/{tool_id} - Execute a specific tool

Memory Management

• GET /memory - List all memory keys
• GET /memory/{key} - Retrieve memory value
• POST /memory - Store key-value pair
• DELETE /memory/{key} - Delete memory key
• POST /memory/query - Query memory with filters

Resource Management

• GET /resources - List all resources
• GET /resources/{resource_id} - Get specific resource
• POST /resources - Create new resource
• PUT /resources/{resource_id} - Update resource
• DELETE /resources/{resource_id} - Delete resource
• GET /resources/search - Search resources

Gaming

• POST /tools/slots - Play slot machine
• POST /tools/blackjack - Play blackjack

System

• GET /info - Server information and capabilities
• POST /pay - Mock payment processing

Available Tools

Terminal Tools

• sandbox_python - Execute Python code in secure sandbox
• sandbox_exec - Execute shell commands in secure sandbox
• file_read - Read file contents safely
• directory_list - List directory contents
• sysinfo - Get system information
• pwd - Get current directory
• sandbox_manage - Manage sandbox instances

Utility Tools

• calculator - Basic math calculations
• greet - Simple greeting tool

Gaming Tools

• slots - Slot machine game
• blackjack - Blackjack card game

Security Features

Firecracker Sandboxes

• Isolated Execution: Each user gets their own microVM
• Resource Limits: Configurable CPU and memory limits
• Network Isolation: No network access from sandboxes
• Persistent Environments: Python virtual environments persist across calls

Access Controls

• User Identification: Optional user ID requirement
• Tool Restrictions: Dangerous tools only available in sandboxes
• Timeout Controls: Configurable execution timeouts
• Permission Levels: Different access levels for different tools

Usage Examples

Chat with AI

curl -X POST http://localhost:31337/chat \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "Calculate 15 * 23"}],
    "model": "your-model-name",
    "enable_tool_calling": true,
    "user_id": "user123"
  }'

Execute Python Code

curl -X POST http://localhost:31337/tools/sandbox_python \
  -H "Content-Type: application/json" \
  -d '{
    "code": "print(\"Hello, World!\")",
    "user_id": "user123",
    "packages": ["requests", "numpy"]
  }'

Store and Retrieve Memory

# Store
curl -X POST http://localhost:31337/memory \
  -H "Content-Type: application/json" \
  -d '{"key": "user_pref", "value": "dark_mode"}'

# Retrieve
curl http://localhost:31337/memory/user_pref

Play Casino Games

curl -X POST http://localhost:31337/tools/slots \
  -H "Content-Type: application/json" \
  -d '{"bet": 10, "agent_id": "player1"}'

Development

Available Make Commands

make help          # Show all available commands
make setup         # Run vars.sh setup
make install       # Install Python dependencies
make run           # Start the server (python3 slop_with_terminal.py)
make test          # Run tests
make clean         # Clean up generated files
make docker-build  # Build Docker image
make docker-run    # Run with Docker Compose

Project Structure

slop-terminal/
├── slop_with_terminal.py  # Main Flask server
├── vars.sh                # Setup and configuration script
├── README.md              # This file
├── requirements.txt       # Python dependencies
├── Makefile              # Build automation
├── Dockerfile            # Container configuration
├── docker-compose.yml    # Docker setup
├── .gitlab-ci.yml        # CI/CD pipeline
├── .gitignore            # Git ignore rules
├── config/               # Configuration files
│   └── .env.example      # Environment template
├── docs/                 # Documentation
├── tests/                # Test files
├── static/               # Static files
├── Scripts/              # Generated scripts (auto-generated by vars.sh)
│   ├── set_env.sh        # Environment setup
│   ├── test_firecracker.sh # Test script
│   └── start_firecracker.sh # Firecracker wrapper
├── data/                 # Data directory
│   ├── memory.json       # Memory storage
│   ├── resources.json    # Resource storage
│   ├── terminal/         # Terminal data
│   └── slop_monolith.log # Server logs
├── firecracker/          # Firecracker components
│   ├── kernel/           # Kernel images
│   └── rootfs/           # Root filesystems
├── downloads/            # Downloaded files
└── bin/                  # Binary files

Adding New Tools

1. Create a class inheriting from TerminalTool
2. Implement required methods: tool_id, description, arguments, execute
3. Register the tool in initialize_terminal_tools()

Adding New Models

Simply add new environment variables:

export MODEL_ENDPOINT_X="https://your-endpoint.com/v1"
export MODEL_API_KEY_X="your-key"

Troubleshooting

Common Issues

KVM Permission Errors:

# Fix KVM permissions
sudo usermod -a -G kvm $USER
# Restart terminal or re-login

Firecracker Not Working:

# Test Firecracker setup
./Scripts/test_firecracker.sh    # Auto-generated by setup

# Check KVM availability
ls -la /dev/kvm

Model Connection Issues:

# Test endpoint manually
curl https://your-endpoint.com/v1/models

Memory/Resource Lock Timeouts:

• Check disk space in data directory
• Ensure proper file permissions
• Restart server if persistent

Debug Mode

Enable detailed logging:

# Edit .env file
SLOP_LOG_LEVEL=DEBUG
FLASK_DEBUG=true

# Then start server
make run
# or directly: python3 slop_with_terminal.py

Performance Tuning

Firecracker Settings

Edit your .env file:

FIRECRACKER_MEMORY=1024  # Increase memory
FIRECRACKER_VCPU=2       # More CPU cores

Timeout Settings

Edit your .env file:

DEFAULT_TIMEOUT=120      # Longer timeouts

License

This project is released under the Public Domain. See the original SLOP specification for more details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Support

For issues and questions:

• Check the troubleshooting section
• Review server logs in data/slop_monolith.log
• Test with ./Scripts/test_firecracker.sh (auto-generated by setup)
• Use make help to see all available commands
• Verify endpoints with curl

Related Projects

• SLOP Specification
• Original SLOP Examples

Quick Start Summary

# Clone and navigate to project
git clone <repository-url>
cd slop-terminal

# Setup environment
cp config/.env.example .env
make setup

# Start server
make run

# Test
curl http://localhost:31337/info

---

Built with ❤️ for the SLOP community