Add your first agent to actuated¶

actuated is split into three parts:

An Actuated Agent (agent) that you run on your own machines or VMs (server), which can launch a VM with a single-use GitHub Actions runner.
A VM image launched by the agent, with all the preinstalled software found on a hosted GitHub Actions runner.
Our own control plane that talks to GitHub on your behalf, and schedules builds across your fleet of agents.

All we need you to do is to install our agent on one or more servers, then we take care of the rest. We'll even be able to tell you if your server goes offline for any reason.

Have you registered your organisation yet?

Before you can add an agent, you or your GitHub organisation admin will need to install the: Actuated GitHub App.

Pick your Actuated Servers¶

Pick your Actuated Servers carefully using our guide: Pick a host for actuated

Review the End User License Agreement (EULA)¶

Make sure you've read the Actuated EULA before registering your organisation with the actuated GitHub App, or starting the agent binary on one of your hosts.

If you missed it in the "Provision a Server" page, we recommend you use Ubuntu 22.04 as the host operating system on your Server.

Install the Actuated Agent¶

Download the Actuated Agent and installation script to the server

Setting up an ARM64 agent? Wherever you see agent in a command, change it to: agent-arm64. So instead of agent keygen you'd run agent-aarch64 keygen.

Install crane:
```
(
curl -sLS https://get.arkade.dev | sudo sh
arkade get crane
sudo mv $HOME/.arkade/bin/crane /usr/local/bin/
)
```
Download the latest agent and install the binary to /usr/local/bin/:
```
(
rm -rf agent || :
mkdir -p agent

crane export ghcr.io/openfaasltd/actuated-agent:latest | tar -xvf - -C ./agent
sudo mv ./agent/agent* /usr/local/bin/
)
```
Run the setup.sh script which will install all the required dependencies like containerd, CNI and Firecracker.
```
(
cd agent
sudo ./install.sh
mkdir -p ~/.actuated
)
```
Create a file to store your license. If you don't have it handy, check your email for your receipt. If someone else in your organisation purchased the subscription, they should be able to forward it to you.

Run the following, then paste in your license, hit enter once, then Control + D.
```
cat > $HOME/.actuated/LICENSE
```
Generate your enrollment file

You'll need to create a DNS A or CNAME record for each server you add to actuated, this could be something like server1.example.com for instance.

Run the following to create an enrollment file at $HOME/.actuated/agent.yaml:
```
agent enroll --url https://server1.example.com
```
The enrollment file contains:
- The hostname of the server
- The public key of the agent which we use to encrypt tokens sent to the agent to bootstrap runners to GitHub Actions
- A unique API token encrypted with our public key, which is used by the control plane to authenticate each message sent to the agent
Expose the agent's endpoint using HTTPS

The actuated control plane will only communicate with a HTTPS endpoint to ensure properly encryption is in place. An API token is used in addition with the TLS connection for all requests.

In addition, any bootstrap tokens sent to the agent are further encrypted with the agent's public key.

For hosts with public IPs, you will need to use the built-in TLS provisioning with Let's Encrypt. For hosts behind a firewall, NAT or in a private datacenter, you can use inlets to create a secure tunnel to the agent.

We're considering other models for after the pilot, for instance GitHub's own API has the runner make an outbound connection and uses long-polling.

See also: expose the agent with HTTPS
Start the agent

We suggest starting the agent through a script or tmux session initially, then once we've confirmed it's enrolled correctly, switch over to systemd.

The easiest way to configure everything is to run as root, however, you can also use a non-root user with passwordless sudo, if you prefer.

These steps are for hosts with public IP addresses, if you want to use inlets, jump to the end of this step.

For an x86_64 server, add the following to: /root/start.sh:
```
#!/bin/bash

echo Running Agent from: ./agent
DOMAIN=agent1.example.com

sudo -E agent up \
    --image-ref=ghcr.io/openfaasltd/actuated-ubuntu20.04:x86-64-latest \
    --kernel-ref=ghcr.io/openfaasltd/actuated-kernel-5.10.77:x86-64-latest \
    --letsencrypt-domain $DOMAIN \
    --letsencrypt-email webmaster@$DOMAIN
```
For an Arm64 server, add the following to /root/start.sh instead:
```
#!/bin/bash

echo Running Agent from: ./agent
DOMAIN=agent1.example.com

sudo -E agent-arm64 up \
    --image-ref=ghcr.io/openfaasltd/actuated-ubuntu20.04:aarch64-latest  \
    --kernel-ref=ghcr.io/openfaasltd/actuated-kernel-5.10.77:aarch64-latest \
    --letsencrypt-domain $DOMAIN \
    --letsencrypt-email webmaster@$DOMAIN
```
Note the different binary name: agent-arm64 and suffix on the image references: aarch64-latest.

For an Actuated Agent behind an inlets tunnel, do not include the --letsencrypt-* flags, and instead add --listen-addr 127.0.0.1:.

Check that the control-plane is accessible

curl -i https://server1.example.com

A correct response is a 403.

If you see the expected response, go ahead and install the service as a systemd service:

sudo agent install-service \
    --path /root/start.sh \
    --user root

Check the service's status with:

sudo systemctl status actuated
sudo journalctl -u actuated --since today -f

Send us your agent's connection info

Share the $HOME/.actuated/agent.yaml file with us so we can add your agent to the actuated control plane.

We'll let you know once we've added your agent to actuated and then it's over to you to start running your builds.

Once you've run our test build, you need to run the steps for systemd mentioned above.

Next steps¶

You can now start your first build and see it run on your actuated agent.

Start a build on your agent