Servos - Service Environment Isolation & Orchestration System

A lightweight Python library for environment isolation, Docker orchestration, and multi-platform service deployment. Extracted from the ProServe framework to provide focused environment isolation capabilities.

🚀 Part of the modular ecosystem: ProServe (core framework) • Servos (isolation) • EDPMT (hardware) • wmlog (logging)

🎯 Overview

Servos provides robust environment isolation and orchestration for running services across multiple platforms including Arduino, MicroPython, ARM64, and x86_64 architectures. It offers containerized execution environments with automatic platform detection and deployment.

🏗️ Architecture

Servos Ecosystem Integration

graph TB
    subgraph "Modular Ecosystem"
        ProServe[ProServe Framework<br/>Core Microservices]
        Servos[Servos<br/>Environment Isolation]
        EDPMT[EDPMT Framework<br/>Hardware Control]
        wmlog[wmlog<br/>Centralized Logging]
    end
    
    ProServe --> Servos
    EDPMT --> Servos
    Servos --> wmlog
    
    subgraph "Servos Core Architecture"
        IsolationManager[IsolationManager<br/>Process/Container Management]
        PlatformDetector[PlatformDetector<br/>Auto-Detection]
        EnvironmentConfig[EnvironmentConfig<br/>Resource Limits]
        ContainerOrchestrator[Container Orchestrator<br/>Docker Management]
    end
    
    Servos --> IsolationManager
    Servos --> PlatformDetector
    Servos --> EnvironmentConfig
    Servos --> ContainerOrchestrator
    
    subgraph "Platform Support"
        Arduino[Arduino<br/>AVR/ESP32/STM32]
        MicroPython[MicroPython<br/>ESP32/CircuitPython]
        ARM64[ARM64<br/>Raspberry Pi/M1]
        x86_64[x86_64<br/>Standard PC/Server]
    end
    
    PlatformDetector --> Arduino
    PlatformDetector --> MicroPython
    PlatformDetector --> ARM64
    PlatformDetector --> x86_64
    
    subgraph "Isolation Modes"
        ProcessIsolation[Process Isolation<br/>Native Execution]
        DockerIsolation[Docker Containers<br/>Full Isolation]
        ResourceLimits[Resource Limits<br/>CPU/Memory/Time]
        NetworkIsolation[Network Isolation<br/>Controlled Access]
    end
    
    IsolationManager --> ProcessIsolation
    IsolationManager --> DockerIsolation
    IsolationManager --> ResourceLimits
    IsolationManager --> NetworkIsolation
    
    subgraph "Docker Environments"
        ArduinoContainer[Arduino Container<br/>PlatformIO/Toolchain]
        MicroPyContainer[MicroPython Container<br/>Firmware/Tools]
        ARM64Container[ARM64 Container<br/>Cross-compilation]
        x86Container[x86_64 Container<br/>Standard Runtime]
    end
    
    DockerIsolation --> ArduinoContainer
    DockerIsolation --> MicroPyContainer
    DockerIsolation --> ARM64Container
    DockerIsolation --> x86Container

