Service Management - Agentic AI

Learn how to run Agentic AI as a persistent background service using launchd (macOS) with automatic restart and logging.

Overview

Agentic AI can run as a background service (daemon) that:

✅ Starts automatically on login/boot
✅ Restarts on crash
✅ Runs the scheduler for automated calls
✅ Logs to persistent files
✅ Requires no manual intervention

Reference: src/agenticai/cli.py:722-1055 (service management commands)

Prerequisites

Step 1: Complete Setup

Ensure you’ve configured credentials:

agenticai setup

Step 2: Get a Permanent Webhook URL

For production, use a permanent tunnel instead of ngrok’s temporary URLs:

Option A: Cloudflare Tunnel (Free)

# Install cloudflared
brew install cloudflared

# Start permanent tunnel
cloudflared tunnel --url http://localhost:8080

Option B: ngrok with Fixed Domain (Paid)

ngrok http 8080 --domain=your-subdomain.ngrok-free.app

Copy the URL for the next step.

Step 3: Test Server

Verify the server works before installing as a service:

agenticai server

Press Ctrl+C to stop once verified.

Install the Service

Install Agentic AI as a launchd service:

agenticai service install --webhook-url https://your-permanent-url.com

Example:

agenticai service install --webhook-url https://abc123.trycloudflare.com

What happens:

Creates a launchd plist file at:

~/Library/LaunchAgents/com.agenticai.server.plist

Configures auto-start on login
Sets up crash recovery
Creates log directory:
```
/tmp/agenticai/
```
Loads the service (but doesn’t start it yet)

Reference: src/agenticai/cli.py:828-891

Service Commands

Start the Service

agenticai service start

Output:

✓ Service started
View logs: tail -f /tmp/agenticai/agenticai.log

Stop the Service

agenticai service stop

Restart the Service

agenticai service restart

Useful after configuration changes.

Check Service Status

agenticai service status

Example Output:

┌────────────────────────────────────┐
│   Agentic AI Service Status        │
└────────────────────────────────────┘

✓ Service installed
  Plist: ~/Library/LaunchAgents/com.agenticai.server.plist

✓ Service running (PID: 12345)

Recent logs:
  [2024-03-15 14:32:01] INFO: Starting Agentic AI server
  [2024-03-15 14:32:02] INFO: Server running on 0.0.0.0:8080
  [2024-03-15 14:32:02] INFO: Scheduler started
  [2024-03-15 14:32:02] INFO: Next run: morning_check at 2024-03-16 09:00:00

Full logs: tail -f /tmp/agenticai/agenticai.log

Reference: src/agenticai/cli.py:993-1034

View Logs

Follow logs in real-time:

agenticai service logs --follow

Or use the shorthand:

agenticai service logs -f

View last 50 lines:

agenticai service logs

View last 100 lines:

agenticai service logs --lines 100

Reference: src/agenticai/cli.py:1036-1055

Uninstall the Service

agenticai service uninstall

This:

Stops the service
Removes the plist file
Preserves logs in /tmp/agenticai/

Reference: src/agenticai/cli.py:893-912

Service Configuration

The service is configured via a launchd plist file.

Plist Location

~/Library/LaunchAgents/com.agenticai.server.plist

Generated Configuration

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.agenticai.server</string>
    
    <key>ProgramArguments</key>
    <array>
        <string>/path/to/agenticai</string>
        <string>server</string>
    </array>
    
    <key>WorkingDirectory</key>
    <string>/path/to/project</string>
    
    <key>EnvironmentVariables</key>
    <dict>
        <key>PATH</key>
        <string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string>
        <key>AGENTICAI_WEBHOOK_URL</key>
        <string>https://your-url.com</string>
    </dict>
    
    <key>RunAtLoad</key>
    <true/>
    
    <key>KeepAlive</key>
    <dict>
        <key>SuccessfulExit</key>
        <false/>
        <key>Crashed</key>
        <true/>
    </dict>
    
    <key>StandardOutPath</key>
    <string>/tmp/agenticai/agenticai.log</string>
    
    <key>StandardErrorPath</key>
    <string>/tmp/agenticai/agenticai-error.log</string>
    
    <key>ThrottleInterval</key>
    <integer>10</integer>
