Daemon Operations

Platform-specific setup, health monitoring, and troubleshooting for the Trix daemon.

Updated Oct 6, 2026

Platform-Specific Setup

The daemon integrates with your operating system's service manager for automatic startup and management.

Linux (systemd)

On Linux, the daemon installs as a user-level systemd service:

# Install as user service
trixd install

# Service file location
# ~/.config/systemd/user/trixd.service

# Manage with systemctl
systemctl --user status trixd
systemctl --user start trixd
systemctl --user stop trixd
systemctl --user restart trixd

# View logs with journalctl
journalctl --user -u trixd -f

# Enable auto-start on login
systemctl --user enable trixd

# Disable auto-start
systemctl --user disable trixd

systemd Service File

# ~/.config/systemd/user/trixd.service
[Unit]
Description=Trix Daemon
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/trixd run
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target

macOS (launchd)

On macOS, the daemon installs as a launchd agent:

# Install as user agent
trixd install

# Plist location
# ~/Library/LaunchAgents/com.trix.trixd.plist

# Manage with launchctl
launchctl list | grep trixd
launchctl start com.trix.trixd
launchctl stop com.trix.trixd

# Unload/reload (restart)
launchctl unload ~/Library/LaunchAgents/com.trix.trixd.plist
launchctl load ~/Library/LaunchAgents/com.trix.trixd.plist

# View logs
tail -f ~/.trix/logs/daemon.log

# The daemon auto-starts on login by default

launchd Plist File

<?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.trix.trixd</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/local/bin/trixd</string>
        <string>run</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>~/.trix/logs/daemon.log</string>
    <key>StandardErrorPath</key>
    <string>~/.trix/logs/daemon.log</string>
</dict>
</plist>

Windows (Service)

On Windows, the daemon installs as a Windows Service:

# Install as Windows Service (run as Administrator)
trixd install

# Service name: TrixDaemon

# Manage with sc command
sc query TrixDaemon
sc start TrixDaemon
sc stop TrixDaemon

# Or use net commands
net start TrixDaemon
net stop TrixDaemon

# View logs
Get-Content $env:USERPROFILE\.trix\logs\daemon.log -Wait

# Or use Event Viewer
eventvwr.msc

On Windows, service installation requires Administrator privileges. Open PowerShell or Command Prompt as Administrator before running trixd install.

Health & Monitoring

The daemon exposes HTTP endpoints for health checks and metrics.

HTTP Endpoints

# Health check (returns 200 if healthy)
curl http://127.0.0.1:9090/health

# Response: {"status": "healthy", "timestamp": "2024-01-15T10:30:00Z"}

# Detailed status
curl http://127.0.0.1:9090/status

# Prometheus metrics
curl http://127.0.0.1:9090/metrics

Prometheus Metrics

Available metrics for monitoring:

Metric	Type	Description
`trixd_up`	gauge	1 if daemon is running
`trixd_cache_entries`	gauge	Number of cached memories
`trixd_cache_size_bytes`	gauge	Total cache size in bytes
`trixd_sync_last_success_timestamp`	gauge	Unix timestamp of last successful sync
`trixd_sync_duration_seconds`	histogram	Sync cycle duration
`trixd_sync_errors_total`	counter	Total sync errors
`trixd_ipc_connections`	gauge	Active IPC connections
`trixd_ipc_requests_total`	counter	Total IPC requests
`trixd_watcher_events_total`	counter	File watcher events processed

Grafana Dashboard

Example Prometheus queries for Grafana:

# Cache hit rate
rate(trixd_cache_hits_total[5m]) / rate(trixd_cache_requests_total[5m])

# Sync success rate
rate(trixd_sync_success_total[1h]) / rate(trixd_sync_attempts_total[1h])

# Average sync duration
rate(trixd_sync_duration_seconds_sum[5m]) / rate(trixd_sync_duration_seconds_count[5m])

# IPC request rate
rate(trixd_ipc_requests_total[1m])

Cache Management

The local cache provides fast, offline access to your memories.

Cache Location

By default: ~/.trix/cache/

Each memory is stored as a separate JSON file for quick access and easy inspection.

Cache Operations

# View cache stats
trixd status