Detailed Servos Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                           Servos Architecture                              │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌─────────────────────────────────────────────────────────────────────┐     │
│  │                         CLI Interface                               │     │
│  │                                                                     │     │
│  │  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐  │     │
│  │  │   servos    │ │   servos    │ │   servos    │ │     servos      │  │     │
│  │  │   detect    │ │list-platforms│ │   version   │ │    <command>    │  │     │
│  │  │             │ │             │ │             │ │                 │  │     │
│  │  │• Auto-detect│ │• Show all   │ │• Version    │ │• Custom         │  │     │
│  │  │  current    │ │  supported  │ │  info       │ │  isolation      │  │     │
│  │  │  platform   │ │  platforms  │ │• Build      │ │  commands       │  │     │
│  │  │• Hardware   │ │• Docker     │ │  metadata   │ │• Interactive    │  │     │
│  │  │  details    │ │  images     │ │• CLI help   │ │  shell          │  │     │
│  │  │• System     │ │• Capabilities│ │             │ │                 │  │     │
│  │  │  info       │ │             │ │             │ │                 │  │     │
│  │  └─────────────┘ └─────────────┘ └─────────────┘ └─────────────────┘  │     │
│  └─────────────────────────────────────────────────────────────────────┘     │
│                                │                                             │
│                                ▼                                             │
│  ┌─────────────────────────────────────────────────────────────────────┐     │
│  │                      Core Isolation Engine                         │     │
│  │                                                                     │     │
│  │  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐  │     │
│  │  │ Isolation   │ │  Platform   │ │Environment  │ │   Container     │  │     │
│  │  │  Manager    │ │  Detector   │ │   Config    │ │  Orchestrator   │  │     │
│  │  │             │ │             │ │             │ │                 │  │     │
│  │  │• Process    │ │• Hardware   │ │• Resource   │ │• Docker API     │  │     │
│  │  │  Spawn      │ │  Detection  │ │  Limits     │ │• Image Build    │  │     │
│  │  │• Container  │ │• Arch Query │ │• CPU/Memory │ │• Container      │  │     │
│  │  │  Create     │ │• OS Info    │ │• Network    │ │  Lifecycle      │  │     │
│  │  │• Security   │ │• Feature    │ │  Rules      │ │• Volume Mount   │  │     │
│  │  │  Sandbox    │ │  Support    │ │• Time Limits│ │• Health Check   │  │     │
│  │  │• Resource   │ │• Embedded   │ │• User/Group │ │• Log Stream     │  │     │
│  │  │  Monitor    │ │  Board ID   │ │  Mapping    │ │• Network Setup  │  │     │
│  │  └─────────────┘ └─────────────┘ └─────────────┘ └─────────────────┘  │     │
│  └─────────────────────────────────────────────────────────────────────┘     │
│                                │                                             │
│                                ▼                                             │
│  ┌─────────────────────────────────────────────────────────────────────┐     │
│  │                    Platform-Specific Environments                  │     │
│  │                                                                     │     │
│  │  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐  │     │
│  │  │   Arduino   │ │MicroPython  │ │   ARM64     │ │     x86_64      │  │     │
│  │  │Environment  │ │ Environment │ │Environment  │ │   Environment   │  │     │
│  │  │             │ │             │ │             │ │                 │  │     │
│  │  │• PlatformIO │ │• MicroPython│ │• Cross-     │ │• Standard       │  │     │
│  │  │  Toolchain  │ │  Runtime    │ │  compilation│ │  Runtime        │  │     │
│  │  │• AVR-GCC    │ │• CircuitPy  │ │• QEMU       │ │• Python 3.8+   │  │     │
│  │  │• ESP-IDF    │ │  Support    │ │  Emulation  │ │• Build Tools    │  │     │
│  │  │• STM32Cube  │ │• Firmware   │ │• RPi Tools  │ │• Dev Libraries  │  │     │
│  │  │• Board      │ │  Upload     │ │• Native     │ │• Testing        │  │     │
│  │  │  Configs    │ │• Serial     │ │  Execution  │ │  Framework      │  │     │
│  │  │• Flash      │ │• Debug      │ │• Profiling  │ │• Debug Tools    │  │     │
│  │  │  Tools      │ │• Serial     │ │  Tools      │ │• Performance    │  │     │
│  │  └─────────────┘ └─────────────┘ └─────────────┘ └─────────────────┘  │     │
│  └─────────────────────────────────────────────────────────────────────┘     │
│                                │                                             │
│                                ▼                                             │
│  ┌─────────────────────────────────────────────────────────────────────┐     │
│  │                      Docker Integration                            │     │
│  │                                                                     │     │
│  │  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐  │     │
│  │  │  Arduino    │ │ MicroPython │ │   ARM64     │ │     x86_64      │  │     │
│  │  │ Container   │ │  Container  │ │  Container  │ │   Container     │  │     │
│  │  │             │ │             │ │             │ │                 │  │     │
│  │  │• Ubuntu     │ │• Python 3.x │ │• Multi-arch │ │• Ubuntu/Alpine  │  │     │
│  │  │  Base       │ │  Base       │ │  Support    │ │  Base           │  │     │
│  │  │• PlatformIO │ │• MicroPython│ │• Cross-comp │ │• Python 3.8+   │  │     │
│  │  │  Install    │ │  Tools      │ │  Toolchain  │ │• Development    │  │     │
│  │  │• Serial     │ │• esptool    │ │• QEMU User  │ │  Environment    │  │     │
│  │  │  Support    │ │• ampy       │ │  Mode       │ │• Build Utils    │  │     │
│  │  │• USB/GPIO   │ │• rshell     │ │• Native     │ │• Package        │  │     │
│  │  │  Access     │ │• mpremote   │ │  Runtime    │ │  Managers       │  │     │
│  │  │• Firmware   │ │• Firmware   │ │• Debug      │ │• Testing        │  │     │
│  │  │  Flash      │ │  Management │ │  Support    │ │  Frameworks     │  │     │
│  │  └─────────────┘ └─────────────┘ └─────────────┘ └─────────────────┘  │     │
│  └─────────────────────────────────────────────────────────────────────┘     │
│                                │                                             │
│                                ▼                                             │
│  ┌─────────────────────────────────────────────────────────────────────┐     │
│  │                        Integration Layer                           │     │
│  │                                                                     │     │
│  │  ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────────┐  │     │
│  │  │   wmlog     │ │  ProServe   │ │    EDPMT    │ │     Docker      │  │     │
│  │  │  Logging    │ │ Framework   │ │  Hardware   │ │     Engine      │  │     │
│  │  │             │ │             │ │ Management  │ │                 │  │     │
│  │  │• Structured │ │• Service    │ │• Device     │ │• Container      │  │     │
│  │  │  Logging    │ │  Framework  │ │  Control    │ │  Runtime        │  │     │
│  │  │• Real-time  │ │• Manifest   │ │• GPIO/I2C   │ │• Image          │  │     │
│  │  │  Stream     │ │  Driven     │ │• Sensor     │ │  Management     │  │     │
│  │  │• Context    │ │• Multi-env  │ │  Reading    │ │• Volume         │  │     │
│  │  │  Enrichment │ │  Deploy     │ │• Hardware   │ │  Management     │  │     │
│  │  │• WebSocket  │ │• Discovery  │ │  Testing    │ │• Network        │  │     │
│  │  │• MQTT       │ │• Migration  │ │• Firmware   │ │  Management     │  │     │
│  │  │• Console    │ │• Auto Scale │ │  Upload     │ │• Resource       │  │     │
│  │  │  Output     │ │• Load Bal.  │ │• Monitor    │ │  Monitoring     │  │     │
│  │  └─────────────┘ └─────────────┘ └─────────────┘ └─────────────────┘  │     │
│  └─────────────────────────────────────────────────────────────────────┘     │
└─────────────────────────────────────────────────────────────────────────────┘

