# Servers and agents

> What a Falak server is, how the falak-agent enrolls and stays connected, what it manages on the machine, and the lifecycle states a server goes through.

Source: https://falak.sh/docs/concepts/servers-and-agents/

A **server** is a Linux machine that Falak manages. The **agent**, `falak-agent`, is the program on that machine that does the work. This page explains how they relate and what the agent is responsible for.

## Server lifecycle

| Status | Meaning |
|---|---|
| `creating` | The machine is being created at the provider, or Falak waits for the agent to enroll (custom servers) |
| `provisioning` | The agent is applying the provisioning plan (packages, runtimes, users, firewall, SSH) |
| `active` | Ready. Sites and databases can be placed on it. |
| `error` | Provisioning or creation failed. The server page shows the message and output. |
| `deleting` | Being removed |

Separately, the **agent** is `online` or `offline`. It is offline after 60 seconds without a heartbeat.

## Server types

The type decides what provisioning installs and what the server can host:

| Type | API value | Hosts sites | Serves HTTP | Allowed software |
|---|---|---|---|---|
| App server | `app` | yes | yes | PHP, Node, database, cache, Docker |
| Web server | `web` | yes | yes | PHP, Node, Docker |
| Database server | `db` | no | no | Database |
| Cache server | `cache` | no | no | Redis or Valkey |
| Worker server | `worker` | yes | no | PHP, Node, Docker |
| Load balancer | `lb` | no | yes | (Caddy only) |
| Builder | `builder` | no | no | Node, Docker |

More in [Server types](/docs/servers/server-types/).

## What the agent does

The agent is a single static Go binary (about 10 MB, about 17 MB of RAM idle). It runs as the systemd service `falak-agent` and:

- **Provisions** the machine from a declarative plan: apt packages, users, PHP versions, FrankenPHP or Caddy, Node.js, databases, services, unattended upgrades and SSH settings.
- **Configures the edge**: it applies the full Caddy route set for all sites on the server atomically through the Caddy admin API.
- **Deploys** releases: fetch, prepare, run deploy hooks, activate, roll back, prune; swaps containers and runs Compose projects.
- **Supervises processes** with a built-in supervisor (web processes, queue workers, Horizon, Octane, daemons) and runs **cron** jobs with a built-in scheduler that reports heartbeats.
- **Manages the firewall** (nftables), WireGuard private networks, databases and database users, and backups.
- **Collects telemetry**: host metrics from `/proc`, log files, journald and container logs, and receives OTLP from your apps on `unix:/run/falak/otlp.sock` and `127.0.0.1:4318`, then forwards everything to the observability stack.
- **Opens terminal sessions** for the web terminal.

State-style commands (`proc.apply`, `cron.apply`, `edge.caddy.apply`, `net.firewall.apply`) always carry the full desired state, so re-running them is safe and the agent converges.

## Enrollment

```text title="What the install command does"
curl -fsSL https://<panel>/install/<token> | sudo sh
  1. checks root, systemd, Linux, CPU architecture (amd64/arm64)
  2. downloads /usr/local/bin/falak-agent from your panel (SHA-256 verified)
  3. falak-agent enroll --panel https://<panel> --token <token>   → certificate in /etc/falak
  4. falak-agent install   → writes the systemd unit, enables and starts it
```

The token is single-use and expires after 24 hours (`FALAK_INSTALL_TOKEN_TTL`, in minutes). After enrollment, the server moves to `provisioning` automatically.

Agent binaries come from **your** control plane (`/install/agent/linux-amd64` and `/install/agent/linux-arm64`), not from GitHub. Servers never need to reach GitHub to install the agent.

## Trust model

- The agent verifies the agent API with Falak's **Fleet CA**, not with public CAs.
- The control plane identifies the agent by its client certificate.
- The Fleet CA private key is stored in the control plane database, encrypted with `APP_KEY`. Losing the database or `APP_KEY` means re-enrolling every server; see [Backup and restore](/docs/operations/backup-restore/).

## The agent never builds

Managed servers only fetch finished artifacts or images. Builds run on the builder on the control plane host, or on a `builder` server. See [Builds](/docs/concepts/builds/).

## Next steps