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?

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

servos-1.0.5.tar.gz (50.0 kB view details)

Uploaded Sep 18, 2025 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

servos-1.0.5-py3-none-any.whl (47.0 kB view details)

Uploaded Sep 18, 2025 Python 3

File details

Details for the file servos-1.0.5.tar.gz.

File metadata

Download URL: servos-1.0.5.tar.gz
Upload date: Sep 18, 2025
Size: 50.0 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.12.0

File hashes

Hashes for servos-1.0.5.tar.gz
Algorithm	Hash digest
SHA256	`7445b23f6f7faa177d41b82f8dff1c3205c423c234e37b1855f097190fb7d9cc`
MD5	`a140120afe419e78a70f374af7ce32eb`
BLAKE2b-256	`8e97eb013d3d8ea8849bc6840b47410393329d6414e2562432779f2233c0b5fc`

See more details on using hashes here.

File details

Details for the file servos-1.0.5-py3-none-any.whl.

File metadata

Download URL: servos-1.0.5-py3-none-any.whl
Upload date: Sep 18, 2025
Size: 47.0 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.12.0

File hashes

Hashes for servos-1.0.5-py3-none-any.whl
Algorithm	Hash digest
SHA256	`640baae22c28de19d287e78619bd98b300e87ad721de70bade3f783d064bb8db`
MD5	`74388c9ffd6cad1bbca0ef48c18ff96a`
BLAKE2b-256	`32c47d58a5baa87917f41d97e9ce34ad805a7a467f1f8efd6625a1e7b636481e`

See more details on using hashes here.

Release history Release notifications | RSS feed

This release

1.0.5 This release

Sep 18, 2025 2 files

1.0.0

Sep 17, 2025 2 files

servos 1.0.5

Servos - Service Environment Isolation & Orchestration System

🎯 Overview

🏗️ Architecture

Servos Ecosystem Integration

Detailed Servos Architecture

✨ Features

🔧 Component Layers

🚀 Quick Start

Installation

Basic Usage

CLI Usage

🌍 Supported Platforms

📦 Package Structure

🔨 Development

Local Development

Building Containers

🧪 Testing

📚 API Reference

IsolationManager

PlatformDetector

🔗 Integration with ProServe

🤝 Contributing

📄 License

👨‍💻 Author

🙏 Acknowledgments

Documentation

Python Packages

Why Servos?

Project links

Key dates

1 maintainer

Credits

License

Requires

Provides Extra

Tags

Classifiers

Download files

Source Distribution

Built Distribution

File details

File metadata

File hashes

File details

File metadata

File hashes

Release history Release notifications | RSS feed