Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/slopus/happy/llms.txt

Use this file to discover all available pages before exploring further.

The happy daemon command manages the Happy background service that enables remote session spawning and mobile control.

​
Syntax

happy daemon <subcommand>

​
Subcommands

​
start

Start the daemon in detached mode. 
happy daemon start
Spawns a background process that runs independently of your terminal.

​
stop

Stop the daemon (sessions continue running). 
happy daemon stop
Stopping the daemon does not kill active sessions. They continue running but can’t spawn new sessions remotely until the daemon restarts.

​
status

Show daemon status and diagnostics. 
happy daemon status
Displays daemon-specific diagnostics including PID, uptime, and version.

​
list

List active sessions tracked by the daemon. 
happy daemon list

​
stop-session

Stop a specific session by ID. 
happy daemon stop-session <session-id>
​
session-id
string
required
The session ID to stop

​
logs

Display the path to the latest daemon log file. 
happy daemon logs

​
install

Install the daemon as a system service (platform-specific). 
happy daemon install
On macOS, this creates a LaunchAgent that starts the daemon at login.

​
uninstall

Uninstall the daemon system service. 
happy daemon uninstall

​
Description

The Happy daemon is a background service that:
  • Enables spawning sessions from your mobile device
  • Manages session lifecycle
  • Provides keep-alive signals for active sessions
  • Handles version compatibility checks
  • Maintains session registry

​
Auto-Start Behavior

The daemon automatically starts when you:
  • Run happy (main command)
  • Run happy gemini
  • Run happy acp
  • Start any agent that requires mobile control
You typically don’t need to manually start the daemon - Happy handles it automatically.

​
Examples

​
Check Daemon Status

happy daemon status
Output: 
🤖 Daemon Status
✓ Daemon is running
  PID: 12345
  Started: 2024-01-15 10:30:00
  CLI Version: 1.0.0
  HTTP Port: 54321

📄 Daemon State:
Location: /Users/username/.happy/daemon-state.json
{
  "pid": 12345,
  "startTime": 1705317000000,
  "startedWithCliVersion": "1.0.0",
  "httpPort": 54321
}

​
List Active Sessions

happy daemon list
Output when sessions are active: 
Active sessions:
[
  {
    "id": "abc-123-def-456",
    "type": "claude",
    "startTime": 1705317000000,
    "path": "/Users/username/projects/my-app"
  },
  {
    "id": "xyz-789-ghi-012",
    "type": "gemini",
    "startTime": 1705318000000,
    "path": "/Users/username/projects/other-app"
  }
]
Output when no sessions: 
No active sessions this daemon is aware of (they might have been started by a previous version of the daemon)

​
Stop a Session

happy daemon stop-session abc-123-def-456
Output: 
Session stopped

​
View Daemon Logs

happy daemon logs
Output: 
/Users/username/.happy/logs/2024-01-15-10-30-00-daemon.log
Then view the log: 
tail -f $(happy daemon logs)

​
Start Daemon Manually

happy daemon start
Output: 
Daemon started successfully

​
Stop Daemon

happy daemon stop
Output: 
Daemon stopped

​
Install as System Service (macOS)

happy daemon install
This creates a LaunchAgent at: 
~/Library/LaunchAgents/com.happy.daemon.plist
The daemon will automatically start:
  • At system login
  • When the user logs in
  • After crashes (with exponential backoff)

​
Uninstall System Service

happy daemon uninstall
Removes the LaunchAgent and stops the daemon.

​
Daemon State File

The daemon stores its state in:
  • Production: ~/.happy/daemon-state.json
  • Development: ~/.happy-dev/daemon-state.json

​
State File Contents

{
  "pid": 12345,
  "startTime": 1705317000000,
  "startedWithCliVersion": "1.0.0",
  "httpPort": 54321
}
​
pid
number
Process ID of the running daemon
​
startTime
number
Unix timestamp when daemon started
​
startedWithCliVersion
string
Version of Happy CLI that started the daemon
​
httpPort
number
HTTP port the daemon listens on for control commands

​
Log Files

Daemon logs are stored in:
  • Location: ~/.happy/logs/ (or ~/.happy-dev/logs/)
  • Format: YYYY-MM-DD-HH-MM-SS-daemon.log
  • Example: 2024-01-15-10-30-00-daemon.log

​
Viewing Logs

tail -f $(happy daemon logs)

​
Version Compatibility

The daemon includes version checking:
  • Automatically restarts if CLI version doesn’t match daemon version
  • Ensures compatibility between daemon and CLI commands
  • Prevents version mismatch issues

​
Version Mismatch Handling

When you update Happy CLI:
  1. Next happy command detects version mismatch
  2. Automatically stops old daemon
  3. Starts new daemon with current version
  4. Session continues seamlessly

​
Process Management

​
Daemon Process Hierarchy

happy daemon (PID 12345)
├── Session 1 (claude)
├── Session 2 (gemini)
└── MCP Servers

​
Cleanup Runaway Processes

If processes become orphaned or stuck: 
happy doctor clean
This will:
  • Find all Happy-related processes
  • Identify orphaned/stuck processes
  • Kill runaway processes
  • Clean up stale state files
Output: 
Cleaned up 3 runaway processes

​
Troubleshooting

​
Daemon Won’t Start

If daemon fails to start: 
# Check for port conflicts
happy daemon status

# View logs
tail -f $(happy daemon logs)

# Kill any stuck processes
happy doctor clean

# Try starting again
happy daemon start

​
Daemon Keeps Restarting

If daemon repeatedly restarts: 
# Check logs for errors
tail -f $(happy daemon logs)

# Run diagnostics
happy doctor

# Check for version issues
happy --version

​
Stale Daemon State

If state file exists but daemon isn’t running: 
# Happy automatically cleans stale state
happy daemon status

# Or manually clean
rm ~/.happy/daemon-state.json
happy daemon start

​
Can’t Connect to Daemon

If commands fail to reach the daemon: 
# Check if running
happy daemon status

# Check port isn't blocked
lsof -i :$(cat ~/.happy/daemon-state.json | jq -r .httpPort)

# Restart daemon
happy daemon stop
happy daemon start

​
Sessions Not Listed

If happy daemon list shows no sessions but you have active sessions:
Sessions started before the current daemon may not appear in the list. The daemon only tracks sessions started after it was launched.
Solution: 
# View all Happy processes
happy doctor

# This shows all sessions regardless of daemon tracking

​
Environment Variables

​
HAPPY_SERVER_URL
string
Server URL for the daemon to connect to
HAPPY_SERVER_URL=http://localhost:3005 happy daemon start
​
HAPPY_HOME_DIR
string
Override Happy data directory
HAPPY_HOME_DIR=/custom/path happy daemon start

​
Advanced Usage

​
Synchronous Start (Internal)

happy daemon start-sync
Starts the daemon synchronously (blocks until daemon exits). This is used internally by happy daemon start to spawn the detached process.
Don’t use start-sync directly - use start instead. The start-sync command is for internal use only.

​
Monitor Daemon

# Watch daemon status
watch -n 1 'happy daemon status'

# Monitor logs
tail -f $(happy daemon logs)

# Check process
ps aux | grep happy
The daemon runs automatically when needed. You typically only need these commands for troubleshooting or manual control.

Build docs developers (and LLMs) love

Get started for freeTalk to us