The falak-agent

falak-agent is the only Falak component on a managed server. This page is the operator’s reference: where it lives, how to inspect it, and how to remove it.

At a glance

Binary	/usr/local/bin/falak-agent (static Go binary, about 10 MB)
Service	falak-agent.service (/etc/systemd/system/falak-agent.service)
Memory	About 17 MB idle (GOMEMLIMIT=24MiB)
Talks to	https://agents.<panel>/agent/v1 (mutual TLS), https://<panel> (downloads, artifacts)
Listens on	unix:/run/falak/otlp.sock and 127.0.0.1:4318 (OTLP from your apps) only

Subcommands

falak-agent run        enroll if needed (FALAK_PANEL_URL + FALAK_TOKEN), then serve
falak-agent enroll     enroll only; with --token it replaces an existing identity (backup in /etc/falak/previous/)
falak-agent check      check the identity and the connection to the panel (--wait 60s retries until connected)
falak-agent install    install the binary and systemd unit, then start the service (--no-start: enable only)
falak-agent version    print the version

Flags and environment variables

Each flag has an environment variable; the unit also reads /etc/falak/agent.env if present.

Flag	Env	Default
--panel	FALAK_PANEL_URL	(enrollment only)
--token	FALAK_TOKEN	(one-time enrollment token)
--etc-dir	FALAK_ETC_DIR	/etc/falak
--state-dir	FALAK_STATE_DIR	/var/lib/falak
--run-dir	FALAK_RUN_DIR	/run/falak
--log-dir	FALAK_LOG_DIR	/var/log/falak
--sites-root	FALAK_SITES_ROOT	/srv/falak/sites
--otlp-http	FALAK_OTLP_HTTP	127.0.0.1:4318 (empty disables)
--otlp-socket	FALAK_OTLP_SOCKET	/run/falak/otlp.sock (empty disables)
--caddy-admin	FALAK_CADDY_ADMIN	http://127.0.0.1:2019
--docker-socket	FALAK_DOCKER_SOCKET	/var/run/docker.sock
--heartbeat	FALAK_HEARTBEAT	15s
--poll-wait	FALAK_POLL_WAIT	30 (seconds)
--log-level	FALAK_LOG_LEVEL	info (debug, info, warn, error)
--insecure-enroll	FALAK_INSECURE_ENROLL=1	off (development only)

Files

Path	Contents
/etc/falak/	agent.key, agent.crt, ca.crt (Fleet CA), agent.json, telemetry.json, certs/
/var/lib/falak/	Process and cron state, the OTLP disk buffer
/run/falak/otlp.sock	OTLP socket for your apps
/var/log/falak/	Logs of supervised programs
/var/log/falak/access/<site>.log	Caddy access log per site (JSON, 10 MB × 3 rotation)
/srv/falak/sites/<site>/	Releases, shared files, current
/usr/local/bin/falak-agent.prev	The previous binary after an upgrade

The systemd unit

/etc/systemd/system/falak-agent.service (excerpt)

[Service]
Type=simple
ExecStart=/usr/local/bin/falak-agent run
EnvironmentFile=-/etc/falak/agent.env
Restart=always
RestartSec=5
KillMode=mixed
TimeoutStopSec=90
LimitNOFILE=65536
Environment=GOMEMLIMIT=24MiB

KillMode=mixed sends SIGTERM to the agent only, so its supervisor can stop your programs gracefully. Restarting the agent restarts supervised programs (workers, daemons, web processes).

Inspect

systemctl status falak-agent
journalctl -u falak-agent -f          # JSON logs
falak-agent version

The server page shows the agent’s status (online/offline), last heartbeat, version and whether an update is available.

Heartbeats and offline detection

The agent sends a heartbeat every 15 seconds with host facts and a metrics summary. After 60 seconds without one (FALAK_AGENT_OFFLINE_AFTER on the control plane), the agent is offline and the Server agent offline alert (fleet.agent_offline, critical) fires. Server agent back online follows.

Host facts (OS, CPU, memory, installed runtimes, host.name) are re-collected every 5 minutes.

Commands across restarts

Each agent process has a session id. Commands delivered to a previous process are re-delivered when safe to repeat (Caddy routes, telemetry, processes, cron, firewall and other *.apply state) or fail with “The agent restarted before running the command” (deploy steps, scripts). A command never acknowledged is handled the same way after 90 seconds (FALAK_AGENT_COMMAND_LEASE).

Certificates

The agent certificate is valid for 90 days and renewed automatically through POST /agent/v1/renew. The Fleet CA is valid for 10 years.

Remove the agent

1. Delete the server in Falak (this revokes the agent; for cloud servers it also destroys the machine by default).

2. On a machine you keep:

   sudo systemctl disable --now falak-agent
   sudo rm -f /usr/local/bin/falak-agent /usr/local/bin/falak-agent.prev /etc/systemd/system/falak-agent.service
   sudo rm -rf /etc/falak

Your sites under /srv/falak/sites, Caddy/FrankenPHP and installed packages stay until you remove them.

Reconnect a machine

To connect a machine again, for example after you deleted its server in Falak, create the server and run its new install command on the machine. The install command stops the running agent, enrolls with the new token and moves the old identity (key, certificates, agent.json and the old agent’s telemetry and command state) to /etc/falak/previous/<UTC time>/. Your sites and installed packages stay. The command ends only when the new agent is connected.

While a machine still has a deleted server’s identity, the agent logs once every 10 minutes: this agent was revoked or its server was removed from Falak; run a new install command from the panel to connect this machine again.

To check an agent at any time:

sudo falak-agent check

It prints the agent id when the panel accepts it, or the reason when it doesn’t: revoked identity, agents host unreachable, TLS error or clock skew.

Falak before v0.5.2

Older install commands enroll only when /etc/falak has no identity, so the agent keeps the deleted server’s certificate and the new server stays Waiting for agent. Move the old identity aside first, then run a freshly generated install command:

sudo systemctl stop falak-agent
sudo mkdir -p /root/falak-old
sudo mv /etc/falak/agent.key /etc/falak/agent.crt /etc/falak/ca.crt /etc/falak/agent.json /root/falak-old/

Next steps

Agent upgradesUpgrade one or all agents from the UI or API.

ArchitectureThe agent protocol.