Background Daemon

The AgentLoop daemon allows you to run the orchestrator as a persistent background service. This is useful for long-running tasks, CI/CD integration, or when you want sessions to survive terminal closures.

Overview


┌──────────────────────────────────────────────────────────────────┐
│                         User Terminal                            │
│                                                                  │
│   $ agentloop                    $ agentloop                     │
│   > /daemon start                > /orchestrator status          │
│   Daemon started ✓               Connected to daemon...          │
│   > /exit                        Orchestrator: running           │
│   (terminal closed)              Tasks: 3 in-progress            │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌──────────────────────────────────────────────────────────────────┐
│                    Background Daemon Process                     │
│                                                                  │
│   ┌────────────────────────────────────────────────────────┐     │
│   │                   Orchestrator                         │     │
│   │                                                        │     │
│   │  • Continues running after terminal closes             │     │
│   │  • Processes tasks autonomously                        │     │
│   │  • Maintains session state and history                 │     │
│   │  • Reconnectable from any terminal                     │     │
│   │  • Automatic recovery from interruptions               │     │
│   └────────────────────────────────────────────────────────┘     │
│                                                                  │
│   Session Data: ~/.config/agentloop/daemon/                             │
│   Logs: ~/.config/agentloop/logs/                                       │
└──────────────────────────────────────────────────────────────────┘

Use Cases

Use Case	Description
Long-Running Tasks	Start a large refactoring job and disconnect; reconnect later to check progress
CI/CD Integration	Run the daemon in your build pipeline for automated code generation
Remote Development	SSH into a server, start the daemon, disconnect, and reconnect later
Persistent Sessions	Conversation history and task state persist across CLI restarts

Daemon Commands

Interactive Mode

Manage the daemon from interactive mode:

Command	Description
`/daemon start`	Start the background daemon service
`/daemon stop`	Stop the running daemon
`/daemon restart`	Restart the daemon (useful after configuration changes)
`/daemon status`	Check if daemon is running and view connection info

Starting the Daemon


> /daemon start
Daemon started ✓
Process ID: 12345
Listening on: ~/.config/agentloop/daemon.sock

Once started, the daemon:

Runs in the background
Survives terminal closures
Continues processing tasks
Maintains conversation history

Checking Status


> /daemon status

Output shows:

Running state
Process ID
Active tasks
Connection information
Uptime

Stopping the Daemon


> /daemon stop
Daemon stopped ✓

This gracefully shuts down the daemon after completing any in-progress operations.

Restarting

After configuration changes:


> /daemon restart
Daemon restarted ✓

This stops the current daemon and starts a fresh instance with updated configuration.

Reconnecting

If you close your terminal, simply start AgentLoop again:


agentloop

The CLI automatically detects and connects to a running daemon, preserving your session.

Workflow Example

Remote Development


# SSH into remote server
ssh user@server
 
# Navigate to project
cd /path/to/project
 
# Start AgentLoop and create tasks
agentloop
> Break down "user authentication" into tasks
> /orchestrator run --infinite
> /daemon start
> /exit
 
# Disconnect from SSH
exit
 
# Later, reconnect
ssh user@server
cd /path/to/project
agentloop
 
# Resume where you left off
> /orchestrator status
> What tasks are done?

CI/CD Pipeline


# Example GitHub Actions workflow
jobs:
  generate-code:
    steps:
      - uses: actions/checkout@v3
 
      - name: Install AgentLoop
        run: npm install -g @trygentic/agentloop
 
      - name: Run orchestrator
        run: agentloop orchestrator

Long-Running Refactor


# Start a major refactoring job
> /orchestrator generate "Refactor authentication to use OAuth 2.0"
> /orchestrator run --infinite
> /daemon start

# Close terminal, go home, sleep...

# Next morning, check progress
$ agentloop
> /orchestrator status
> What's been completed?

Data Locations

Location	Purpose
`~/.config/agentloop/daemon/`	Session state and socket
`~/.config/agentloop/logs/`	Daemon logs
`~/.config/agentloop/`	Database and credentials

Troubleshooting

Daemon won’t start:

Check if a daemon is already running: /daemon status
Check logs in ~/.config/agentloop/logs/
Ensure socket file isn’t stale: remove ~/.config/agentloop/daemon.sock

Can’t connect to daemon:

Verify daemon is running: ps aux | grep agentloop
Check socket permissions
Try restarting: /daemon restart

Daemon stops unexpectedly:

Check system logs for OOM (out of memory) kills
Review daemon logs for errors
Ensure adequate disk space

The daemon includes automatic recovery mechanisms. If the process crashes, it can resume from the last known good state when restarted.

Learn about task scheduling in the daemon.

Orchestrator

Configure daemon and orchestrator settings.

Configuration