✨ Features

🔧 Component Layers

graph TB
    CLI[CLI Interface] --> Core[Core Isolation]
    CLI --> Platform[Platform Detection]
    
    Core --> Docker[Docker Manager]
    Platform --> Docker
    
    Docker --> Arduino[Arduino Container]
    Docker --> MicroPython[MicroPython Container]  
    Docker --> ARM64[ARM64 Container]
    Docker --> x86[x86_64 Container]
    
    Arduino --> Hardware1[Arduino Hardware]
    MicroPython --> Hardware2[ESP32/CircuitPython]
    ARM64 --> Hardware3[Raspberry Pi/Apple M1]
    x86 --> Hardware4[Standard PC/Server]

🚀 Quick Start

Installation

# Basic installation
pip install servos

# With all optional dependencies
pip install servos[all]

# With Docker support
pip install servos[docker]

# For MicroPython development
pip install servos[micropython]

# For Arduino development  
pip install servos[arduino]

Basic Usage

from servos import IsolationManager, PlatformDetector

# Detect current platform
detector = PlatformDetector()
platform = detector.detect_platform()
print(f"Detected platform: {platform}")

# Create isolated environment
manager = IsolationManager(platform=platform)
result = manager.execute_isolated("my_script.py")

CLI Usage

# Detect current platform
servos detect

# Run script in isolated environment
servos isolate my_script.py

# List supported platforms
servos list-platforms

# Show version information
servos version

🌍 Supported Platforms

Platform	Description	Container	Use Cases
`arduino`	Arduino & compatible MCUs	✅	IoT, embedded systems
`micropython`	MicroPython environments	✅	ESP32, CircuitPython
`arm64`	ARM64 processors	✅	Raspberry Pi, Apple M1
`x86_64`	Standard x86_64	✅	PCs, servers
`rpi-arm`	Raspberry Pi ARM	✅	Pi-specific projects

📦 Package Structure

servos/
├── servos/
│   ├── __init__.py              # Main package interface
│   ├── cli.py                   # Command-line interface
│   ├── core/
│   │   ├── __init__.py
│   │   └── isolation.py         # Core isolation management
│   └── isolation/
│       ├── __init__.py
│       ├── extended_environments.py  # Extended isolation
│       └── platforms/           # Platform-specific code
├── docker/                      # Container definitions
│   ├── arduino/                 # Arduino container
│   ├── micropython/            # MicroPython container
│   ├── arm64/                  # ARM64 container
│   └── x86_64/                 # x86_64 container
├── tests/                      # Test suite
├── setup.py                    # Package configuration
├── requirements.txt            # Dependencies
├── Makefile                    # Build automation
└── README.md                   # This file