# Clear specific entry via IPC
echo '{"jsonrpc":"2.0","id":1,"method":"invalidate","params":{"id":"mem_abc123"}}' | \
  nc -U ~/.trix/daemon.sock

# Clear entire cache
rm -rf ~/.trix/cache/*

# Force re-sync
trixd restart

The cache is ephemeral and safe to delete. The daemon will repopulate it on the next sync cycle.

Troubleshooting

Quick Diagnostics

# Run all diagnostic checks
trixd doctor

# Check if daemon is running
trixd status

# View recent logs
trixd logs -n 50

# View logs in real-time
trixd logs -f

Daemon Won't Start

Check configuration: Run trixd doctor to validate config
Port conflict: Check if port 9090 is in use: lsof -i :9090
Stale socket: Remove stale socket: rm ~/.trix/daemon.sock
Permissions: Ensure write access: ls -la ~/.trix/

# Check for port conflicts
lsof -i :9090

# Remove stale socket
rm -f ~/.trix/daemon.sock

# Check directory permissions
ls -la ~/.trix/

API Connection Issues

Verify API key: Run trix auth status
Check URL: Ensure api.url is correct in config
Test connectivity: curl https://api.trixdb.com/health
Firewall: Ensure outbound HTTPS (port 443) is allowed

# Test API connectivity
curl -H "Authorization: Bearer $TRIX_API_KEY" https://api.trixdb.com/v1/health

# Check network
ping api.trixdb.com

# DNS resolution
nslookup api.trixdb.com

Sync Issues

Check logs: trixd logs -f during sync
Force sync: Trigger via IPC or restart
Enable debug: Set log.level: debug in config

File Watcher Issues

Verify directories: Ensure paths exist and are readable
Check patterns: Test with simple patterns like *.md
Permissions: Daemon needs read access to watched directories

# Linux: Increase inotify watches if needed
echo "fs.inotify.max_user_watches=524288" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

# Check current limit
cat /proc/sys/fs/inotify/max_user_watches

Service Issues

# Check service status
systemctl --user status trixd

# View service logs
journalctl --user -u trixd -e

# Reload after config changes
systemctl --user daemon-reload
systemctl --user restart trixd

# Reinstall if needed
trixd uninstall && trixd install

Debug Mode

For detailed debugging, run in foreground with maximum verbosity:

# Stop the service first
trixd stop

# Run with trace-level logging
trixd run -vvv

# Or enable debug in config
# log:
#   level: debug

Full Reset

If all else fails, perform a complete reset:

# Stop and uninstall
trixd stop
trixd uninstall

# Remove all daemon data (keeps CLI config)
rm -rf ~/.trix/cache
rm -rf ~/.trix/logs
rm -f ~/.trix/daemon.sock

# Reinstall fresh
trixd install
trixd start
trixd status

When seeking support, include the output of trixd doctor and recent logs from trixd logs -n 100.

Security Considerations

API Key Storage

Store API keys securely; avoid committing to version control
Use environment variables in shared/CI environments
Rotate keys periodically via trix keys

File Permissions

# Secure your Trix directory
chmod 700 ~/.trix
chmod 600 ~/.trix/daemon.yaml
chmod 600 ~/.trix/config.yaml

# Socket permissions (auto-set by daemon)
# ~/.trix/daemon.sock is created with mode 0600

IPC Socket Security

Socket created with mode 0600 (owner access only)
Only local processes can connect
No authentication required (relies on file permissions)

Cache Security

Cache contains your memories in plaintext JSON
Protect ~/.trix/cache with appropriate permissions
Consider full-disk encryption for sensitive data

HTTP Server Security

Binds to localhost (127.0.0.1) by default
Never expose to external networks without authentication
Disable if not needed: http.enabled: false

File Watcher Security

Disabled by default for security
Only watch directories you explicitly trust
Avoid broad patterns that might match sensitive files
Be careful with shared directories

# Recommended security setup
chmod 700 ~/.trix
chmod 600 ~/.trix/daemon.yaml

# Use environment variables for API key
export TRIX_API_KEY="your-key-here"

# Don't store key in config file
# api:
#   url: https://api.trixdb.com
#   # key: <use TRIX_API_KEY env var instead>