Machineuse Documentation¶

Distributed container management for browser automation at scale

Machineuse is a production-ready system for creating, scheduling, and managing isolated browser instances across multiple nodes. It provides intelligent load balancing, snapshot-based dormancy, and flexible deployment options.

Key Features¶

• Distributed Architecture — Scale horizontally 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 Links¶

Getting Started¶

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

Architecture Overview¶

┌─────────────────────────────────────────────────────────────┐
│                      Control Plane                          │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │  Scheduler  │  │  API Server │  │  Metadata   │         │
│  │             │  │             │  │  (Postgres) │         │
│  └─────────────┘  └─────────────┘  └─────────────┘         │
└─────────────────────────────────────────────────────────────┘
                           │ NNG
        ┌──────────────────┼──────────────────┐
        │                  │                  │
        ▼                  ▼                  ▼
┌───────────────┐  ┌───────────────┐  ┌───────────────┐
│   Worker 1    │  │   Worker 2    │  │   Worker N    │
│ ┌───────────┐ │  │ ┌───────────┐ │  │ ┌───────────┐ │
│ │ Container │ │  │ │ Container │ │  │ │ Container │ │
│ │ Container │ │  │ │ Container │ │  │ │ Container │ │
│ └───────────┘ │  │ └───────────┘ │  │ └───────────┘ │
└───────────────┘  └───────────────┘  └───────────────┘

Support¶

• GitHub Issues: Report bugs and request features
• Documentation: You're reading it!
• Contributing: See the Contributing Guide

License¶

Machineuse is released under the MIT License.