Remote Execution

The primitive exec command enables you to execute commands on remote hardware devices registered with the Primitive platform. This provides secure, authenticated access to distributed computing resources.

Basic Usage

primitive exec <hardware-identifier> [command...]

Execute commands on remote hardware devices.

# Execute a simple command
primitive exec my-device-slug ls -la

# Run a Python script
primitive exec device-123 python /path/to/script.py

# Check system information
primitive exec my-hardware uname -a

# Execute multiple commands
primitive exec my-device "cd /tmp && ls -la && pwd"

Hardware Identification

You can identify target hardware using either:

Device Slug

Human-readable device identifier:

primitive exec my-laptop-ubuntu python --version
primitive exec build-server-001 make clean all

Device ID

Unique device identifier:

primitive exec device_abc123def456 ./run-tests.sh
primitive exec hw_789xyz123abc docker ps

Finding Device Identifiers

# List all available devices
primitive hardware list

# Get specific device information
primitive hardware get my-device-slug

Interactive Sessions

Starting Interactive Shell

When no command is specified, primitive exec starts an interactive shell session:

# Start interactive session
primitive exec my-device

# This opens a shell prompt on the remote device
user@remote-device:~$ pwd
/home/user
user@remote-device:~$ python --version
Python 3.9.7
user@remote-device:~$ exit

Interactive Features

• Full terminal emulation
• Command history and tab completion
• Environment variable access
• File system navigation
• Process management

Command Execution

Single Commands

# System information
primitive exec my-device "cat /proc/cpuinfo"

# Process monitoring
primitive exec my-device "top -n 1"

# File operations
primitive exec my-device "find /var/log -name '*.log' -mtime -1"

Script Execution

# Run local script on remote device
primitive exec my-device bash < ./local-script.sh

# Execute remote script
primitive exec my-device ./remote-script.sh

# Python script execution
primitive exec my-device python3 -c "print('Hello from remote!')"

Long-Running Commands

# Background processes
primitive exec my-device "nohup ./long-running-task.sh &"

# Process monitoring
primitive exec my-device "ps aux | grep my-process"

# Kill background processes
primitive exec my-device "pkill -f long-running-task"

Environment and Context

Working Directory

Commands execute in the user's home directory by default:

# Check current directory
primitive exec my-device pwd

# Change directory and execute
primitive exec my-device "cd /opt/myapp && ./start.sh"

Environment Variables

Remote sessions inherit the user's environment:

# Check environment
primitive exec my-device env

# Set variables for command
primitive exec my-device "export VAR=value && echo $VAR"

# Use existing environment
primitive exec my-device "echo $HOME"

User Context

Commands run as the user associated with the registered device:

# Check current user
primitive exec my-device whoami

# Check user permissions
primitive exec my-device id

# Access user files
primitive exec my-device "ls -la ~/Documents"

File Transfer and Management

While primitive exec is primarily for command execution, it can be used for basic file operations:

File Viewing

# View file contents
primitive exec my-device "cat /etc/hostname"

# Paginated viewing
primitive exec my-device "less /var/log/syslog"

# Search file contents
primitive exec my-device "grep -i error /var/log/application.log"

File Operations

# Create files
primitive exec my-device "echo 'Hello World' > /tmp/test.txt"

# Copy files
primitive exec my-device "cp /home/user/source.txt /tmp/dest.txt"

# Move files
primitive exec my-device "mv /tmp/old-name.txt /tmp/new-name.txt"

# Delete files
primitive exec my-device "rm /tmp/temporary-file.txt"

Directory Operations

# Create directories
primitive exec my-device "mkdir -p /tmp/new/directory"

# List directories
primitive exec my-device "find /home/user -type d -name 'project*'"

# Directory sizes
primitive exec my-device "du -sh /home/user/*"

Development and Debugging

Development Workflows

# Check out code
primitive exec my-device "git clone https://github.com/user/repo.git"

# Build projects
primitive exec my-device "cd /home/user/project && make"

# Run tests
primitive exec my-device "cd /home/user/project && npm test"

# Deploy applications
primitive exec my-device "cd /home/user/app && ./deploy.sh production"

Debugging and Monitoring

# Check system resources
primitive exec my-device "htop -n 1"

# Monitor logs
primitive exec my-device "tail -f /var/log/application.log"

