Skip to main content
The Fliiq daemon is a background process that runs scheduled jobs, listens for Telegram messages, and exposes a health API. It’s a thin FastAPI server that spawns agent loops — each job runs independently.

​
Starting the Daemon

# Foreground (see logs in terminal)
fliiq daemon start

# Detached (runs in background)
fliiq daemon start --detach

​
Managing the Daemon

fliiq daemon status     # Check if running, show Telegram status
fliiq daemon stop       # Graceful shutdown
fliiq daemon restart    # Stop + start

​
What the Daemon Does

  1. Loads jobs from .fliiq/jobs/*.yaml
  2. Schedules timers for each job based on trigger config (cron, interval, one-shot)
  3. Executes jobs by spawning fresh agent_loop() calls with the job’s prompt and skills
  4. Listens for Telegram messages (if TELEGRAM_BOT_TOKEN is set) and email (if Gmail credentials are configured) — all channel listeners use a shared persistent session store so conversation context is preserved across job runs and restarts, for every channel
  5. Exposes health API at http://localhost:7890/health

​
Architecture

Each job execution is isolated:
  • Fresh agent_loop() call — no shared message history with interactive sessions
  • Independent — multiple jobs can run simultaneously
  • Per-job memory at .fliiq/memory/jobs/<name>.md
  • Audit trails saved automatically
The daemon doesn’t block interactive use. You can run fliiq while the daemon runs jobs in the background.
Telegram prerequisite: If TELEGRAM_BOT_TOKEN is set in your .env, you must also set TELEGRAM_ALLOWED_CHAT_IDS. The daemon will refuse to start without it. Run fliiq telegram setup to configure this interactively — see Telegram setup for details.

​
Auto-Restart on Upgrade

When Fliiq is upgraded to a new version (e.g. via pip install --upgrade fliiq), the daemon detects the version change and automatically restarts itself to pick up the new code. No manual intervention needed — the daemon comes back up on the new version without dropping any scheduled jobs.

​
Retry Behavior

If a job fails (API timeout, LLM error):
  • Transient retry: 3 attempts with 30s/60s backoff
  • Startup retry: If a job’s last run failed and the daemon restarts, the job fires immediately instead of waiting for its next scheduled window
  • Failure notifications: If a job exhausts all retries, the daemon sends a Telegram notification automatically (requires TELEGRAM_BOT_TOKEN and TELEGRAM_ALLOWED_CHAT_IDS to be configured)

​
Health Endpoint

curl http://localhost:7890/health
Returns daemon status including active jobs and Telegram listener status.

​
Next Steps

  • Creating Jobs — Define scheduled automations
  • Triggers — Cron, interval, one-shot, and webhook triggers
  • Delivery — Send job results via email, SMS, or Telegram