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

​
Starting the Daemon

​
Managing the Daemon

​
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
  6. Serves /api/chat — a conversational HTTP endpoint that accepts free-form prompts and returns agent replies. Shares the same unified cross-channel conversation brain as Telegram, email, and SMS. Useful for integrating Fliiq with external clients (e.g. an iOS Shortcut via Siri over Tailscale).

​
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

Returns daemon status including active jobs, Telegram listener status, and the bind host.

​
Chat API (/api/chat)

The daemon exposes a conversational endpoint for external clients:
The /api/chat endpoint shares the same unified cross-channel conversation brain as Telegram, email, and SMS — so replies can reference prior turns from any channel. It’s designed for use with iOS Shortcuts (trigger via Siri over Tailscale) but works with any HTTP client. All /api/* routes require a Bearer token from ~/.fliiq/daemon.secret.

​
Next Steps

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