Projects & Jobs

The Primitive platform organizes work into projects and jobs. Projects are containers for related work, while jobs are individual execution units that run on your hardware.

Projects

Projects provide organization and context for your computational work on the Primitive platform.

primitive projects list

List all projects you have access to within your organization.

primitive projects list

Project Information Includes:

• Project name and identifier
• Description and metadata
• Organization ownership
• Creation and modification dates
• Access permissions
• Associated jobs and resources

Project Structure

Projects typically contain:

• Job Definitions: Templates and configurations for computational tasks
• Resources: Files, datasets, and dependencies
• Results: Output files and execution artifacts
• Configuration: Environment settings and parameters
• Documentation: Project descriptions and usage guides

Project Access

Project access is controlled through:

• Organization Membership: Must be member of project's organization
• Role-Based Permissions: Different access levels (read, write, admin)
• Project Sharing: Explicit sharing with users or groups

Jobs

Jobs are individual execution units that run computational tasks on registered hardware.

primitive jobs list

List all jobs in your organization.

primitive jobs list

Job Information Includes:

• Job name and identifier
• Current status (pending, running, completed, failed)
• Associated project
• Target hardware requirements
• Execution timestamps
• Resource usage
• Output and results

primitive jobs details <job-slug>

Get detailed information about a specific job.

primitive jobs details my-job-slug
primitive jobs details job-abc123

Detailed Job Information:

• Complete job configuration
• Execution history and logs
• Resource requirements and usage
• Input files and dependencies
• Output artifacts and results
• Error information (if failed)
• Performance metrics

Job Lifecycle

Job States

Jobs progress through several states:

1. Created: Job defined but not yet scheduled
2. Pending: Waiting for available hardware resources
3. Running: Currently executing on hardware
4. Completed: Successfully finished execution
5. Failed: Execution failed with errors
6. Cancelled: Manually cancelled before completion
7. Timeout: Exceeded maximum execution time

Job Execution

Jobs are executed by the Primitive agent running on your hardware:

1. Job Discovery: Agent polls for available jobs
2. Resource Matching: Platform matches jobs to suitable hardware
3. Job Download: Agent downloads job artifacts and dependencies
4. Execution: Job runs in isolated environment
5. Result Upload: Agent uploads results and logs
6. Cleanup: Temporary resources are cleaned up

Job Requirements

Jobs can specify requirements for:

• Hardware Specifications: CPU, memory, storage requirements
• Operating System: Linux, macOS, Windows
• Software Dependencies: Required libraries and tools
• Network Access: Internet connectivity needs
• Execution Time: Expected duration and timeouts
• Resource Limits: Maximum CPU, memory, disk usage

Job Management

Job Scheduling

The platform automatically schedules jobs based on:

• Hardware availability and capabilities
• Job priority and queue position
• Resource requirements and constraints
• Organization policies and limits

Job Monitoring

Monitor job execution through:

• Real-time Status: Current job state and progress
• Execution Logs: Detailed output from job execution
• Resource Usage: CPU, memory, disk, network metrics
• Performance Data: Execution time, throughput, efficiency

Job Results

Job results include:

• Output Files: Generated artifacts and data
• Execution Logs: Complete stdout/stderr output
• Metrics: Performance and resource usage data
• Status Information: Success/failure indicators
• Error Details: Diagnostic information for failures

Working with Projects and Jobs

Project Workflow

# 1. List available projects
primitive projects list

# 2. View project details (through web interface)
# 3. Configure jobs for the project
# 4. Monitor job execution
primitive jobs list

# 5. View job results
primitive jobs details my-job-slug

Job Monitoring Workflow

# 1. List current jobs
primitive jobs list

# 2. Check specific job status
primitive jobs details active-job

# 3. Monitor agent execution
primitive daemons logs agent

# 4. View system resources
primitive hardware systeminfo

Integration with Other Commands

Hardware Integration

• Jobs require registered hardware for execution
• Hardware capabilities determine job compatibility
• Resource monitoring ensures optimal job placement

# Ensure hardware is registered and healthy
primitive hardware list
primitive hardware checkin

Agent Integration

• Agent automatically discovers and executes jobs
• Monitor job execution through agent logs
• Control job execution via daemon management

# Ensure agent is running
primitive daemons list
primitive daemons logs agent

File Integration

• Jobs can use uploaded files as inputs
• Job results are stored as platform files
• File organization supports project structure

# Upload input files for jobs
primitive files upload --key-prefix "project-data/" ./input.csv

# Results are accessible through file commands
primitive files list

Troubleshooting

No Jobs Available

Check Agent Status:

# Verify agent is running
primitive daemons list

# Check agent logs for issues
primitive daemons logs agent

# Restart agent if needed
primitive daemons stop agent
primitive daemons start agent

Verify Hardware Registration:

# Ensure hardware is registered
primitive hardware list

# Check hardware status
primitive hardware checkin

# Verify organization membership
primitive organizations list

Job Execution Issues

Resource Problems:

# Check available resources
primitive hardware systeminfo

# Monitor resource usage
primitive daemons logs monitor

# Review job requirements vs. available resources
primitive jobs details problematic-job

Permission Issues:

# Verify project access
primitive projects list

# Check organization membership
primitive organizations list

# Ensure proper authentication
primitive whoami

Performance Issues

Slow Job Execution:

# Check system resources
primitive hardware systeminfo

# Monitor current jobs
primitive jobs list

# Review agent logs for bottlenecks
primitive daemons logs agent

Job Queue Delays:

# Check job queue status
primitive jobs list

# Verify hardware availability
primitive hardware list

# Monitor agent job discovery
primitive daemons logs agent

Best Practices

1. Organize Projects: Use clear, descriptive project names and organization
2. Monitor Jobs: Regularly check job status and execution logs
3. Resource Planning: Ensure adequate hardware resources for job requirements
4. Error Handling: Review failed jobs and address underlying issues
5. Performance Optimization: Monitor resource usage and optimize job configurations
6. Documentation: Maintain clear documentation for projects and job workflows

Example Workflows

Project Development Cycle

# 1. List available projects
primitive projects list

# 2. Upload project files
primitive files upload --key-prefix "project-alpha/src/" ./source/

# 3. Monitor job execution
primitive jobs list

# 4. Check job details
primitive jobs details build-job-123

# 5. Review execution logs
primitive daemons logs agent

# 6. Download results (through file operations)

Job Monitoring and Debugging

# 1. Check current job status
primitive jobs list

# 2. Get detailed job information
primitive jobs details failing-job

# 3. Check hardware resources
primitive hardware systeminfo

# 4. Monitor agent logs
primitive daemons logs agent

# 5. Review system health
primitive hardware checkin

# 6. Restart services if needed
primitive daemons stop
primitive daemons start

Performance Monitoring

# 1. List active jobs
primitive jobs list

# 2. Monitor system resources
primitive hardware systeminfo

# 3. Check agent performance
primitive daemons logs agent

# 4. Monitor system metrics
primitive daemons logs monitor

# 5. Review job efficiency
primitive jobs details completed-job