# Network diagnostics
primitive exec my-device "netstat -tulpn"

# Disk usage
primitive exec my-device "df -h"

Package Management

# Ubuntu/Debian
primitive exec my-device "sudo apt update && sudo apt upgrade"

# CentOS/RHEL
primitive exec my-device "sudo yum update"

# macOS
primitive exec my-device "brew update && brew upgrade"

# Python packages
primitive exec my-device "pip install --user requests"

Security and Permissions

Authentication

• All remote execution requires valid authentication
• Commands run with the permissions of the registered user
• Device access is controlled through organization membership

Command Restrictions

• Some commands may be restricted based on device configuration
• Administrative commands may require elevated privileges
• Resource-intensive operations may be limited

Session Security

• All communication is encrypted in transit
• Sessions are authenticated and logged
• Commands are executed in isolated environments where possible

Error Handling

Connection Issues

# Device offline
Error: Device 'my-device' is not currently online

# Authentication failure
Error: Authentication failed for device 'my-device'

# Device not found
Error: Device 'invalid-device' not found

Command Failures

# Command not found
my-device: command 'invalid-command' not found

# Permission denied
my-device: permission denied: /root/restricted-file

# Resource limits
my-device: command terminated: resource limit exceeded

Troubleshooting

Device Connectivity

Device Not Responding:

# Check device status
primitive hardware list

# Verify device is online
primitive hardware get my-device

# Test basic connectivity
primitive exec my-device echo "test"

Authentication Issues:

# Verify CLI authentication
primitive whoami

# Check device registration
primitive hardware get my-device

# Reconfigure if needed
primitive config

Command Execution Issues

Permission Denied:

# Check user permissions
primitive exec my-device id

# Use sudo if available
primitive exec my-device "sudo command"

# Check file permissions
primitive exec my-device "ls -la /path/to/file"

Command Not Found:

# Check PATH
primitive exec my-device "echo $PATH"

# Find command location
primitive exec my-device "which command-name"

# Use full path
primitive exec my-device "/usr/bin/python3 script.py"

Performance Issues

Slow Response:

# Check device resources
primitive exec my-device "top -n 1"

# Monitor network
primitive exec my-device "ping -c 3 8.8.8.8"

# Check system load
primitive exec my-device "uptime"

Best Practices

1. Use Descriptive Device Names: Make devices easy to identify
2. Test Connectivity: Verify device is online before complex operations
3. Handle Errors Gracefully: Check command exit codes and output
4. Secure Credentials: Protect authentication tokens and keys
5. Monitor Resources: Be aware of resource usage on remote devices
6. Log Activities: Keep records of important remote operations
7. Use Interactive Mode: For complex debugging and exploration

Example Workflows

Development Deployment

# 1. Check device status
primitive hardware list

# 2. Pull latest code
primitive exec build-server "cd /home/user/project && git pull"

# 3. Install dependencies
primitive exec build-server "cd /home/user/project && npm install"

# 4. Run tests
primitive exec build-server "cd /home/user/project && npm test"

# 5. Build application
primitive exec build-server "cd /home/user/project && npm run build"

# 6. Deploy
primitive exec production-server "cd /opt/app && ./deploy.sh"

System Maintenance

# Check system status
primitive exec my-server "uptime && df -h"

# Update packages
primitive exec my-server "sudo apt update && sudo apt upgrade -y"

# Clean up logs
primitive exec my-server "sudo find /var/log -name '*.log' -mtime +30 -delete"

# Restart services
primitive exec my-server "sudo systemctl restart nginx"

# Verify services
primitive exec my-server "sudo systemctl status nginx"

Data Processing

# Upload data file
primitive files upload --key-prefix "data/" ./dataset.csv

# Process data on remote device
primitive exec data-processor "python /home/user/scripts/process.py /tmp/dataset.csv"

# Check results
primitive exec data-processor "ls -la /tmp/results/"

# Download results
primitive exec data-processor "cat /tmp/results/summary.json"

Interactive Debugging

# Start interactive session
primitive exec debug-server

# Inside the interactive session:
user@debug-server:~$ cd /var/log
user@debug-server:/var/log$ tail -n 50 application.log
user@debug-server:/var/log$ grep ERROR application.log
user@debug-server:/var/log$ ps aux | grep myapp
user@debug-server:/var/log$ exit