</dict>
</plist>

Reference: src/agenticai/cli.py:728-786

Key Configuration Options

Option	Description
`RunAtLoad`	Start service when loaded (on login)
`KeepAlive`	Automatically restart if crashed
`ThrottleInterval`	Wait 10 seconds between restart attempts
`StandardOutPath`	Log stdout to file
`StandardErrorPath`	Log stderr to separate file

Daemon Mode

Alternatively, run in daemon mode without installing as a service:

agenticai daemon --webhook-url https://your-url.com

This:

Starts the server
Starts the scheduler
Shows next scheduled call times
Runs in foreground (use Ctrl+C to stop)

Example Output:

Starting Agentic AI in daemon mode
Scheduler started
  morning_check: 2024-03-16 09:00:00
  weekly_report: 2024-03-17 17:00:00
INFO:     Started server process [12345]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8080

Reference: src/agenticai/cli.py:257-308

Daemon mode is useful for testing, but service mode is recommended for production.

Logs and Monitoring

Log Files

File	Content
`/tmp/agenticai/agenticai.log`	Standard output (INFO logs)
`/tmp/agenticai/agenticai-error.log`	Error output (ERROR logs)

Tail Logs

Standard logs:

tail -f /tmp/agenticai/agenticai.log

Error logs:

tail -f /tmp/agenticai/agenticai-error.log

Both logs:

tail -f /tmp/agenticai/agenticai*.log

Log Rotation

For production, set up log rotation:

# Create newsyslog config
sudo nano /etc/newsyslog.d/agenticai.conf

Add:

