Hardware Management

The primitive hardware command group provides comprehensive tools for registering, managing, and monitoring your hardware devices on the Primitive platform.

Registration

primitive hardware register [--organization <org-slug>]

Register a new hardware device with the Primitive platform.

# Register with default organization
primitive hardware register

# Register with specific organization
primitive hardware register --organization my-org-slug

Registration Process:

1. Collects system information and hardware specifications
2. Generates a unique hardware identifier
3. Creates a device profile on the Primitive platform
4. Establishes secure communication channels
5. Configures the device for job execution and monitoring

primitive hardware unregister

Unregister a hardware device from the platform.

primitive hardware unregister

Unregistration Process:

1. Stops any running jobs or agents
2. Removes device from organization
3. Cleans up local configuration
4. Revokes device credentials
5. Removes device from platform

Device Information

primitive hardware list

List all registered hardware devices you have access to.

primitive hardware list

Displays information about each device including:

• Device name and identifier
• Organization assignment
• Current status (online/offline)
• Hardware specifications
• Last check-in time

primitive hardware get <identifier>

Get detailed information about a specific hardware device.

primitive hardware get my-device-slug
primitive hardware get device-id-123

Shows comprehensive device information:

• Hardware specifications
• Current resource usage
• Job execution history
• Performance metrics
• Configuration details

primitive hardware systeminfo

Display detailed system information for the current device.

primitive hardware systeminfo

Provides comprehensive system details:

• Operating system and version
• CPU specifications and capabilities
• Memory configuration and usage
• Storage devices and capacity
• Network interfaces and connectivity
• Hardware sensors and status

Device Status

primitive hardware checkin

Manually check in your hardware device to report current status.

primitive hardware checkin

Check-in Process:

1. Collects current system metrics
2. Reports device health and status
3. Updates resource availability
4. Synchronizes configuration changes
5. Receives platform messages and updates

Check-ins normally happen automatically when running the agent or monitor, but manual check-ins can be useful for:

• Verifying connectivity
• Updating device status after changes
• Troubleshooting communication issues
• Forcing configuration synchronization

Hardware Specifications

When you register hardware, the platform automatically detects and records:

CPU Information

• Processor model and architecture
• Core count and thread count
• Clock speeds and capabilities
• Instruction set support
• Cache sizes and hierarchy

Memory Configuration

• Total installed memory
• Memory type and speed
• Available memory
• Memory usage patterns

Storage Systems

• Storage devices and types (SSD, HDD, NVMe)
• Total and available capacity
• I/O performance characteristics
• File system information

Network Capabilities

• Network interfaces and speeds
• Connectivity status
• Bandwidth measurements
• Network protocol support

Operating System

• OS type and version
• Kernel information
• System libraries and runtimes
• Environment configuration

Organization Management

Hardware devices are associated with organizations for access control and resource management.

Default Organization

When registering without specifying an organization, the device is added to your default organization.

Specific Organization

Use the --organization flag to register with a specific organization:

primitive hardware register --organization engineering-team

Changing Organizations

To move a device to a different organization:

1. Unregister from current organization
2. Re-register with new organization

primitive hardware unregister
primitive hardware register --organization new-org-slug

Monitoring and Health

Continuous Monitoring

When running the monitor daemon, the platform continuously tracks:

• Resource utilization trends
• Performance metrics
• Hardware health indicators
• Environmental conditions
• Error rates and alerts

Health Checks

Regular health checks monitor:

• System responsiveness
• Resource availability
• Hardware sensor readings
• Network connectivity
• Service status

Alerts and Notifications

The platform can alert you to:

• Hardware failures or degradation
• Resource exhaustion
• Performance anomalies
• Connectivity issues
• Security events

Troubleshooting

Registration Issues

Authentication Errors:

# Verify CLI configuration
primitive whoami

# Reconfigure if needed
primitive config

Organization Not Found:

# List available organizations
primitive organizations list

# Use correct organization slug
primitive hardware register --organization correct-slug

Network Connectivity:

# Test basic connectivity
primitive whoami

# Check system info collection
primitive hardware systeminfo

# Try with debug output
primitive --debug hardware register

Device Communication Issues

Device Offline:

# Force check-in
primitive hardware checkin

# Check network connectivity
ping api.primitive.tech

# Verify authentication
primitive whoami

Outdated Information:

# Manual check-in to update status
primitive hardware checkin

# Restart monitoring services
primitive daemons stop monitor
primitive daemons start monitor

Performance Issues

Resource Detection Problems:

# Check system information collection
primitive hardware systeminfo

# Verify monitor is running
primitive daemons list

# Check monitor logs
primitive daemons logs monitor

Slow Response:

# Check network connectivity
primitive hardware checkin

# Monitor system resources
primitive hardware systeminfo

# Check for system issues
primitive daemons logs agent

Best Practices

1. Unique Naming: Use descriptive, unique names for your hardware devices
2. Proper Organization: Register devices with appropriate organizations
3. Regular Check-ins: Ensure devices check in regularly (automatic with daemons)
4. Monitor Health: Watch for hardware health alerts and warnings
5. Keep Updated: Maintain current system software and drivers
6. Security: Protect device credentials and access
7. Documentation: Document hardware configurations and changes

Security Considerations

• Device registration creates unique cryptographic identities
• Communication with platform uses encrypted protocols
• Device credentials are stored securely on local system
• Access control is enforced through organization membership
• Regular credential rotation maintains security
• Audit logs track all device activities

Example Workflows

Initial Hardware Setup

# 1. Configure CLI
primitive config

# 2. Verify authentication
primitive whoami

# 3. Check system information
primitive hardware systeminfo

# 4. Register hardware
primitive hardware register --organization my-team

# 5. Verify registration
primitive hardware list

# 6. Set up monitoring
primitive daemons install

Device Maintenance

# Check device status
primitive hardware checkin

# View device information
primitive hardware get my-device

# Monitor system resources
primitive hardware systeminfo

# Check daemon health
primitive daemons list

Organization Migration

# 1. List current devices
primitive hardware list

# 2. Note current organization
primitive hardware get my-device

# 3. Unregister from current org
primitive hardware unregister

# 4. Register with new organization
primitive hardware register --organization new-team

# 5. Verify new registration
primitive hardware list

Troubleshooting Workflow

# 1. Check authentication
primitive whoami

# 2. Verify device registration
primitive hardware list

# 3. Force status update
primitive hardware checkin

# 4. Check system information
primitive hardware systeminfo

# 5. Review daemon status
primitive daemons list

# 6. Check logs if needed
primitive --debug hardware checkin