🔨 Development

Local Development

# Clone and setup
git clone https://github.com/servos/servos.git
cd servos

# Install in development mode
make install

# Run tests
make test

# Build package
make build

# Format code
make format

Building Containers

The Docker environments are automatically built when needed, but you can also build them manually:

# Build specific platform container
docker build -f docker/arduino/Dockerfile -t servos:arduino .
docker build -f docker/micropython/Dockerfile -t servos:micropython .
docker build -f docker/arm64/Dockerfile -t servos:arm64 .
docker build -f docker/x86_64/Dockerfile -t servos:x86_64 .

🧪 Testing

# Run all tests
make test

# Run specific test
python -m pytest tests/test_isolation.py

# Run with coverage
python -m pytest --cov=servos tests/

📚 API Reference

IsolationManager

Main class for managing environment isolation:

from servos import IsolationManager, EnvironmentConfig

config = EnvironmentConfig()
manager = IsolationManager(platform="arduino", config=config)
result = manager.execute_isolated("blink_led.py")

PlatformDetector

Automatic platform detection:

from servos.isolation.platforms import PlatformDetector

detector = PlatformDetector()
platform = detector.detect_platform()
architecture = detector.get_architecture()

🔗 Integration with ProServe

Servos is designed to work seamlessly with the ProServe framework:

# In your ProServe service manifest
dependencies:
  - servos>=1.0.0

# Use in ProServe services
from servos import IsolationManager
from proserve import Service

class MyService(Service):
    def __init__(self):
        self.isolation = IsolationManager()
    
    async def handle_request(self, request):
        result = self.isolation.execute_isolated("user_script.py")
        return {"status": "success", "result": result}

🤝 Contributing

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Commit changes: git commit -m 'Add amazing feature'
Push to branch: git push origin feature/amazing-feature
Open a Pull Request

📄 License

This project is licensed under the Apache Software License 2.0 - see the LICENSE file for details.

👨‍💻 Author

Tom Sapletta

🙏 Acknowledgments

Extracted from the ProServe framework
Built for the EDPMT (Electronic Device Programming & Management Tool) ecosystem
Inspired by modern containerization and microservices architectures

Servos - Making environment isolation simple and powerful! 🚀

Documentation

API Documentation - Detailed reference for Servos APIs
Quick Start - Getting started with environment isolation

Python Packages

Explore the ecosystem of Python packages related to Servos:

ProServe - Core microservices framework
Servos - Environment isolation and orchestration
wmlog - Centralized structured logging
SELLM - AI-powered manifest generator
EDPMT - Hardware control framework for IoT

Why Servos?

Metadata

Release files for servos 1.0.5

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for servos 1.0.5
File	Size	Uploaded
servos-1.0.5.tar.gz	50.0 kB	Sep 18, 2025	Details

Built distribution (wheel)

Table of built distributions (wheels) for servos 1.0.5
File	Interpreter	ABI	Platform	Reset
servos-1.0.5-py3-none-any.whl 47.0 kB Sep 18, 2025	Python 3	none	any	Details

Total release size: 97.0 kB

Release files / servos-1.0.5.tar.gz

Download URL	servos-1.0.5.tar.gz
Size	50.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`7445b23f6f7faa177d41b82f8dff1c3205c423c234e37b1855f097190fb7d9cc`
BLAKE2b-256 checksum How to use checksums	`8e97eb013d3d8ea8849bc6840b47410393329d6414e2562432779f2233c0b5fc`
Upload date	Sep 18, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.12.0`

Release files / servos-1.0.5-py3-none-any.whl

Download URL	servos-1.0.5-py3-none-any.whl
Size	47.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`640baae22c28de19d287e78619bd98b300e87ad721de70bade3f783d064bb8db`
BLAKE2b-256 checksum How to use checksums	`32c47d58a5baa87917f41d97e9ce34ad805a7a467f1f8efd6625a1e7b636481e`
Upload date	Sep 18, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.2.0 CPython/3.12.0`

Release history Release notifications | RSS feed

This release

1.0.5 This release

Sep 18, 2025 2 release files

1.0.0

Sep 17, 2025 2 release files

servos 1.0.5