🚀 NoxRunner - Python Client for Sandbox Execution Backends

NoxRunner is a Python client library for interacting with NoxRunner-compatible sandbox execution backends. It uses only Python standard library - zero external dependencies.

📖 About This Project

NoxRunner is the client library extracted from Agentsmith, a commercial distributed, high-concurrency AI-Agent development and operating platform. In the commercial Agentsmith platform, sandboxes run on enterprise private cloud clusters with comprehensive security policies, operational standards, automated container management, image building, resource allocation, and content auditing capabilities. These enterprise features are not part of this open-source release.

What's Open Source:

• ✅ Client Library: This Python client library for interacting with NoxRunner backends
• ✅ Backend Specification: The complete API specification (see SPECS.md)
• ✅ Local Sandbox Mode: A local device simulation mode for development, testing, and POC demos

Use Cases:

• 🧪 Development & Testing: Use the local sandbox mode to develop and test AI agents without the overhead of managing a full cluster
• 🚀 Production Deployment: When ready to deploy publicly, switch to a real NoxRunner backend cluster for production workloads
• 🔧 Mock Backend: Perfect for building simple AI agents that need a sandbox execution environment during development

This approach significantly reduces operational and debugging burden during the development phase while maintaining compatibility with production-grade sandbox infrastructure.

✨ Features

• ✅ Zero Dependencies: Only uses Python standard library
• ✅ Complete API Coverage: All NoxRunner backend endpoints
• ✅ Shell Command Interface: Natural shell command execution with exec_shell() method
• ✅ Environment Variable Support: Full support for environment variable expansion in shell commands
• ✅ Friendly CLI: Colored output, interactive shell
• ✅ Local Testing Mode: Offline testing with local sandbox backend
• ✅ Easy to Use: Simple API with clear error messages
• ✅ Well Documented: Comprehensive documentation and examples
• ✅ Type Hints: Full type support for better IDE experience

📦 Installation

Install from Source

# Clone the repository
git clone https://github.com/noxrunner/noxrunner.git
cd noxrunner

# Install in development mode
pip install -e .

# Or install with development dependencies
pip install -e ".[dev]"

Install from PyPI (when published)

pip install noxrunner

🚀 Quick Start

As a Library

from noxrunner import NoxRunnerClient

# Create client (local test mode for development)
client = NoxRunnerClient(local_test=True)

# Or connect to remote backend
# client = NoxRunnerClient("http://127.0.0.1:8080")

# Create sandbox
session_id = "my-session"
result = client.create_sandbox(session_id)
print(f"Sandbox: {result['podName']}")

# Wait for sandbox ready
client.wait_for_pod_ready(session_id)

# Execute command (array format)
result = client.exec(session_id, ["python3", "--version"])
print(result["stdout"])

# Execute shell command (string format - more natural!)
result = client.exec_shell(session_id, "python3 --version")
print(result["stdout"])

# Shell commands with environment variables
result = client.exec_shell(
    session_id,
    "echo $MY_VAR && ls -la",
    env={"MY_VAR": "test_value"}
)
print(result["stdout"])

# Upload files
client.upload_files(session_id, {
    "script.py": "print('Hello from NoxRunner!')"
})

# Download files as tar archive
tar_data = client.download_files(session_id)

# Download and extract to local directory (recommended)
import tempfile
from pathlib import Path

with tempfile.TemporaryDirectory() as tmpdir:
    client.download_workspace(session_id, tmpdir)
    # Files are now in tmpdir

# Delete sandbox
client.delete_sandbox(session_id)

As a CLI Tool

Remote Mode (Default):

# Health check
noxrc health

# Create sandbox
noxrc create my-session --wait

# Execute command
noxrc exec my-session python3 --version

# Upload files
noxrc upload my-session script.py data.txt

# Download files
noxrc download my-session --extract ./output

# Interactive shell
noxrc shell my-session

# Delete sandbox
noxrc delete my-session

Local Testing Mode (for offline testing):

# Use --local-test flag for offline testing
noxrc --local-test create my-session
noxrc --local-test exec my-session echo "Hello"
noxrc --local-test upload my-session script.py
noxrc --local-test delete my-session

⚠️ Warning: Local testing mode executes commands in your local environment using /tmp directories. This can cause data loss or security risks!

📚 Documentation

• API Reference - Complete API documentation
• Backend Specification - Implement your own NoxRunner-compatible backend
• Examples - Usage examples
• Contributing - How to contribute

🏗️ Project Structure

noxrunner/
├── noxrunner/          # Python package
│   ├── __init__.py
│   ├── client.py       # NoxRunnerClient class
│   ├── exceptions.py   # Exception classes
│   ├── backend/        # Backend implementations
│   │   ├── base.py     # Abstract base class
│   │   ├── local.py    # LocalBackend
│   │   └── http.py     # HTTPSandboxBackend
│   ├── security/        # Security utilities
│   │   ├── command_validator.py
│   │   └── path_sanitizer.py
│   └── fileops/        # File operation utilities
│       └── tar_handler.py
├── tests/              # Test suite
│   ├── test_security.py
│   ├── test_fileops.py
│   ├── test_backend_local.py
│   ├── test_backend_http.py
│   └── test_integration.py
├── examples/           # Example scripts
├── docs/               # Sphinx documentation
└── README.md           # This file

🔌 Backend Compatibility

NoxRunner is designed to work with any backend that implements the NoxRunner Backend Specification. This includes:

• Kubernetes-based sandbox managers
• Docker-based execution backends
• VM-based sandbox systems
• Any custom implementation following the spec

🧪 Testing

# Run all unit tests
pytest tests/test_security.py tests/test_fileops.py tests/test_backend_local.py tests/test_backend_http.py

# Run local backend integration tests
pytest tests/test_integration.py::TestLocalBackendIntegration

# Run HTTP backend integration tests (requires running backend)
NOXRUNNER_ENABLE_INTEGRATION=1 NOXRUNNER_BASE_URL=http://127.0.0.1:8080 pytest tests/test_integration.py::TestHTTPSandboxBackendIntegration

# Run with coverage
pytest --cov=noxrunner --cov-report=html

# Run all tests
pytest tests/

Testing Modes

• Unit Tests: Test individual modules (security, fileops, backend mocks)
• Local Integration Tests: Test LocalBackend with real file operations
• HTTP Integration Tests: Test HTTPSandboxBackend against running backend service

See USAGE.md for more details on testing.

📝 License

MIT License - see LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

🔗 Links

• Repository: https://github.com/noxrunner/noxrunner
• Documentation: https://noxrunner.readthedocs.io
• Issues: https://github.com/noxrunner/noxrunner/issues

🙏 Acknowledgments

NoxRunner was originally developed as part of Agentsmith, a commercial distributed AI-Agent development and operating platform. The client library and backend specification have been extracted and open-sourced to enable broader adoption and community contribution. The local sandbox simulation mode was added to facilitate development, testing, and POC demonstrations without requiring access to production infrastructure.