File: docs\admin\actions\installation\binary.md

---
title: 'Installation from binary'
license: 'CC-BY-SA-4.0'
---

## System requirements

Forgejo Runner requires that Git is installed, and has been tested with a minimum version of Git 2.24.3.

## Downloading and installing the binary

Download the latest [binary release](https://code.forgejo.org/forgejo/runner/releases) and verify its signature:

```shell
$ export ARCH=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
$ export RUNNER_VERSION=$(curl -X 'GET' https://data.forgejo.org/api/v1/repos/forgejo/runner/releases/latest | jq .name -r | cut -c 2-)
$ export FORGEJO_URL="https://code.forgejo.org/forgejo/runner/releases/download/v${RUNNER_VERSION}/forgejo-runner-${RUNNER_VERSION}-linux-${ARCH}"
$ wget -O forgejo-runner ${FORGEJO_URL} || curl -o forgejo-runner ${FORGEJO_URL}
$ chmod +x forgejo-runner
$ wget -O forgejo-runner.asc ${FORGEJO_URL}.asc || curl -o forgejo-runner.asc ${FORGEJO_URL}.asc
$ gpg --keyserver hkps://keys.openpgp.org --recv EB114F5E6C0DC2BCDD183550A4B61A2DC5923710
$ gpg --verify forgejo-runner.asc forgejo-runner && echo "✓ Verified" || echo "✗ Failed"
Good signature from "Forgejo <contact@forgejo.org>"
        aka "Forgejo Releases <release@forgejo.org>"
✓ Verified
```

Next, copy the downloaded binary to `/usr/local/bin` and make it executable:

```shell
$ cp forgejo-runner /usr/local/bin/forgejo-runner
```

You should now be able to test the runner by running `forgejo-runner -v`:

```
$ forgejo-runner -v
forgejo-runner version v12.7.3
```

## Setting up the runner user

Set up the user to run the daemon:

```shell
$ useradd --create-home runner
```

If the runner will be using Docker, ensure the `runner` user has access to
the docker socket. Run the following command to grant access to the docker socket:

```shell
$ usermod -aG docker runner
```

If the runner will be using Podman, no particular permissions are
needed, but you will need to configure your system to run the Podman
service. See the [Podman](#podman) section below for more information.

## Setting up the container environment

The Forgejo Runner relies on application containers (Docker, Podman, etc.) or system containers (LXC) to execute a
workflow in an isolated environment. They need to be installed and configured independently.

It is common for workflows to also require interaction with a container environment, for example to execute `docker
build` commands. This is distinct from how Forgejo Runner itself executes jobs, and is an optional configuration that is
described in detail in [Utilizing Docker within Actions](../../docker-access/).

### Docker

See the [Docker installation](https://docs.docker.com/engine/install/) documentation for more information.

### Podman

On most recent Linux distributions, the `podman` package alone should
give you a working version of Podman which can run as the unprivileged
`runner` user. You _do not_ need to install any supplemental packages
for Docker compatibility or "rootless" operation. However, some
configuration is necessary to ensure that the runner is started at
boot time and can access the Podman service.

These instructions are for Debian 13 (trixie) but should also apply to
Ubuntu, and likely to other `systemd` based distributions. They
assume you have downloaded and installed the `forgejo-runner` and
created the `runner` user as described above.

First, install `podman`:

```shell
sudo apt install podman
```

Next, you will configure `systemd` to create a socket which will launch
Podman as the `runner` user when accessed by `forgejo-runner`. As your
normal user (it is _not_ necessary to enable logins for `runner`),
run:

```shell
sudo systemctl --user -M runner@ enable --now podman.socket
```

Verify that the socket is enabled and find its location:

```console
$ sudo systemctl --user -M runner@ status podman.socket
● podman.socket - Podman API Socket
     Loaded: loaded (/usr/lib/systemd/user/podman.socket; enabled; preset: enabled)
     Active: active (listening) since Wed 2026-04-29 16:47:03 EDT; 78ms ago
 Invocation: 18779cd4131144e197422ade1c100a0e
   Triggers: ● podman.service
       Docs: man:podman-system-service(1)
     Listen: /run/user/1004/podman/podman.sock (Stream)
```

Use the path to this socket shown above in the `docker_host` parameter
when [configuring the runner](#podman-socket-configuration).

Finally, you must set the `runner` user to "linger" so that the socket
will be created at boot:

```shell
sudo loginctl enable-linger runner
```

On non-systemd distributions, you are free to choose any path you like
for the podman socket (for instance, `/home/runner/podman.sock`). It
can then be provided by running, as the `runner` user:

```shell
podman system service -t 0 unix:///home/runner/podman.sock
```

See the documentation for your distribution's init system for how to
ensure this is started at boot time.

### LXC

For jobs to run in LXC containers, the Forgejo Runner needs passwordless sudo access for all `lxc-*` commands on a
Debian GNU/Linux `bookworm` system where [LXC](https://linuxcontainers.org/lxc/) is installed. The [LXC
helpers](https://code.forgejo.org/forgejo/lxc-helpers/) can be used as follows to create a suitable container:

```shell
$ git clone https://code.forgejo.org/forgejo/lxc-helpers
$ sudo cp -a lxc-helpers/lxc-helpers{,-lib}.sh /usr/local/bin
$ lxc-helpers.sh lxc_container_create myrunner
$ lxc-helpers.sh lxc_container_start myrunner
$ lxc-helpers.sh lxc_container_user_install myrunner 1000 debian
```

> **NOTE:** Multiarch [Go](https://go.dev/) builds and [binfmt](https://github.com/tonistiigi/binfmt) need `bookworm` to
> produce and test binaries on a single machine for people who do not have access to dedicated hardware.

The Forgejo Runner can then be installed and run within the `myrunner` container.

```shell
$ lxc-helpers.sh lxc_container_run forgejo-runners -- sudo --user debian bash
$ sudo apt-get install docker.io wget gnupg2
$ wget -O forgejo-runner https://code.forgejo.org/forgejo/runner/releases/download/v12.7.3/forgejo-runner-12.7.3-linux-amd64
...
```

> **Warning:** LXC containers do not provide a level of security that makes them safe for potentially malicious users to
> run jobs. They provide an excellent isolation for jobs that may accidentally damage the system they run on.

### Host

There are no requirements for jobs that run directly on the host.

> **Warning:** there is no isolation at all and a single job can permanently destroy the host.

> **Warning:** processes forked out of a job may linger after the job is complete, possibly forever, if the job fails to
> wait for them to complete.

## Configuration

As the `runner` user, generate the default configuration file for
Forgejo Runner, and store it in a file accessible to the user
(`/home/runner/runner-config.yml` for instance):

```shell
forgejo-runner generate-config > /home/runner/runner-config.yml
```

Forgejo Runner needs to be configured and registered with Forgejo before it can be started successfully. [Configure
Forgejo Runner](../../configuration/#initial-configuration), editing `/home/runner/runner-config.yml` file as you
proceed.

> **NOTE**: Forgejo Runner requires the configuration file to be explicitly specified with the `-c` command-line
> option. There is no default configuration file location.

### Podman socket configuration

When using Podman, you must configure the `docker_host` parameter in
the `container` section of the configuration file with the path to the
Podman socket created [above](#podman). For example, if the output of
`systemctl` shows the socket as `/run/user/1004/podman/podman.sock`,
then the configuration would be:

```yaml
container:
  docker_host: unix:///run/user/1004/podman/podman.sock
```

You can also set this with the `DOCKER_HOST` environment variable.

As a reminder, to find the path to the podman socket, as the `runner`
user, you can run:

```shell
XDG_RUNTIME_DIR=/run/user/$(id -u) systemctl --user status podman.socket
```

Note that the `XDG_RUNTIME_DIR` environment variable required by
`systemctl` is _not_ set in non-login shells.

## Starting the runner

After the runner has been registered, it can be started by running `forgejo-runner daemon` as the `runner` user, in the
home directory:

```shell
$ whoami
runner
$ pwd
/home/runner
$ forgejo-runner daemon -c runner-config.yml
INFO[2024-09-14T19:19:14+02:00] Starting runner daemon
```

## Running as a systemd service

To automatically start the runner when the system starts, copy
[forgejo-runner.service](https://code.forgejo.org/forgejo/runner/raw/branch/main/contrib/forgejo-runner.service) to
`/etc/systemd/system/forgejo-runner.service`.

Then run `systemctl daemon-reload` to reload the unit files. Run `systemctl start forgejo-runner.service` to test the
new service. If everything works, run `systemctl enable forgejo-runner.service` to enable auto-starting the service on
boot.

Use `journalctl -u forgejo-runner.service` to read the runner logs.