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.

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

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.

Note

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.

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.

Next steps

Connect a custom serverStep-by-step with the install command.

The agentFiles, flags, logs and restarts.