# The falak-agent

> Reference for falak-agent on your servers — subcommands, flags, environment variables, files, the systemd unit, logs, heartbeats and removal.

Source: https://falak.sh/docs/servers/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

```text
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

```ini title="/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

```bash
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:

   ```bash
   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//`. 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:

```bash
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.

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:

```bash
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