docs/USAGE_GUIDE.md

Ubuntu Sandbox Environment - Deployment Guide

Quick Start

1. Create a New HuggingFace Space

1. Go to huggingface.co/spaces
2. Click "Create new Space"
3. Choose Docker as the SDK
4. Name your space (e.g., ubuntu-sandbox)
5. Set license (e.g., MIT)
6. Choose hardware (CPU is sufficient, GPU optional)

2. Upload Files

Upload the following files to your new space:

📁 Your Space Repository
├── app.py              # Main application
├── requirements.txt    # Python dependencies  
├── Dockerfile          # Container configuration
├── config.yaml         # Environment settings
├── README.md          # Documentation
└── USAGE_GUIDE.md     # This file

3. Deploy

1. After uploading, HuggingFace will automatically build your space
2. The build process takes 5-10 minutes
3. Once built, your space will be available at: https://your-username-ubuntu-sandbox.hf.space

Configuration

Environment Variables

You can set these environment variables in your space settings:

Variable	Default	Description
INSTALL_TOOLS	true	Install additional development tools
MAX_OUTPUT_LINES	1000	Maximum lines in terminal output
COMMAND_TIMEOUT	30	Timeout for command execution (seconds)
AI_FRIENDLY_MODE	true	Enable AI-specific features

Hardware Requirements

• Minimum: 2GB RAM, 1 CPU core
• Recommended: 4GB RAM, 2 CPU cores
• For GPU work: Add GPU hardware

Usage Examples

For AI Models

import requests

# Base URL of your HuggingFace Space
BASE_URL = "https://your-username-ubuntu-sandbox.hf.space"

# Execute a command
response = requests.post(
    f"{BASE_URL}/api/execute",
    json={"command": "python3 -c 'print(\"Hello from AI!\")'"}
)
print(response.json())

# Create a file
requests.post(
    f"{BASE_URL}/api/create",
    json={
        "filename": "ai_project.py",
        "content": "print('AI created this!')"
    }
)

# Run the created file
result = requests.post(
    f"{BASE_URL}/api/execute", 
    json={"command": "python3 ai_project.py"}
)
print(result.json())

For JavaScript/Node.js

const BASE_URL = "https://your-username-ubuntu-sandbox.hf.space";

// Execute command
fetch(`${BASE_URL}/api/execute`, {
    method: 'POST',
    headers: {'Content-Type': 'application/json'},
    body: JSON.stringify({command: 'node --version'})
})
.then(response => response.json())
.then(data => console.log(data));

// Create Node.js app
fetch(`${BASE_URL}/api/create`, {
    method: 'POST', 
    headers: {'Content-Type': 'application/json'},
    body: JSON.stringify({
        filename: 'app.js',
        content: 'console.log("AI is coding!");'
    })
});

Advanced Configuration

Custom Dockerfile

If you need additional system packages, modify the Dockerfile:

# Add to your Dockerfile after the existing apt-get install
RUN apt-get update && apt-get install -y \
    your-custom-package \
    another-package \
    && apt-get clean \
    && rm -rf /var/lib/apt/lists/*

Custom Python Packages

Add to requirements.txt:

your-custom-package==1.0.0
another-dependency==2.0.0

Environment Variables

Set in your space's Settings > Variables tab:

INSTALL_TOOLS=true
AI_FRIENDLY_MODE=true
COMMAND_TIMEOUT=60

Troubleshooting

Build Issues

• Package installation fails: Check if packages exist in Ubuntu 22.04 repos
• Memory errors: Increase hardware or reduce package count
• Build timeout: Split into smaller Docker layers

Runtime Issues

• Commands fail: Check if packages are installed in Dockerfile
• API not responding: Verify app.py is correct and dependencies installed
• Permission errors: Ensure proper file permissions in Dockerfile

Performance Issues

• Slow response: Check hardware configuration
• Memory usage: Monitor with htop command
• Disk space: Clean up temporary files

Security Considerations

What's Protected

• Container isolation: Your space is isolated from other spaces
• Resource limits: Prevents resource exhaustion
• No root access: Commands run as non-root user
• Timeout protection: Long-running commands are terminated

Best Practices

• Monitor usage: Check logs regularly
• Clean up: Remove temporary files
• Backup important work: Files may be cleaned up
• Don't store sensitive data: This is a public environment

Monitoring and Maintenance

Check System Health

# Check system resources
system_info

# Check running processes  
ps aux

# Check disk usage
df -h

# Check memory usage
free -h

View Logs

# Application logs
tail -f /home/user/workspace/logs/sandbox.log

# System logs
journalctl -f

Maintenance Tasks

# Clean temporary files
rm -rf /home/user/workspace/temp/*

# Check for old sessions
ps aux | grep bash

# Update package cache
apt update

Integration Examples

GitHub Actions Integration

name: Test in Ubuntu Sandbox
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - name: Test in Sandbox
      run: |
        curl -X POST "https://your-space.hf.space/api/execute" \
             -H "Content-Type: application/json" \
             -d '{"command": "python3 -m pytest tests/"}'

CI/CD Pipeline

# Example CI/CD integration
def deploy_to_sandbox():
    # Build and test
    requests.post("/api/execute", 
                  json={"command": "python3 setup.py test"})
    
    # Create Docker image
    requests.post("/api/execute",
                  json={"command": "docker build -t myapp ."})
    
    # Deploy
    requests.post("/api/execute", 
                  json={"command": "docker run -d -p 80:80 myapp"})

Support and Resources

Getting Help

• Space Issues: Check HuggingFace Space logs
• Technical Questions: Review the README.md documentation
• Feature Requests: Submit through space repository

Useful Commands

# Environment information
python3 /home/user/workspace/environment_info.py

# Install additional tools
/home/user/workspace/install_tools.sh

# Check system status
system_info

Community

• HuggingFace Forum: discuss.huggingface.co
• Documentation: huggingface.co/docs/spaces
• GitHub: github.com/huggingface/gradio

---

Ready to deploy your Ubuntu Sandbox Environment! 🚀

This guide should help you get your AI-accessible development environment up and running quickly. For specific issues, check the troubleshooting section or refer to the main README.md documentation.