agent-manager/SYSTEMD.md

Systemd Service Installation

This document explains how to install and run the Agent Manager as a systemd service.

Prerequisites

• Node.js >= 18.0.0
• A non-root user to run the service (recommended: claude)
• systemd-based Linux distribution

Installation Steps

1. Prepare the application

Clone the repository to the user's home directory:

cd /home/claude
git clone <repository-url> agent-manager
cd agent-manager

2. Configure the application

Create your .env file from the example:

cp .env.example .env

Edit .env to configure your settings:

nano .env

Create your commands.json from the example:

cp commands.json.example commands.json

Edit commands.json to configure your webhook commands:

nano commands.json

3. Install the systemd service

Copy the service file to systemd directory (requires sudo):

sudo cp agent-manager.service /etc/systemd/system/

If your installation path is different from /home/claude/agent-manager, edit the service file:

sudo nano /etc/systemd/system/agent-manager.service

Update these fields:

• WorkingDirectory: Path to your installation
• User: The unprivileged user to run as
• Group: The group to run as
• ReadWritePaths: Path to your installation (for writing queue.json)

4. Enable and start the service

Reload systemd to recognize the new service:

sudo systemctl daemon-reload

Enable the service to start on boot:

sudo systemctl enable agent-manager

Start the service:

sudo systemctl start agent-manager

Managing the Service

Check service status

sudo systemctl status agent-manager

View logs (last 100 lines, follow mode)

journalctl -u agent-manager -f -n100

View logs without follow

journalctl -u agent-manager -n100

View logs since a specific time

journalctl -u agent-manager --since "2025-10-28 10:00:00"

View logs for today

journalctl -u agent-manager --since today

Stop the service

sudo systemctl stop agent-manager

Restart the service

sudo systemctl restart agent-manager

Disable the service (won't start on boot)

sudo systemctl disable agent-manager

Updating the Application

When updating the application code:

1. Stop the service:

   sudo systemctl stop agent-manager
   

2. Pull the latest changes:

   cd /home/claude/agent-manager
   git pull
   

3. Start the service:

   sudo systemctl start agent-manager
   

4. Check logs to ensure it started correctly:

   journalctl -u agent-manager -f -n50
   

Logging

The logger automatically detects when running under systemd and adjusts its output:

• With systemd: Colors and timestamps are disabled (journald adds these)
• Without systemd: Colors and timestamps are enabled for better console output

You can view logs using journalctl:

# Follow logs in real-time
journalctl -u agent-manager -f

# Show last 100 lines
journalctl -u agent-manager -n100

# Show logs from the last hour
journalctl -u agent-manager --since "1 hour ago"

# Show logs with specific priority (error, warning, info)
journalctl -u agent-manager -p err

# Export logs to file
journalctl -u agent-manager > agent-manager.log

Security Features

The service file includes several security hardening options:

• NoNewPrivileges=true: Prevents privilege escalation
• PrivateTmp=true: Uses private /tmp directory
• ProtectSystem=strict: Makes most of the filesystem read-only
• ProtectHome=read-only: Makes home directories read-only (except WorkingDirectory)
• ReadWritePaths: Only allows writing to the application directory

Troubleshooting

Service fails to start

Check the service status:

sudo systemctl status agent-manager

View detailed logs:

journalctl -u agent-manager -n100

Permission issues

Ensure the claude user has read/write access to the application directory:

sudo chown -R claude:claude /home/claude/agent-manager

Port already in use

Check if another process is using port 3000 (or your configured port):

sudo lsof -i :3000

Either stop the conflicting process or change the port in .env:

PORT=3001

Then restart the service:

sudo systemctl restart agent-manager

Node.js not found

Ensure Node.js is installed and the path in the service file is correct:

which node

If the path is different, update ExecStart in /etc/systemd/system/agent-manager.service.

File Permissions

The application needs write access to create queue.json for job persistence. Ensure:

# Check ownership
ls -la /home/claude/agent-manager

# Fix ownership if needed
sudo chown -R claude:claude /home/claude/agent-manager

# Verify permissions
ls -la /home/claude/agent-manager/queue.json

Advanced Configuration

Custom environment variables

Add environment variables in the service file under the [Service] section:

Environment=NODE_ENV=production
Environment=CUSTOM_VAR=value

Or use an environment file:

EnvironmentFile=/home/claude/agent-manager/.env.systemd

Automatic restarts

The service is configured to restart on failure with a 10-second delay. Modify these settings in the service file:

Restart=on-failure
RestartSec=10s

Options for Restart:

• no: Never restart
• on-failure: Restart only on failure
• on-abnormal: Restart on abnormal termination
• always: Always restart

Resource limits

Add resource limits to the service file:

[Service]
MemoryMax=500M
CPUQuota=50%
TasksMax=100