Managing Instances¶

This guide covers creating, managing, and monitoring browser instances.

Instance Lifecycle¶

Create → Active → Idle Detection → Dormant → Revival → Active
                      ↓
                   Delete

States¶

State	Description
`creating`	Instance is being provisioned
`running`	Instance is active and accessible
`idle`	No activity detected
`dormant`	Snapshotted and stopped to save resources
`reviving`	Being restored from dormant state
`failed`	Creation or operation failed
`stopped`	Instance has stopped

Creating Instances¶

Basic Creation¶

# CLI
machineuse-cli create --image ubuntu:22.04

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

With Configuration¶

# CLI
machineuse-cli create \
  --image ubuntu:22.04 \
  --memory 4 \
  --cpu 2 \
  --disk 20

# API
curl -X POST http://localhost:8000/v2/instances \
  -H "Content-Type: application/json" \
  -d '{
    "image": "ubuntu:22.04",
    "config": {
      "memory_gb": 4,
      "cpu_cores": 2,
      "disk_gb": 20,
      "idle_timeout_minutes": 30,
      "auto_snapshot": true
    }
  }'

With Node Preference¶

# Schedule on specific worker
machineuse-cli create --image ubuntu:22.04 --node-preference worker-2

Listing Instances¶

# All instances
machineuse-cli list

# On specific node
machineuse-cli list --node worker-1

# Filter by status
machineuse-cli list --status running

Example output:

ID               Status    Node      Memory    CPU    Created
───────────────────────────────────────────────────────────────
abc123def456     running   worker-1  2048 MB   2      2026-03-19 10:30
def456ghi789     dormant   worker-2  4096 MB   4      2026-03-19 09:15

Instance Details¶

# CLI
machineuse-cli info abc123def456

# API
curl http://localhost:8000/v2/instances/abc123def456

Response:

{
  "id": "abc123def456",
  "status": "running",
  "node_id": "worker-1",
  "subdomain": "a1b2c3d4",
  "debug_port": 9222,
  "stream_port": 5000,
  "created_at": "2026-03-19T10:30:00Z",
  "resources": {
    "cpu_percent": 15.2,
    "memory_mb": 512,
    "disk_mb": 1024
  },
  "urls": {
    "debug": "http://a1b2c3d4.example.com/debug/",
    "stream": "http://a1b2c3d4.example.com/stream"
  }
}

Dormancy Management¶

Make Instance Dormant¶

Snapshot and stop an instance to save resources:

# CLI
machineuse-cli dormant abc123def456

# API
curl -X POST http://localhost:8000/v2/instances/abc123def456/dormant

Revive Dormant Instance¶

Restore an instance from its snapshot:

# CLI
machineuse-cli revive abc123def456

# API
curl -X POST http://localhost:8000/v2/instances/abc123def456/revive

Revival options:

{
  "method": "quick_start",  // or "full_restore"
  "priority": "high"
}

Deleting Instances¶

# CLI
machineuse-cli delete abc123def456

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

# Force delete (skips graceful shutdown)
machineuse-cli delete abc123def456 --force

Accessing Instances¶

Once running, instances are accessible via:

Browser Debug Interface¶

Connect to Chrome DevTools:

http://{subdomain}.example.com/debug/

Or directly via port:

http://localhost:{debug_port}

Video Stream¶

View browser screen:

http://{subdomain}.example.com/stream

Programmatic Access¶

from machineuse.client import ClusterManager

client = ClusterManager("http://localhost:8000")
instance = client.get_instance("abc123def456")

# Connect to browser
from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.connect_over_cdp(
        f"http://localhost:{instance.debug_port}"
    )
    page = browser.new_page()
    page.goto("https://example.com")

Resource Monitoring¶

Instance Metrics¶

machineuse-cli metrics abc123def456

Output:

Instance: abc123def456
Status: running
Uptime: 2h 15m

Resources:
  CPU: 15.2%
  Memory: 512 MB / 2048 MB (25%)
  Disk: 1.2 GB / 10 GB (12%)
  Network: 1.5 MB/s in, 0.8 MB/s out

Activity:
  Last Activity: 2 minutes ago
  Idle Time: 2 minutes
  Idle Threshold: 30 minutes

Bulk Operations¶

# Stop all instances on a node
machineuse-cli bulk dormant --node worker-1

# Delete all failed instances
machineuse-cli bulk delete --status failed