Skip to content

Quick Start Guide

Get Machineuse running in under 5 minutes.

Prerequisites

  • Docker and Docker Compose installed
  • curl for testing

Step 1: Start the Service

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

# Start with Docker Compose
docker-compose up -d

Step 2: Verify Health

curl http://localhost:8000/health

Expected response:

{
  "status": "healthy",
  "instances_count": 0,
  "running_instances": 0
}

Step 3: Create an Instance

Using curl:

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

Or using the CLI:

machineuse-cli create --image ubuntu:22.04

Response:

{
  "id": "abc123def456",
  "status": "creating",
  "subdomain": "a1b2c3d4",
  "debug_port": 9222,
  "stream_port": 5000
}

Step 4: List Instances

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

# Using CLI
machineuse-cli list

Step 5: Access Your Instance

Once the instance is running:

  • Browser Debug: http://localhost:9222
  • Video Stream: http://localhost:5000

Step 6: Delete Instance

# Using curl
curl -X DELETE http://localhost:8000/v2/instances/abc123def456

# Using CLI
machineuse-cli delete abc123def456

Using the Python Client

from machineuse.client import ClusterManager

# Connect to the API
client = ClusterManager("http://localhost:8000")

# Create an instance
instance = client.create_instance(
    image="ubuntu:22.04",
    config={"memory_gb": 2, "cpu_cores": 2}
)
print(f"Created: {instance.id}")

# List all instances
for inst in client.list_instances():
    print(f"{inst.id}: {inst.status}")

# Delete the instance
client.delete_instance(instance.id)

Common Operations

Make Instance Dormant

Save resources by making an idle instance dormant:

machineuse-cli dormant abc123def456

Revive Dormant Instance

Restore a dormant instance:

machineuse-cli revive abc123def456

View Metrics

machineuse-cli metrics --node worker-1

Next Steps