# Connect your own server

> Connect any Ubuntu server to Falak with a one-line install command — what it does, expected output, provisioning, expired tokens and enrollment fixes.

Source: https://falak.sh/docs/servers/connect-custom-server/

"Custom" servers are machines you already have: a VPS from any provider, a dedicated server, a VM on-premises. You create the server in Falak, run one command on the machine, and Falak takes it from there.

## Prerequisites

- A fresh **Ubuntu LTS** machine (24.04 recommended), amd64 or arm64, with systemd.
- Root or sudo access, and `curl` or `wget`.
- Outbound HTTPS from the machine to your panel (`https://falak.example.com`) and to `https://agents.falak.example.com`.
- The machine is **not** the control plane host.

See [Requirements](/docs/getting-started/requirements/#managed-servers).

## Connect

1. Open **Servers → Create**.

2. Fill in:

   | Field | Notes |
   |---|---|
   | Name | Letters, digits, spaces, `.`, `_`, `-`; unique; becomes the hostname (for example `app-1`) |
   | Type | What the server is for. See [Server types](/docs/servers/server-types/). |
   | Provider | **Custom (bring your own server)** |
   | Timezone | Default `UTC` |
   | Software | PHP runtime and versions, Node.js, database, cache, Docker (only options the type allows) |
   | SSH keys | Organization keys to install for the `falak` user |

3. Click **Create server**. The server is `creating` and the page shows the install command:

   ```bash
   curl -fsSL https://falak.example.com/install/<token> | sudo sh
   ```

4. Run it on the machine:

   ```text title="Expected output"
   falak: downloading falak-agent (amd64)
   falak: enrolling with https://falak.example.com
   falak: falak-agent installed and running
   ```

5. The server turns `provisioning`. Follow the output on the server page. When it turns `active`, you can place sites and databases on it.

![A server page: status, agent version and heartbeat, resource usage, provisioning output and tabs for metrics, processes, firewall, network, terminal, SSH keys, recipes, PHP and settings.](./_images/servers-server.png)

## What the install command does

1. Checks before it changes anything: root, Linux with systemd and apt, amd64 or arm64, the OS (Ubuntu 22.04, 24.04 and 26.04 are supported; other versions and Debian get a warning), that your panel and `agents.<panel>` answer, and that the clock is within 5 minutes of the panel's (mutual TLS needs it).
2. Downloads `falak-agent` from **your panel** (`/install/agent/linux-<arch>`) and verifies its SHA-256.
3. Installs it to `/usr/local/bin/falak-agent`.
4. If the machine was connected before, stops the running agent. Its old identity is replaced and backed up in `/etc/falak/previous/` (see [Reconnect a machine](/docs/servers/agent/#reconnect-a-machine)).
5. Runs `falak-agent enroll --panel https://falak.example.com --token <token>`: generates a key, sends a CSR and host facts, and stores the signed certificate in `/etc/falak`.
6. Runs `falak-agent install`: writes `/etc/systemd/system/falak-agent.service`, enables and starts it.
7. Runs `falak-agent check --wait 60s` and prints `falak-agent connected as <agent id>`. If the agent can't connect, the command fails with the reason.

Then Falak runs the [machine check](/docs/servers/machine-check/) and, when nothing blocks, sends the provisioning plan. See [Provisioning](/docs/servers/provisioning/).

## Install tokens

- A token works **once** and expires after **24 hours** (`FALAK_INSTALL_TOKEN_TTL`, in minutes).
- Regenerate the command on the server page if it expired (permission `fleet.agents.manage`).
- Issuing a token is recorded in the audit log.

## Through the API

```bash
curl -X POST https://falak.example.com/api/v1/servers \
  -H "Authorization: Bearer $FALAK_TOKEN" -H "Accept: application/json" -H "Content-Type: application/json" \
  -d '{"name": "app-1", "type": "app", "provider": "custom",
       "stack": {"php": {"runtime": "frankenphp", "versions": ["8.4"], "default": "8.4"}, "node": "22", "database": "postgresql"}}'
```

The response (`201`) includes `install_command` for custom servers. See [Servers API](/docs/api/servers/).

## Troubleshooting

| Symptom | Fix |
|---|---|
| `falak: error: run as root` | Use `sudo sh` at the end of the command. |
| `systemd is required` | Containers without systemd are not supported. |
| `download failed` | The machine cannot reach your panel over HTTPS, or the panel's certificate is not publicly trusted (for example `--tls internal`). |
| `enrollment failed` | The token was used or expired, or `https://agents.<panel>` is unreachable. On the control plane host run `falak-ctl doctor`; the agent API must answer `401` without a client certificate. |
| Stuck in `provisioning` | Open the server page for the output. Transient download errors are retried with backoff. |
| Server `error` | Fix the cause shown, then **Re-provision** from the server page. |
| Server stays **Waiting for agent** after you deleted it and ran a new install command on the same machine | From v0.5.2 the install command replaces the old identity by itself. With an older Falak, move the old identity aside first: see [Reconnect a machine](/docs/servers/agent/#reconnect-a-machine). |
| Install command ends with `falak-agent is installed but not connected` | It prints the reason from `falak-agent check`: revoked identity, `agents.<panel>` unreachable, TLS error or clock skew. Run `sudo falak-agent check` again; logs: `journalctl -u falak-agent`. |
| `this machine's clock is …s off the panel's` | Turn on time sync: `sudo timedatectl set-ntp true`, then run the install command again. |
| Provisioning step `apt`, `caddy` or `php:<version>` fails on `apt-get update` | The error names the repository and its file under `/etc/apt/sources.list.d`. Fix or remove that file, then **Re-provision**. A `ppa:ondrej/php` source with no release for the server's Ubuntu (for example 26.04) is disabled automatically (renamed to `<file>.disabled-by-falak`). |
| `PHP 8.4 is not available on Ubuntu 26.04; installing PHP 8.5 instead` | The PHP PPA has no packages for Ubuntu 26.04 yet, so PHP comes from Ubuntu's archive, which has only PHP 8.5. Use Ubuntu 24.04 if you need another version. |

## Next steps