Service Management¶

Run XPyCode as a system service for automatic startup and background operation.

Overview¶

The service management feature enables XPyCode to run as a system service, providing:

Automatic Startup - Start with your system without manual intervention
Background Operation - Run continuously in the background
System Integration - Leverage native service managers on each platform

Supported Platforms¶

Windows - Uses pywin32 for Windows Service integration
Linux - Uses systemd for service management
macOS - Uses launchd for daemon management

Installation as a Service¶

Windows¶

Windows service installation uses pywin32 and integrates with Windows Services Manager.

# Install service (auto-start by default)
python -m xpycode_master service install

# Install without auto-start
python -m xpycode_master service install --no-auto-start

# Install with custom arguments
python -m xpycode_master service install --args "--log-level DEBUG"

Administrator Privileges

Windows service operations require Administrator privileges. Run your terminal as Administrator.

Linux¶

Linux service installation uses systemd for service management.

# Install service
sudo python -m xpycode_master service install

Sudo Required

On Linux, systemd operations require root privileges. Always use sudo for service management commands.

macOS¶

macOS service installation uses launchd for daemon management.

# Install service
python -m xpycode_master service install

User vs System Launch Agents

macOS installs as a user launch agent by default, which starts when you log in. System-wide daemons are not supported in this version.

Service Management Commands¶

Start Service¶

Start the XPyCode service:

python -m xpycode_master service start

Service Started

The service will start in the background. You can verify status with the status command.

Stop Service¶

Stop a running service:

python -m xpycode_master service stop

Restart Service¶

Restart the service (stop then start):

python -m xpycode_master service restart

When to Restart

Restart after updating XPyCode or changing service configuration.

Check Status¶

Get the current service status:

python -m xpycode_master service status

Output shows: - Service state (running, stopped, not installed) - Process ID (if running) - Auto-start configuration - Service arguments

Set Automatic Startup¶

Configure the service to start automatically on system boot:

python -m xpycode_master service set-auto

Set Manual Startup¶

Configure the service for manual start only:

python -m xpycode_master service set-manual

Update Service Arguments¶

Change the arguments passed to the XPyCode service:

python -m xpycode_master service set-args "--log-level DEBUG --use-external-addin"

Restart Required

After updating arguments, restart the service for changes to take effect.

Uninstall Service¶

Remove the service from your system:

python -m xpycode_master service uninstall

Permanent Removal

This removes the service configuration. You'll need to run install again to re-enable service mode.

Configuration¶

Service configuration is stored in a JSON file.

Configuration Location¶

~/.xpycode/service_config.json

On Windows: %USERPROFILE%\.xpycode\service_config.json

Configuration Options¶

{
  "args": "--log-level INFO",
  "auto_start": true
}

args - Command-line arguments passed to XPyCode on startup
auto_start - Whether to start automatically on system boot

Manual Configuration

You can edit this file directly, but using set-args and set-auto/set-manual commands is recommended.

Viewing Logs¶

Windows¶

View service logs in Windows Event Viewer:

Open Event Viewer (eventvwr.msc)
Navigate to Windows Logs → Application
Filter by source: xpycode_master

PowerShell Command:

Get-EventLog -LogName Application -Source "xpycode_master" -Newest 50

Event Viewer Access

Event Viewer logs are available to all users, but some events may require Administrator privileges to view.

Linux¶

View service logs using journalctl:

# Follow logs in real-time
journalctl -u xpycode.service -f

# View last 100 lines
journalctl -u xpycode.service -n 100

# View logs since boot
journalctl -u xpycode.service -b

Journal Permissions

You may need to use sudo to view system journal entries depending on your configuration.

macOS¶

View service logs using log show:

# View logs from the last hour
log show --predicate 'subsystem == "com.xpycode.master"' --last 1h

# Follow logs in real-time
log stream --predicate 'subsystem == "com.xpycode.master"'

# View today's logs
log show --predicate 'subsystem == "com.xpycode.master"' --info --debug --last 1d

Unified Logging

macOS uses the Unified Logging system. Logs are stored in binary format and accessed via the log command.

Troubleshooting¶

Service Won't Start¶

Check Permissions:

Windows: Ensure running as Administrator
Linux: Use sudo for service commands
macOS: Check launch agent permissions with launchctl list

Verify Installation:

python -m xpycode_master service status

If "not installed", run the install command again.

Service Crashes on Startup¶

Check Logs:

Review platform-specific logs (see Viewing Logs) for error messages.

Common Issues:

Port conflicts - Another service using the same port
Missing dependencies - Run pip install --upgrade xpycode_master
Invalid arguments - Check service_config.json for malformed args

Test Manually:

Run XPyCode manually to see errors directly:

python -m xpycode_master

Service Status Shows "Unknown"¶

This can happen when:

Service manager hasn't updated state yet (wait a few seconds)
Service was modified outside XPyCode commands
Platform-specific service manager has issues

Fix:

# Uninstall and reinstall
python -m xpycode_master service uninstall
python -m xpycode_master service install

Windows Service Control Manager Errors¶

If you see "Access Denied" or similar errors:

Open Command Prompt or PowerShell as Administrator
Verify Windows Service Manager has permission to start services
Check Windows Event Viewer for detailed error messages

Linux systemd Unit Not Found¶

If systemctl reports unit not found:

# Check if unit file exists
ls -la /etc/systemd/system/xpycode.service

# Reload systemd
sudo systemctl daemon-reload

# Reinstall service
sudo python -m xpycode_master service install

macOS Launch Agent Not Loading¶

If launchd won't load the agent:

# Check for errors
launchctl list | grep xpycode

# View detailed status
launchctl print gui/$(id -u)/com.xpycode.master

# Unload and reload
launchctl unload ~/Library/LaunchAgents/com.xpycode.master.plist
launchctl load ~/Library/LaunchAgents/com.xpycode.master.plist

Permission Denied Errors¶

Windows: - Run terminal as Administrator - Check user account has service installation rights

Linux: - Use sudo for all service commands - Verify user is in appropriate groups (systemd-journal for log viewing)

macOS: - User launch agents don't require sudo - Check file permissions in ~/Library/LaunchAgents/

Tips¶

Start Simple: Install with defaults first, customize later
Check Logs: Always review logs when troubleshooting
Test Manually: Run XPyCode manually before installing as service
Auto-start: Enable auto-start only after verifying service works correctly

Next Steps¶

Settings - Configure XPyCode preferences
IDE Overview - Learn about IDE features
Troubleshooting - General troubleshooting guide