Machineuse

Distributed container management for browser automation at scale — Create, schedule, and manage isolated browser instances across multiple nodes with intelligent load balancing and snapshot-based dormancy.

---

Features

• Distributed Architecture — Horizontally scalable across multiple worker nodes
• Pure NNG Messaging — High-performance communication without external brokers
• Intelligent Scheduling — Automatic placement based on node capabilities and load
• Container Isolation — SystemD-nspawn containers with dedicated resources
• Real-time Metrics — Comprehensive monitoring with time-series analytics
• Snapshot Dormancy — Resource-efficient pause/resume with filesystem snapshots
• Auto-healing — Automatic failure detection and instance migration
• Flexible Storage — SQLite for nodes, PostgreSQL option for control plane

Quick Start

Using Docker (Recommended)

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

# Start with Docker Compose
docker-compose up -d

# Check health
curl http://localhost:8000/health

Manual Installation

# Clone and setup
git clone https://github.com/dotcommoners/machineuse.git
cd machineuse/machineuse-api
poetry install

# Start single-node deployment
python -m machineuse.nodes.agent worker-1 --control-plane

# Create your first instance
machineuse-cli create --image ubuntu:22.04

Distributed Deployment

# Start control plane
python -m machineuse.nodes.control_plane --bind tcp://*:5000

# Start worker nodes (on different machines)
python -m machineuse.nodes.agent worker-1 tcp://control-plane:5000
python -m machineuse.nodes.agent worker-2 tcp://control-plane:5000

# Or use Docker Compose for distributed mode
docker-compose -f docker-compose.distributed.yml up -d

Usage

Python Library

from machineuse.client import ClusterManager

# Connect to distributed cluster
client = ClusterManager("tcp://control-plane:5000")

# Create instance with scheduling
instance = client.create_instance(
    image="ubuntu:22.04",
    config={"memory_gb": 4, "cpu_cores": 2}
)
print(f"Instance {instance.id} scheduled on {instance.node_id}")

# Monitor cluster
status = client.get_cluster_status()
print(f"Cluster utilization: {status['utilization']}%")

CLI

# Instance management
machineuse-cli create --image ubuntu:22.04    # Create instance
machineuse-cli list --node worker-1           # List instances
machineuse-cli delete <id>                    # Delete instance
machineuse-cli dormant <id>                   # Make dormant
machineuse-cli revive <id>                    # Revive instance

# Cluster management
machineuse-cli nodes list                     # List all nodes
machineuse-cli cluster status                 # Cluster overview
machineuse-cli metrics --node worker-1        # Node metrics

REST API

# Health check
curl http://localhost:8000/health

# Create instance
curl -X POST http://localhost:8000/v2/instances \
  -H "Content-Type: application/json" \
  -d '{"image": "ubuntu:22.04", "config": {"memory_gb": 2}}'

# List instances
curl http://localhost:8000/v2/instances

Docker Deployment

Single Node

docker-compose up -d

Services:

• machineuse-api — FastAPI server on port 8000
• postgres — PostgreSQL database (optional)

Distributed Mode

docker-compose -f docker-compose.distributed.yml up -d

Services:

• control-plane — Central coordinator
• worker-1, worker-2 — Container execution nodes
• postgres — Shared metadata storage

Environment Variables

Variable	Description	Default
MACHINEUSE_CONFIG	Config file path	/etc/machineuse/config.json
MACHINEUSE_LOG_LEVEL	Log level	INFO
MACHINEUSE_DB_URL	PostgreSQL URL	-
MACHINEUSE_MAX_INSTANCES	Max containers per node	50

Documentation

Full documentation: docs.dotcommoners.com/machineuse

• Installation Guide — Setup instructions
• Quick Start — Get running in 5 minutes
• API Reference — REST API documentation
• CLI Reference — Command-line usage
• Architecture — System design
• Deployment — Production deployment

Requirements

Core Dependencies

• Ubuntu/Debian system with systemd-nspawn support
• Python 3.11+ and Poetry
• Root/sudo access for container management

For Distributed Deployment

• Multiple Linux nodes with network connectivity
• NNG library (pip install pynng)
• PostgreSQL for control plane metadata (optional)
• DuckDB for analytics (auto-installed)

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

# Setup development environment
cd machineuse-api
poetry install --with dev

# Run tests
poetry run pytest --cov=machineuse

# Format and lint
poetry run black machineuse/ tests/
poetry run flake8 machineuse/ tests/

License

MIT License — see LICENSE for details.

---

GitHub • Documentation • Issues