Machines API

// Retrieve all machines connected to your account
const machines = await client.machines.list();

// Filter machines by status, tags, and search term
const machines = await client.machines.list({
  status: 'online',           // Only online machines
  tags: ['production'],       // Must have 'production' tag
  search: 'web-server',      // Match name or hostname
});

// Fetch a single machine by its unique ID
const machine = await client.machines.get('machine-id');

// Shape of the machine object returned by get() and list()
interface Machine {
  id: string;                                      // Unique machine identifier
  name: string;                                    // User-assigned display name
  status: 'online' | 'offline' | 'connecting';    // Current connection state
  os: string;                                      // Operating system (e.g. "linux")
  arch: string;                                    // CPU architecture (e.g. "amd64")
  hostname: string;                                // System hostname
  ip: string;                                      // Network IP address
  tags: string[];                                  // User-defined tags for filtering
  createdAt: Date;                                 // When the machine was registered
  lastSeen: Date;                                  // Last heartbeat timestamp
}

// Get real-time resource usage and agent info
const status = await client.machines.status('machine-id');

// Detailed machine health and resource metrics
interface MachineStatus {
  connected: boolean;           // Whether the agent is currently connected
  uptime: number;               // System uptime in seconds
  lastPing: Date;               // Timestamp of the last heartbeat
  agentVersion: string;         // Installed agent version
  cpu: {
    usage: number;              // CPU usage percentage (0-100)
    cores: number;              // Number of CPU cores
  };
  memory: {
    total: number;              // Total memory in bytes
    used: number;               // Used memory in bytes
    free: number;               // Free memory in bytes
  };
  disk: {
    total: number;              // Total disk space in bytes
    used: number;               // Used disk space in bytes
    free: number;               // Free disk space in bytes
  };
}

// Update display name and tags for a machine
await client.machines.update('machine-id', {
  name: 'New Name',
  tags: ['production', 'web'],
});

// Permanently remove a machine from your account
await client.machines.delete('machine-id');

// Disconnect a machine without removing it (can reconnect later)
await client.machines.disconnect('machine-id');

// Create a real-time event subscription for a specific machine
const subscription = client.machines.subscribe('machine-id');
 
// Listen for status changes (online/offline/connecting)
subscription.on('status', (status) => {
  console.log('Status:', status);
});
 
// Listen for resource metrics updates (CPU, memory, disk)
subscription.on('metrics', (metrics) => {
  console.log('CPU:', metrics.cpu.usage);
});
 
// Cleanup: stop receiving events when done
subscription.unsubscribe();

// Fetch multiple machines in a single request
const machines = await client.machines.getMany([
  'machine-1',
  'machine-2',
]);
 
// Apply the same tag update to multiple machines at once
await client.machines.updateMany(
  ['machine-1', 'machine-2'],
  { tags: ['batch-updated'] }
);

// List all defined machine groups
const groups = await client.machines.groups.list();
 
// Get machines belonging to a specific group
const machines = await client.machines.list({
  group: 'production',
});