Skip to content

enhancement: Add fly agent run, the base of the monitoring agent #26

Closed

Description

@nabil1440

Blocker: yes. #27, #28 and #29 need this.

Part of the monitoring agent (contract v0.2.1). Order: #26 → #27 → #28 → #29 → #30, with #9.

Defect

  • fly has no agent mode. The monitoring agent contract requires the command fly agent run.
  • The FlyWP installer writes the systemd unit fly-agent.service. The unit starts ~fly/.fly/bin/fly agent run. With the current fly, the unit fails at each start.

Cost

  • FlyWP cannot turn on the install job. Thus, no server sends data.

Benefit of the fix

Fix

  1. Add the command fly agent run. Do not mark it as a command that needs Docker. The agent must operate when Docker is down.
  2. Keep the current root check. The agent operates as the server user.
  3. Read FLY_AGENT_URL, FLY_AGENT_TOKEN and FLY_AGENT_SERVER_ID from the environment. Read the state folder from STATE_DIRECTORY. If a value is not set or not valid, stop with an error that names the value.
  4. Accept only an https:// URL.
  5. Lock a file in the state folder. If a different agent has the lock, stop with an error.
  6. Start each cycle at FLY_AGENT_SERVER_ID % 60 seconds past the minute.
  7. Use the report interval N (1 to 10) from the last reply. Keep it in the state folder. Use 1 until the first reply.
  8. Make one HTTP client for all requests: the bearer token, a timeout and the User-Agent fly/<version>.
  9. Send agent_version as version.Version. make release puts the release tag in it.
  10. On SIGTERM, save the state and stop in less than 10 seconds.

Completion checks

  • The unit from the FlyWP installer starts the agent, and systemctl is-active fly-agent shows active.
  • An agent without FLY_AGENT_TOKEN stops with an error that names the value.
  • A second fly agent run stops with an error.
  • The agent operates when Docker is stopped.
  • The agent does not operate as root.
  • No log line contains the token (a test examines this).
  • The tests use a fake control plane (an httptest TLS server).

Activity

  1. self-assigned this
    on Sep 22, 2026
  2. changed the title [-]Add `fly agent run`, the base of the monitoring agent[/-] [+]enhancement: Add `fly agent run`, the base of the monitoring agent[/+] on Oct 1, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

enhancementNew feature or request

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions