> For the complete documentation index, see [llms.txt](https://docs.reviactyl.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.reviactyl.app/project/agent/installing-agent.md). # Installing Agent Agent is the next generation server control plane from Reviactyl. It is the fork of Pterodactyl agent with additional features. ## Supported Systems The following is a list of supported operating systems. Please be aware that this is not an exhaustive list, there is a high probability that you can run the software on other Linux distributions without much effort. You are responsible for determining which packages may be necessary on those systems. There is also a very high probability that new releases of the supported OSes below will work just fine, you are not restricted to only the versions listed below. | Operating System | Version | Status | Notes | | ---------------------------------- | ------- | --------------- | --------------------------------------------------- | | **Ubuntu** | 20.04 | Fully Supported | | | | 22.04 | Fully Supported | | | | 24.04 | Fully Supported | | | | 26.04 | Fully Supported | Documentation was written using 26.04 LTS | | **RHEL / Rocky Linux / AlmaLinux** | 8 | Fully Supported | | | | 9 | Fully Supported | | | **Debian** | 11 | Fully Supported | | | | 12 | Fully Supported | | | | 13 | Fully Supported | | | **Windows** | All | Not Supported | *Windows support will be added in future releases*. | | **MacOS** (M1 or Later) | All | Not Supported | *MacOS support will be added in future releases*. | ## System Requirements To run Agent, you will need a Linux system capable of running Docker containers. Most VPS and almost all dedicated servers should be capable of running Docker, but there are edge cases. When your provider uses `Virtuozzo`, `OpenVZ` (or `OVZ`), or `LXC` virtualization, you will most likely be unable to run Agent. Some providers have made the necessary changes for nested virtualization to support Docker. Ask your provider's support team to make sure. KVM is guaranteed to work. The easiest way to check is to type `systemd-detect-virt`. If the result doesn't contain `OpenVZ` or`LXC`, it should be fine. The result of `none` will appear when running dedicated hardware without any virtualization. Should that not work for some reason, or you're still unsure, you can also run the command below. ```shell admin@reviactyl:~$ sudo dmidecode -s system-manufacturer VMware, Inc. ``` ## Dependencies * curl * Docker ### Installing Docker For a quick install of Docker CE, you can execute the command below: ```shell curl -sSL https://get.docker.com/ | CHANNEL=stable bash ``` If you would rather do a manual installation, please reference the [official Docker documentation](https://docs.docker.com/engine/install/) for how to install Docker CE on your server. {% hint style="warning" %} **Check your Kernel** Please be aware that some hosts install a modified kernel that does not support important docker features. Please check your kernel by running `uname -r`. If your kernel ends in `-xxxx-grs-ipv6-64` or `-xxxx-mod-std-ipv6-64` you're probably using a non-supported kernel. {% endhint %} #### Start Docker on Boot If you are on an operating system with systemd (Ubuntu 16+, Debian 8+, CentOS 7+) run the command below to have Docker start when you boot your machine. ```shell sudo systemctl enable --now docker ``` #### Enabling Swap {% hint style="info" %} **Recent Linux kernel** Since the version 6.1 of the Linux kernel, swap is enabled by default. If you are running a kernel version 6.1 or newer, you can skip this step. To check your kernel version, run `uname -r`. {% endhint %} On most systems, Docker will be unable to setup swap space by default. You can confirm this by running `docker info` and looking for the output of `WARNING: No swap limit support` near the bottom. Enabling swap is entirely optional, but we recommended doing it if you will be hosting for others and to prevent OOM errors. To enable swap, open `/etc/default/grub` as a root user and find the line starting with `GRUB_CMDLINE_LINUX_DEFAULT`. Make sure the line includes `swapaccount=1` somewhere inside the double-quotes. After that, run `sudo update-grub` followed by `sudo reboot` to restart the server and have swap enabled. Below is an example of what the line should look like, *do not copy this line verbatim. It often has additional OS-specific parameters.* ```shell GRUB_CMDLINE_LINUX_DEFAULT="swapaccount=1" ``` {% hint style="info" %} **GRUB Configuration** Some Linux distros may ignore `GRUB_CMDLINE_LINUX_DEFAULT`. Therefore you might have to use `GRUB_CMDLINE_LINUX` instead should the default one not work for you. {% endhint %} ## Installing Agent The first step for installing Agent is to ensure we have the required directory structure setup. To do so, run the commands below, which will create the base directory and download the agent executable. ```shell sudo mkdir -p /etc/reviactyl curl -L -o /usr/local/bin/agent "https://github.com/reviactyl/agent/releases/latest/download/agent_linux_$([[ "$(uname -m)" == "x86_64" ]] && echo "amd64" || echo "arm64")" sudo chmod u+x /usr/local/bin/agent ``` {% hint style="info" %} **OVH/SYS Servers** If you are using a server provided by OVH or SoYouStart please be aware that your main drive space is probably allocated to `/home`, and not `/` by default. Please consider using `/home/daemon-data` for server data. This can be easily set when creating the node. {% endhint %} ## Configure Once you have installed Agent and the required components, the next step is to create a node on your installed Panel. Go to your Panel administrative view, select Nodes from the sidebar, and on the right side click Create New button. After you have created a node, click on it and there will be a tab called Configuration. Copy the code block content, paste it into a new file called `config.yml` in `/etc/reviactyl` and save it. Alternatively, you can click on the Generate Token button, copy the bash command and paste it into your terminal. ![configuration](https://content.gitbook.com/content/l4piqh8dSDm75K0vkSJ8/blobs/klTGzQ9KoVMuPMmVLeky/image) {% hint style="warning" %} **SSL Certificates** When your Panel is using SSL, the Agent must also have one created for its FQDN. See [Creating SSL Certificates](https://reviactyl.app/tutorials/creating-ssl-certificates) documentation page for how to create these certificates before continuing. {% endhint %} ### Starting Agent To start Agent, simply run the command below, which will start it in a debug mode. Once you confirmed that it is running without errors, use `CTRL+C` to terminate the process and daemonize it by following the instructions below. Depending on your server's internet connection pulling and starting Agent for the first time may take a few minutes. ```shell sudo agent --debug ``` You may optionally add the `--debug` flag to run Agent in debug mode. ### Daemonizing (using systemd) Running Agent in the background is a simple task, just make sure that it runs without errors before doing this. Place the contents below in a file called `agent.service` in the `/etc/systemd/system` directory. {% code title="agent.service" %} ```ini [Unit] Description=Reviactyl Agent After=docker.service Requires=docker.service PartOf=docker.service [Service] User=root WorkingDirectory=/etc/reviactyl LimitNOFILE=4096 PIDFile=/var/run/agent/daemon.pid ExecStart=/usr/local/bin/agent Restart=on-failure StartLimitInterval=180 StartLimitBurst=30 RestartSec=5s [Install] WantedBy=multi-user.target ``` {% endcode %} Then, run the commands below to reload systemd and start Agent. ```shell sudo systemctl enable --now agent ``` ### Node Allocations Allocation is a combination of IP and Port that you can assign to a server. Each created server must have at least one allocation. The allocation would be the IP address of your network interface. In some cases, such as when behind NAT, it would be the internal IP. To create new allocations go to Nodes > your node > Allocation. ![allocations](https://content.gitbook.com/content/l4piqh8dSDm75K0vkSJ8/blobs/U8clycd9Ywqi0S9nir54/image) Type `hostname -I | awk '{print $1}'` to find the IP to be used for the allocation. Alternatively, you can type `ip addr | grep "inet "` to see all your available interfaces and IP addresses. Do not use 127.0.0.1 for allocations. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.reviactyl.app/project/agent/installing-agent.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.