Daemon Management

The primitive daemons command group provides comprehensive management of background services that enable continuous operation of Primitive agent and monitor functionality. These daemons run as system services, automatically starting on boot and restarting on failure.

Overview

Primitive uses two main daemon services:

• Agent: Continuously polls for and executes jobs from the Primitive platform
• Monitor: Continuously monitors system resources and reports metrics

Platform Support

• macOS: Uses launchctl and LaunchAgent plist files
• Linux: Uses systemctl and systemd user services
• Windows: Not currently supported

Commands

primitive daemons install [name]

Install daemon services as background processes that start automatically.

# Install both agent and monitor daemons
primitive daemons install

# Install only the agent daemon
primitive daemons install agent

# Install only the monitor daemon
primitive daemons install monitor

What happens during installation:

1. Stops any existing daemon processes
2. Unloads/disables any existing daemon configurations
3. Creates log files in the appropriate directory
4. Generates platform-specific service configuration files
5. Loads/enables the new daemon configuration
6. Starts the daemon service

primitive daemons uninstall [name]

Completely remove daemon services from the system.

# Uninstall both agent and monitor daemons
primitive daemons uninstall

# Uninstall only the agent daemon
primitive daemons uninstall agent

# Uninstall only the monitor daemon
primitive daemons uninstall monitor

What happens during uninstallation:

1. Stops the daemon service
2. Unloads/disables the daemon configuration
3. Deletes the service configuration file
4. Removes log files

primitive daemons start [name]

Start daemon services.

# Start both agent and monitor daemons
primitive daemons start

# Start only the agent daemon
primitive daemons start agent

# Start only the monitor daemon
primitive daemons start monitor

primitive daemons stop [name]

Stop daemon services.

# Stop both agent and monitor daemons
primitive daemons stop

# Stop only the agent daemon
primitive daemons stop agent

# Stop only the monitor daemon
primitive daemons stop monitor

primitive daemons list

Display the status of all daemon services.

primitive daemons list

Shows information about each daemon including:

• Name and label
• Installation status
• Running status
• Configuration file location
• Log file location

primitive daemons logs <name>

View real-time logs from a specific daemon service.

# View agent daemon logs
primitive daemons logs agent

# View monitor daemon logs
primitive daemons logs monitor

This command uses tail -f to follow the log output in real-time. Press Ctrl+C to exit.

Platform-Specific Details

macOS (LaunchAgent)

On macOS, daemons are implemented as LaunchAgents using the launchctl system.

Configuration Location:

• Files: ~/Library/LaunchAgents/tech.primitive.{agent|monitor}.plist
• Logs: ~/Library/Logs/tech.primitive.{agent|monitor}.log

LaunchAgent Features:

• Automatically starts on user login
• Restarts on failure (KeepAlive=true)
• Runs in user session context
• Supports multiple session types (Aqua, Background, LoginWindow, StandardIO)

Manual Management:

# Load a daemon manually
launchctl load -w ~/Library/LaunchAgents/tech.primitive.agent.plist

# Unload a daemon manually
launchctl unload -w ~/Library/LaunchAgents/tech.primitive.agent.plist

# Check daemon status
launchctl list tech.primitive.agent

Linux (systemd)

On Linux, daemons are implemented as systemd user services.

Configuration Location:

• Files: ~/.config/systemd/user/tech.primitive.{agent|monitor}.service
• Logs: ~/.cache/primitive/tech.primitive.{agent|monitor}.log

systemd Features:

• Automatically starts with user session
• Restarts on failure (Restart=always)
• Integrated with systemd logging
• Supports dependency management

Manual Management:

# Enable a daemon manually
systemctl --user enable tech.primitive.agent.service

# Start a daemon manually
systemctl --user start tech.primitive.agent.service

# Check daemon status
systemctl --user status tech.primitive.agent.service

# View systemd logs
journalctl --user -u tech.primitive.agent.service -f

Configuration

Daemons automatically inherit configuration from your CLI setup:

• Host Configuration: Uses the same --host setting as your CLI
• Debug Mode: Enables --debug if your CLI is configured for debug mode
• Authentication: Uses the same credentials as your CLI configuration

Troubleshooting

Common Issues

1. Installation Fails

# Check if primitive binary is in PATH
which primitive

# Verify CLI configuration
primitive whoami

# Try installing with debug output
primitive --debug daemons install

2. Daemon Won't Start

# Check daemon status
primitive daemons list

# View recent logs
primitive daemons logs agent

# Try manual restart
primitive daemons stop agent
primitive daemons start agent

3. Permission Issues (Linux)

# Reload systemd configuration
systemctl --user daemon-reload

# Check systemd status
systemctl --user status tech.primitive.agent.service

4. Log File Issues

# Check log file permissions
ls -la ~/.cache/primitive/  # Linux
ls -la ~/Library/Logs/      # macOS

# Manually create log directory if needed
mkdir -p ~/.cache/primitive/  # Linux
mkdir -p ~/Library/Logs/      # macOS

Debug Information

Use the debug flag for detailed installation information:

primitive --debug daemons install

This will show:

• Executable path resolution
• Configuration file generation
• Platform-specific command execution
• Error details if installation fails

Best Practices

1. Install Both Services: For full functionality, install both agent and monitor daemons
2. Check Status Regularly: Use primitive daemons list to verify service health
3. Monitor Logs: Regularly check daemon logs for errors or warnings
4. Clean Reinstall: If experiencing issues, uninstall completely before reinstalling
5. System Resources: Monitor system resources when running continuous daemons

Security Considerations

• Daemons run with user privileges, not system/root privileges
• Log files may contain sensitive information - protect access appropriately
• Service configurations are created with appropriate file permissions (644)
• Daemons inherit CLI authentication credentials - ensure credentials are secure

Example Workflows

Complete Daemon Setup

# 1. Ensure CLI is configured
primitive config
primitive whoami

# 2. Install both daemons
primitive daemons install

# 3. Verify installation
primitive daemons list

# 4. Check initial logs
primitive daemons logs agent

Daemon Maintenance

# Check daemon status
primitive daemons list

# Restart a problematic daemon
primitive daemons stop agent
primitive daemons start agent

# View recent activity
primitive daemons logs agent

Troubleshooting Workflow

# 1. Check current status
primitive daemons list

# 2. Stop all daemons
primitive daemons stop

# 3. Completely uninstall
primitive daemons uninstall

# 4. Clean reinstall with debug
primitive --debug daemons install

# 5. Verify installation
primitive daemons list