Skip to content

Configuration Reference

Machineuse can be configured via JSON configuration files and environment variables.

Configuration File Locations

Configuration files are checked in the following order:

  1. --config CLI argument
  2. /etc/machineuse/config.json
  3. config.json in current directory
  4. Environment variables with MACHINEUSE_* prefix

Environment Variables

Variable Description Default
MACHINEUSE_CONFIG Path to config file -
MACHINEUSE_DATA_DIR Data directory /var/lib/machineuse
MACHINEUSE_LOG_LEVEL Log level (DEBUG, INFO, WARNING, ERROR) INFO
MACHINEUSE_NODE_ID Unique node identifier hostname
MACHINEUSE_DB_URL PostgreSQL connection URL -
MACHINEUSE_CONTROL_PLANE Control plane address (workers) -
MACHINEUSE_MAX_INSTANCES Max containers per node 50

Configuration File Structure

Single Node Configuration

{
  "deployment_mode": "single_node",
  "node_id": "single-node-1",
  "api": {
    "host": "0.0.0.0",
    "port": 8000,
    "cors_enabled": true,
    "cors_origins": ["*"]
  },
  "storage": {
    "backend": "sqlite",
    "database_path": "/var/lib/machineuse/machineuse.db"
  },
  "analytics": {
    "backend": "duckdb",
    "database_path": "/var/lib/machineuse/analytics.duckdb",
    "retention_days": 30
  },
  "containers": {
    "max_instances": 20,
    "default_memory_mb": 2048,
    "default_cpu_cores": 2,
    "default_disk_mb": 10240,
    "base_image_path": "/var/lib/machines/base-image"
  },
  "monitoring": {
    "metrics_interval_seconds": 30,
    "health_check_interval_seconds": 60,
    "cpu_warning_threshold": 80,
    "cpu_critical_threshold": 95,
    "memory_warning_threshold": 80,
    "memory_critical_threshold": 95
  }
}

Control Plane Configuration

{
  "deployment_mode": "control_plane",
  "node_id": "control-plane-1",
  "api": {
    "host": "0.0.0.0",
    "port": 8000
  },
  "storage": {
    "backend": "postgresql",
    "database_url": "postgresql://user:pass@localhost:5432/machineuse"
  },
  "messaging": {
    "bind_address": "tcp://0.0.0.0:5555",
    "heartbeat_interval_seconds": 10
  },
  "scheduling": {
    "algorithm": "weighted_score",
    "weights": {
      "cpu": 0.3,
      "memory": 0.4,
      "disk": 0.2,
      "network": 0.1
    },
    "rebalance_threshold": 0.3
  }
}

Worker Node Configuration

{
  "deployment_mode": "worker_node",
  "node_id": "worker-1",
  "api": {
    "host": "0.0.0.0",
    "port": 8001
  },
  "storage": {
    "backend": "sqlite",
    "database_path": "/var/lib/machineuse/worker.db"
  },
  "messaging": {
    "control_plane_address": "tcp://control-plane:5555"
  },
  "containers": {
    "max_instances": 50,
    "snapshot_compression": "gzip",
    "snapshot_path": "/var/lib/machineuse/snapshots"
  }
}

Deployment Modes

Single Node Mode

All-in-one deployment suitable for development and small deployments:

./scripts/start-single-node.sh

Features: - Combined control plane and worker - SQLite storage - Local container management

Control Plane Mode

Centralized coordinator for distributed deployments:

./scripts/start-control-plane.sh

Features: - Cluster management - PostgreSQL storage - Worker coordination via NNG

Worker Node Mode

Container execution node for distributed deployments:

./scripts/start-worker-node.sh

Features: - Container runtime - Local SQLite storage - Connects to control plane

Generating Configuration Templates

Use the CLI to generate configuration templates:

# Single node template
machineuse-cli config init single_node -o config.json

# Control plane template
machineuse-cli config init control_plane -o control-plane.json

# Worker node template
machineuse-cli config init worker_node -o worker-node.json

# Validate configuration
machineuse-cli config validate config.json

# Show current configuration
machineuse-cli config show

Resource Limits

Configure container resource limits:

{
  "containers": {
    "max_instances": 50,
    "default_memory_mb": 2048,
    "default_cpu_cores": 2,
    "default_disk_mb": 10240,
    "limits": {
      "max_memory_mb": 8192,
      "max_cpu_cores": 4,
      "max_disk_mb": 51200
    }
  }
}

Scheduling Weights

Configure how instances are scheduled across workers:

{
  "scheduling": {
    "weights": {
      "cpu": 0.3,
      "memory": 0.4,
      "disk": 0.2,
      "network": 0.1
    }
  }
}

Higher weights mean that resource is prioritized when selecting a worker node.

Security Configuration

Production Security

Default configuration has authentication disabled and CORS wide open. Configure these for production:

{
  "api": {
    "auth_enabled": true,
    "cors_enabled": true,
    "cors_origins": ["https://yourdomain.com"]
  }
}