docs/USAGE_GUIDE.md

# Ubuntu Sandbox Environment - Deployment Guide

## Quick Start

### 1. Create a New HuggingFace Space
1. Go to [huggingface.co/spaces](https://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
```python
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
```javascript
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:

```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
```bash
# Check system resources
system_info

# Check running processes  
ps aux

# Check disk usage
df -h

# Check memory usage
free -h
```

### View Logs
```bash
# Application logs
tail -f /home/user/workspace/logs/sandbox.log

# System logs
journalctl -f
```

### Maintenance Tasks
```bash
# 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
```yaml
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
```python
# 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
```bash
# 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](https://discuss.huggingface.co)
- **Documentation**: [huggingface.co/docs/spaces](https://huggingface.co/docs/spaces)
- **GitHub**: [github.com/huggingface/gradio](https://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.