# logfilename          [owner:group]    mode count size when  flags
/tmp/agenticai/*.log                    644  7     10M   *     J

This rotates logs:

Keep 7 backups
Rotate when size exceeds 10MB
Compress old logs (J flag)

Auto-Start on Boot

The service automatically starts on login by default.

Verify Auto-Start

Install the service:

agenticai service install --webhook-url https://your-url.com

Restart your computer
Check service status:
```
agenticai service status
```

You should see:

✓ Service running (PID: xxxx)

Disable Auto-Start

If you want manual control:

# Unload from auto-start
launchctl unload ~/Library/LaunchAgents/com.agenticai.server.plist

# Start manually when needed
agenticai service start

Crash Recovery

The service automatically restarts if it crashes.

How It Works

<key>KeepAlive</key>
<dict>
    <key>SuccessfulExit</key>
    <false/>  <!-- Don't restart on clean exit -->
    <key>Crashed</key>
    <true/>   <!-- DO restart on crash -->
</dict>

<key>ThrottleInterval</key>
<integer>10</integer>  <!-- Wait 10s between restarts -->

Reference: src/agenticai/cli.py:767-782

Test Crash Recovery

Find the service PID:

agenticai service status
# Output: Service running (PID: 12345)

Kill the process:
```
kill -9 12345
```
Wait 10 seconds

Check status again:

agenticai service status
# Should show new PID

Update Webhook URL

To change the webhook URL:

# Uninstall old service
agenticai service uninstall

# Reinstall with new URL
agenticai service install --webhook-url https://new-url.com

# Start the service
agenticai service start

Troubleshooting

Service won't start

Symptoms: agenticai service start failsSolutions:

Check if already running:
```
agenticai service status
```

Check for port conflicts:

lsof -i :8080
# Kill conflicting process or change port in config.yaml

Verify plist exists:

ls -la ~/Library/LaunchAgents/com.agenticai.server.plist

Check error logs:
```
cat /tmp/agenticai/agenticai-error.log
```

Validate plist syntax:

plutil -lint ~/Library/LaunchAgents/com.agenticai.server.plist

Reference: src/agenticai/cli.py:789-820

Service starts but crashes immediately

Symptoms: Service shows as running but PID disappearsSolutions:

Check error logs:

tail -50 /tmp/agenticai/agenticai-error.log

Common issues:
- Missing environment variables in .env
- Invalid Twilio/OpenAI credentials
- Port 8080 already in use
- Config.yaml syntax errors

Test manually first:

agenticai server
# Look for error messages

Verify all services:
```
agenticai test-connection
```

Logs not appearing

Symptoms: /tmp/agenticai/ is empty or outdatedSolutions:

Check log directory exists:
```
ls -la /tmp/agenticai/
```
Create directory manually:
```
mkdir -p /tmp/agenticai
```
Check permissions:
```
chmod 755 /tmp/agenticai
```
Restart service:
```
agenticai service restart
```

Reference: src/agenticai/cli.py:852

Service doesn't auto-start on login

Symptoms: Must manually start service after rebootSolutions:

Verify plist is loaded:

launchctl list | grep agenticai
# Should show: com.agenticai.server

Reload the plist:

launchctl unload ~/Library/LaunchAgents/com.agenticai.server.plist
launchctl load ~/Library/LaunchAgents/com.agenticai.server.plist

Check RunAtLoad is true:

grep -A 1 "RunAtLoad" ~/Library/LaunchAgents/com.agenticai.server.plist
# Should show: <true/>

Reinstall service:

agenticai service uninstall
agenticai service install --webhook-url https://your-url.com

Advanced: Custom Service Configuration

For advanced users, you can manually edit the plist:

nano ~/Library/LaunchAgents/com.agenticai.server.plist

Add Environment Variables

<key>EnvironmentVariables</key>
<dict>
    <key>AGENTICAI_WEBHOOK_URL</key>
    <string>https://your-url.com</string>
    
    <!-- Add custom variables -->
    <key>LOG_LEVEL</key>
    <string>debug</string>
    
    <key>MAX_CONCURRENT_CALLS</key>
    <string>10</string>
</dict>

Change Log Location

<key>StandardOutPath</key>
<string>/var/log/agenticai/agenticai.log</string>

<key>StandardErrorPath</key>
<string>/var/log/agenticai/agenticai-error.log</string>

Reload After Changes

launchctl unload ~/Library/LaunchAgents/com.agenticai.server.plist
launchctl load ~/Library/LaunchAgents/com.agenticai.server.plist

Monitoring Service Health

Check Service is Running

curl http://localhost:8080/health

Expected:

{
  "status": "healthy",
  "active_calls": 0
}

List Active Calls

curl http://localhost:8080/api/calls

macOS Activity Monitor

Open Activity Monitor
Search for “agenticai”
View CPU, memory usage, and PID

Next Steps

Scheduling Calls

Automate calls with schedules

Making Calls

Trigger outbound calls

Receiving Calls

Handle incoming calls

Telegram Integration

Monitor calls via Telegram

Get Started

Core Concepts

Configuration

Usage Guides

Integrations

Troubleshooting

​Overview

​Prerequisites

​Install the Service

​Service Commands

​Start the Service

​Stop the Service

​Restart the Service

​Check Service Status

​View Logs

​Uninstall the Service

​Service Configuration

​Plist Location

​Generated Configuration

​Key Configuration Options

​Daemon Mode

​Logs and Monitoring

​Log Files

​Tail Logs

​Log Rotation

​Auto-Start on Boot

​Verify Auto-Start

​Disable Auto-Start

​Crash Recovery

​How It Works

​Test Crash Recovery

​Update Webhook URL

​Troubleshooting

​Advanced: Custom Service Configuration

​Add Environment Variables

​Change Log Location

​Reload After Changes

​Monitoring Service Health

​Check Service is Running

​List Active Calls

​macOS Activity Monitor

​Next Steps

Scheduling Calls

Making Calls

Receiving Calls

Telegram Integration

Build docs developers (and LLMs) love

Overview

Prerequisites

Install the Service

Service Commands

Start the Service

Stop the Service

Restart the Service

Check Service Status

View Logs

Uninstall the Service

Service Configuration

Plist Location

Generated Configuration

Key Configuration Options

Daemon Mode

Logs and Monitoring

Log Files

Tail Logs

Log Rotation

Auto-Start on Boot

Verify Auto-Start

Disable Auto-Start

Crash Recovery

How It Works

Test Crash Recovery

Update Webhook URL

Troubleshooting

Advanced: Custom Service Configuration

Add Environment Variables

Change Log Location

Reload After Changes

Monitoring Service Health

Check Service is Running

List Active Calls

macOS Activity Monitor

Next Steps