Agent & Monitor

The Primitive agent and monitor work together to provide continuous job execution and system monitoring capabilities. The agent polls for and executes jobs from the Primitive platform, while the monitor tracks system resources and performance metrics.

Agent

The agent is responsible for pulling jobs from the Primitive platform and executing them on your hardware.

primitive agent [--job-run-id <job-run-id>]

Run the Primitive agent to execute jobs.

# Run agent to continuously poll for and execute jobs
primitive agent

# Execute a specific job run
primitive agent --job-run-id abc123def456

Agent Functionality

Continuous Operation:

• Polls the Primitive platform for available jobs
• Downloads job artifacts and dependencies
• Executes jobs in isolated environments
• Reports job status and results back to the platform
• Handles job queuing and scheduling

Job Execution:

• Supports various job types (compilation, testing, analysis, etc.)
• Manages job dependencies and artifacts
• Provides isolated execution environments
• Captures and reports job outputs and logs
• Handles job timeouts and error conditions

Resource Management:

• Monitors available system resources
• Queues jobs when resources are constrained
• Manages concurrent job execution
• Cleans up after job completion

Monitor

The monitor continuously tracks system resources and reports metrics to the Primitive platform.

primitive monitor

Run the Primitive monitor to track system performance.

# Run monitor to continuously track system metrics
primitive monitor

Monitor Functionality

System Metrics:

• CPU usage and load averages
• Memory utilization and availability
• Disk space and I/O statistics
• Network connectivity and throughput
• Temperature and thermal status (where available)

Hardware Information:

• Processor specifications and capabilities
• Memory configuration and speeds
• Storage devices and capacity
• Network interfaces and configurations
• Connected peripherals and devices

Performance Tracking:

• Real-time resource utilization
• Historical performance trends
• Resource availability forecasting
• Performance anomaly detection

Running as Background Services

Both agent and monitor are typically run as background daemons for continuous operation. See the Daemons documentation for detailed setup instructions.

Quick Daemon Setup

# Install both agent and monitor as background services
primitive daemons install

# Start the services
primitive daemons start

# Check service status
primitive daemons list

# View agent logs
primitive daemons logs agent

# View monitor logs
primitive daemons logs monitor

Agent & Monitor Integration

The agent and monitor work together to provide optimal job execution:

Resource-Aware Scheduling:

• Monitor provides real-time resource availability
• Agent schedules jobs based on resource constraints
• Jobs are queued when resources are insufficient
• Dynamic scheduling adapts to changing system conditions

Performance Optimization:

• Monitor tracks job performance impact
• Agent adjusts execution strategies based on performance data
• Resource usage is optimized across concurrent jobs
• System health is maintained during heavy workloads

Health Monitoring:

• Monitor detects system health issues
• Agent pauses job execution during critical conditions
• Automatic recovery when conditions improve
• Alerts and notifications for persistent issues

Configuration

Both agent and monitor inherit configuration from your CLI setup:

Authentication

# Configure credentials (applies to both agent and monitor)
primitive config

# Verify authentication
primitive whoami

Host Configuration

# Configure for production (default)
primitive config

# Configure for local development
primitive --host localhost:8000 config --transport http

Debug Mode

# Run with debug logging
primitive --debug agent
primitive --debug monitor

# Install daemons with debug mode
primitive --debug daemons install

Job Execution Workflow

1. Job Discovery: Agent polls platform for available jobs
2. Resource Check: Monitor verifies sufficient resources available
3. Job Preparation: Agent downloads job artifacts and dependencies
4. Execution: Job runs in isolated environment with resource monitoring
5. Monitoring: Monitor tracks resource usage during execution
6. Completion: Agent reports results and cleans up resources
7. Metrics: Monitor reports final resource usage statistics

Monitoring and Logging

Real-Time Monitoring

# View agent activity in real-time
primitive daemons logs agent

# View monitor metrics in real-time
primitive daemons logs monitor

# Check daemon status
primitive daemons list

Log Files

Agent Logs Include:

• Job discovery and polling activity
• Job download and preparation status
• Execution progress and output
• Error conditions and recovery attempts
• Resource allocation and cleanup

Monitor Logs Include:

• System resource measurements
• Hardware status updates
• Performance metrics
• Health check results
• Alert conditions and notifications

Troubleshooting

Agent Issues

No Jobs Executing:

# Check agent status
primitive daemons list

# Verify authentication
primitive whoami

# Check agent logs for errors
primitive daemons logs agent

# Manually test agent
primitive agent

Job Execution Failures:

# Check system resources
primitive hardware systeminfo

# View detailed logs
primitive --debug daemons logs agent

# Check for specific job run
primitive agent --job-run-id <job-run-id>

Monitor Issues

Missing Metrics:

# Check monitor status
primitive daemons list

# Restart monitor service
primitive daemons stop monitor
primitive daemons start monitor

# Check monitor logs
primitive daemons logs monitor

Resource Detection Problems:

# Run monitor manually with debug
primitive --debug monitor

# Check hardware information
primitive hardware systeminfo

# Verify system permissions

Performance Issues

High Resource Usage:

# Check current system status
primitive hardware systeminfo

# View resource trends in monitor logs
primitive daemons logs monitor

# Adjust job concurrency if needed

Slow Job Execution:

# Monitor resource availability
primitive daemons logs monitor

# Check for resource constraints
primitive hardware systeminfo

# Review agent job scheduling
primitive daemons logs agent

Best Practices

1. Run as Daemons: Install agent and monitor as background services for continuous operation
2. Monitor Resources: Regularly check system resources to ensure adequate capacity
3. Check Logs: Monitor logs for errors, warnings, and performance issues
4. Resource Planning: Ensure sufficient CPU, memory, and storage for job execution
5. Network Connectivity: Maintain stable internet connection for job polling and metrics reporting
6. System Maintenance: Keep system updated and perform regular maintenance
7. Security: Ensure proper authentication and secure credential storage

Security Considerations

• Agent and monitor run with user privileges, not system/root
• Job execution is isolated to prevent system compromise
• Credentials are stored securely and encrypted
• Network communications use secure protocols
• Job artifacts are validated before execution
• System access is limited to necessary resources only

Example Workflows

Development Setup

# 1. Configure for local development
primitive --host localhost:8000 config --transport http

# 2. Verify connectivity
primitive whoami

# 3. Test agent manually
primitive agent

# 4. Test monitor manually
primitive monitor

# 5. Install as daemons for continuous operation
primitive daemons install

Production Deployment

# 1. Configure for production
primitive config

# 2. Verify authentication
primitive whoami

# 3. Register hardware
primitive hardware register

# 4. Install and start daemons
primitive daemons install
primitive daemons start

# 5. Verify operation
primitive daemons list
primitive daemons logs agent
primitive daemons logs monitor

Performance Monitoring

# Check system resources
primitive hardware systeminfo

# Monitor real-time activity
primitive daemons logs monitor

# Check agent job execution
primitive daemons logs agent

# List daemon status
primitive daemons list