Title: Mini PC server: build a Linux CI server for GitHub Actions
URL: https://codemany.com/articles/mini-pc-ci-server
Description: Set up a mini PC server for CI from scratch: buy a $700 box, install Ubuntu Server, add Codemany and run your GitHub Actions jobs in about 45 minutes.
All pages as Markdown: https://codemany.com/llms.txt

---

[Home](https://codemany.com/) [Articles](https://codemany.com/articles)

# Set up a mini PC server for GitHub Actions, from scratch

By [Arpit Agarwal](https://x.com/arpwal), maker of Codemany

A mini PC server in a closet can run your GitHub Actions jobs, 4 at a time. GitHub doesn't charge per minute for jobs on your own machine. This guide builds one from scratch: buy the box, install Ubuntu Server, add Codemany and run your first job. It takes about 45 minutes, plus the time to download Ubuntu. You don't need to know Linux. You type each command, and this page shows what you should see.

## What is a CI server?

A CI server is a computer that builds and tests your code each time you push. Some people call it a build server. With GitHub Actions, GitHub keeps the list of jobs, and a runner on the CI server does the work. GitHub rents you its own machines by the minute. A self-hosted runner runs on a machine you own. That is what you'll build here: self-hosted CI/CD on a mini PC.

You set it up from your laptop. After that, the mini PC asks GitHub for jobs on its own. Nothing on the internet connects in.

## What a mini PC server costs

- **The mini PC: about $700, once.** Prices change, so check before you buy.
- **Power: about $3 a month.** Reviews measure this PC at about 10 watts when idle and under 90 watts flat out. Say it averages 25 watts: 25 W × 24 hours × 30 days = 18 kWh a month. At 18 cents per kWh, that is $3.24. Even flat out all month, 90 W × 720 hours = 65 kWh, about $12. Your power bill shows your real rate.
- **Codemany:** 14 days free, no card. Then $20 a month for 2 machines.

For scale: GitHub charges $0.006 a minute for a standard Linux runner. $700 buys about 117,000 of those minutes. This box runs 4 jobs at once, all day, for as long as it lasts. To see your own numbers, try the [CI cost calculator](https://codemany.com/calculator).

## 1. Buy a mini PC and a USB stick

Any mini PC that works as a home server can be a CI server. These are the exact parts we bought:

- **MINISFORUM UM870 Slim mini PC**: AMD Ryzen 7 8745H (8 cores, 16 threads), 32 GB DDR5, 1 TB SSD. About $700.
  It runs 4 jobs at once, and it is the same box that runs our [public benchmarks](https://codemany.com/benchmarks).
  [Buy on Amazon](https://www.amazon.com/dp/B0DRVSK2T9)
- **SanDisk 32 GB Ultra USB 3.0 flash drive**
  It holds the Ubuntu installer. Any stick of 8 GB or more works. The installer erases it.
  [Buy on Amazon](https://www.amazon.com/dp/B081QSHG13)

Why this mini PC fits CI:

- **8 cores, 16 threads.** Codemany gives each job 4 threads, so it runs 4 jobs at once.
- **32 GB of memory.** Each job gets 4 GB, and 6 GB stays free for Linux itself.
- **1 TB disk.** Each job gets 15 GB. The rest holds Docker images and caches, so jobs don't download the same things every time.

Codemany works out how many jobs fit. You don't set it by hand.

You also need:

- An Ethernet cable to your router. Wired is steadier than Wi-Fi.
- A monitor, a cable that fits the PC, and a USB keyboard. You need them for the install only.
- Your laptop, on the same network.

Other machines work too. Any 64-bit mini PC Linux server (x86-64 or ARM64) will do. Size it by how many jobs you want at once:

- 2 jobs: 8 threads, 16 GB, 512 GB disk.
- 4 jobs: 16 threads, 32 GB, 1 TB disk (the box in this guide).
- 8 jobs: 32 threads, 64 GB, 1 TB disk.

**Want macOS jobs too?** Linux can't run them. They need a Mac, like the [Apple 2026 Mac mini (M6)](https://www.amazon.com/dp/B0HGGJZ92H), $779 on Amazon in November 2026. Then follow the [Mac runner guide](https://codemany.com/docs/guides/mac-runner), or [download Codemany for Mac](https://codemany.com/download).

## 2. Make the Ubuntu Server USB

Use **Ubuntu Server 24.04 LTS**. Codemany supports Ubuntu 22.04 and 24.04. LTS versions get security updates for 5 years.

1. Download Ubuntu Server
   Go to [ubuntu.com/download/server](https://ubuntu.com/download/server) and download Ubuntu Server 24.04 LTS. The file is about 3 GB. Its name looks like `ubuntu-24.04.5-live-server-amd64.iso`.
2. Check the download
   A checksum proves the file arrived whole and unchanged. Get Ubuntu's list of checksums, then compute your own. On a Mac, in Terminal:
   ```
   cd ~/Downloads
   curl -fsSLO https://releases.ubuntu.com/24.04/SHA256SUMS
   grep live-server SHA256SUMS
   shasum -a 256 ubuntu-24.04*-live-server-amd64.iso
   ```
   On Windows, in PowerShell:
   ```
   cd $HOME\Downloads
   curl.exe -fsSLO https://releases.ubuntu.com/24.04/SHA256SUMS
   Select-String live-server SHA256SUMS
   Get-FileHash ubuntu-24.04*-live-server-amd64.iso -Algorithm SHA256
   ```
   Each prints a long string of letters and numbers. The two strings must match. Windows prints capital letters, and that's fine. If they don't match, download the file again.
3. Write it to the USB stick
   Install [balenaEtcher](https://etcher.balena.io/) (free, for Mac and Windows). Open it, choose **Flash from file** and pick the .iso. Choose **Select target** and pick your USB stick. Then choose **Flash!** This erases the stick.

## 3. Set up the BIOS

The BIOS is the screen that runs before any operating system. Plug the monitor, keyboard, Ethernet cable and USB stick into the mini PC. Turn it on and press `Delete` again and again until the BIOS setup opens. If Windows starts instead, restart and press it sooner.

Change these settings. Menu names differ between BIOS versions, so look for these words:

- **Power on after a power cut.** Find **Restore on AC Power Loss**. It may be called **AC Power Recovery** or **State After G3**. Set it to **Power On** (or S0). Now the box starts by itself after an outage.
- **Boot from the USB stick.** On the Boot tab, set **Boot Option #1** to your USB stick. Or skip this, and press the boot menu key at power-on instead. On many Minisforum PCs that key is `F7`.
- **Virtualization (optional).** Check that **SVM Mode** (AMD) or **VT-x** (Intel) is **Enabled**. Codemany needs it only if you later choose a fresh virtual machine for every job.

Save and exit (often `F10`). The PC restarts from the USB stick. Leave Secure Boot as it is. Ubuntu works with it.

## 4. Install Ubuntu Server on the mini PC

**This erases the mini PC's disk**, and the Windows it came with. Copy off anything you want to keep first.

The installer is text only. Use the arrow keys to move, `Space` to tick a box and `Enter` to choose. These are the screens, in order:

1. Boot menu
   Choose **Try or Install Ubuntu Server**.
2. Language and keyboard
   Pick yours. If it offers an installer update, either choice works.
3. Type of installation
   Keep **Ubuntu Server** (not "minimized").
4. Network
   Your Ethernet port shows an address, like `192.168.1.50`. Write it down. You'll use it from your laptop.
5. Proxy and mirror
   Leave the proxy empty. Let the mirror test pass, then choose **Done**.
6. Guided storage
   Keep **Use an entire disk** and **Set up this disk as an LVM group**. The next screen shows the plan. The `ubuntu-lv` line is much smaller than your disk. That's normal, and you'll fix it in step 5. Choose **Done**, then **Continue** to confirm.
7. Profile
   Type your name, a name for the server (we use `ci-box`), a username and a password. Your jobs run as this user.
8. Ubuntu Pro
   Choose **Skip for now**.
9. SSH
   Tick **Install OpenSSH server**. This lets you log in from your laptop. If you already use an SSH key with GitHub, set the import option to **from GitHub** and type your GitHub username.
10. Featured server snaps
    Tick nothing. Codemany installs Docker and the other tools in step 6.
11. Install
    Wait for **Reboot Now** and choose it. When it asks, pull out the USB stick and press `Enter`.

## 5. First boot: log in over SSH

The mini PC starts and shows `ci-box login:`. From now on, you work from your laptop. Open Terminal on a Mac, or PowerShell on Windows, and connect to the address you wrote down:

```
ssh you@192.168.1.50
```

Use your own username and address. The first time, it asks `Are you sure you want to continue connecting`. Type `yes`, then your password. The prompt changes to `you@ci-box:~$`. You're in.

Lost the address? Log in on the mini PC itself and run `hostname -I`. The first number is the address.

### Update everything

```
sudo apt update && sudo apt full-upgrade -y
```

### Give Ubuntu the whole disk

The installer gave Ubuntu only part of the disk. Check:

```
df -h /
```

The **Size** column shows far less than your disk, often about 100G. Grow it to fill the disk:

```
sudo lvextend -r -l +100%FREE /dev/ubuntu-vg/ubuntu-lv
df -h /
```

Now **Size** shows over 900G. It works while Ubuntu runs, with no restart.

The small dark block at the left is the boot area. Leave it alone.

### Reach it by name

```
sudo apt install -y avahi-daemon
```

Now `ssh you@ci-box.local` works too. On a Mac, it works right away. On Windows, use the address if the name doesn't work. Even better: in your router's settings, reserve this address for the mini PC. Routers often call this a DHCP reservation. Then the address never changes.

To rename the box later, run `sudo hostnamectl set-hostname new-name`.

### Security updates

Ubuntu Server installs security updates by itself every day. Check that it's on:

```
systemctl is-enabled unattended-upgrades
```

It prints `enabled`.

## 6. Install Codemany, your GitHub Actions self-hosted runner

Still over SSH, run this on the mini PC:

```
curl --proto '=https' --tlsv1.2 -fsSL https://codemany.com/install.sh | sh
```

It asks for your password once. Then it:

- downloads Codemany for your CPU and checks its signed checksum,
- installs the tools Linux jobs need: git, make, gcc, Docker and QEMU,
- turns on automatic updates for Codemany,
- starts Codemany as a background service that also starts at boot.

At the end, it prints a setup link like `http://192.168.1.50:8825/#code=…`. Prefer apt? The [Codemany for Linux page](https://codemany.com/linux) has the apt repository commands. Both ways keep Codemany updated.

Open the link in your laptop's browser. The code in the link makes the page yours, so don't share it. Then:

1. Sign in with GitHub
   The page shows a code. Enter it on github.com.
2. Pick repositories
   Choose repositories, or a whole organization.
3. Install the Codemany Runners App, if asked
   Choose **Install…** and approve it on GitHub.
4. Done
   The runners start. Your 14-day trial starts too, with no card.

Lost the link? Run `codemany setup-link` to print it again.

Now restart the box once. Setup added you to the `docker` group, and jobs only get that after a restart:

```
sudo reboot
```

Wait a minute, SSH in again and check on it:

```
codemany doctor
codemany capacity
```

`codemany doctor` prints one PASS, WARN or FAIL line per check. `codemany capacity` prints how many jobs fit at once: 4 on this box.

Already run Codemany on a Mac? Add the box to its fleet. On the Mac, open **Machines**, find the box under **Nearby** and choose **Add to the fleet…**. Then run `codemany pair` on the box and type the code it prints on the Mac. To add more machines later, read [Machines](https://codemany.com/docs/machines).

## 7. Run your first job on it

In a repository you picked, add this file as `.github/workflows/hello-ci-box.yml`:

```
name: hello ci box
on: [push, workflow_dispatch]
jobs:
  hello:
    runs-on: [self-hosted, Linux, codemany]
    steps:
      - uses: actions/checkout@v4
      - run: uname -a
      - run: df -h .
      - run: docker version
```

The three labels in `runs-on` mean:

- `self-hosted`: not one of GitHub's machines.
- `Linux`: keeps the job off a Mac, if you run Codemany on one too.
- `codemany`: only runners that Codemany started.

Push it:

```
git add .github/workflows/hello-ci-box.yml
git commit -m "Try the CI box"
git push
```

Open your repository on GitHub and choose the **Actions** tab. The run turns yellow, then green. Open the job, then its first step, **Set up job**. It names the runner that took the job. You can also watch it on the box with `codemany status`, or in the dashboard at `http://ci-box.local:8825`.

To move a real workflow, change `runs-on: ubuntu-latest` to `runs-on: [self-hosted, Linux, codemany]`. Add `docker` to the list for jobs that build images. One difference: GitHub's machines come with many tools already installed. Your box has git, make, gcc and Docker. Add the rest with setup steps like `actions/setup-node`, as many workflows already do.

## 8. Keep your CI server running

- **Unplug the monitor and keyboard.** Leave the power and Ethernet cables in.
- **Give it air.** Put it on a shelf, not in a closed drawer or box. Keep the vents clear.
- **It updates itself.** Codemany checks for a new version every hour. It installs it once running jobs finish. Ubuntu installs its own security updates.
- **Restart it now and then.** When you log in and see `*** System restart required ***`, run `codemany pause --wait`. It stops new jobs and waits for running ones to finish. Then run `sudo reboot`. After the restart, SSH in and run `codemany resume`.

If GitHub shows the runners as Offline, or jobs wait in Queued:

1. Check the power light. After a power cut, the box should start by itself (step 3).
2. From your laptop, run `ping ci-box.local`, or ping its address.
3. SSH in and run `codemany doctor`. For the latest log lines, run `journalctl --user -u codemany -n 50`.
4. Still stuck? Run `sudo reboot`. Read [runner shows Offline](https://codemany.com/problems/self-hosted-runner-offline) for more.

## Troubleshooting

- **The PC starts Windows, not the installer.** Restart and press `F7` or `Delete` right away, then pick the USB stick. If the stick isn't listed, write it again with balenaEtcher.
- **`ssh: connect to host … port 22: Connection refused`.** OpenSSH isn't installed. On the mini PC itself, run `sudo apt install -y openssh-server`.
- **`df -h /` shows far less than 1 TB.** Run the `lvextend` command from [step 5](https://codemany.com/articles/mini-pc-ci-server#disk).
- **Jobs wait in Queued.** Every label in `runs-on` must be on the runner: `self-hosted`, `Linux` and `codemany`. The repository must be one you picked in setup. `codemany status` lists the runners.
- **`permission denied while trying to connect to the Docker daemon socket`.** Restart the box once after installing Codemany: `sudo reboot`.
- **`codemany setup-link` says "no daemon is waiting for setup".** The service isn't running. Start it with `codemany install-service`. If it says "already set up", open the dashboard instead.
- **The box stays off after a power cut.** Set **Restore on AC Power Loss** to **Power On** in the BIOS ([step 3](https://codemany.com/articles/mini-pc-ci-server#bios)).

## Questions

### Is a mini PC good for a home server?

For CI, yes. It is small and quiet, and reviews measure this one at about 10 watts when idle. With 16 threads and 32 GB it runs 4 jobs at once. It has one disk and one power supply, so if it breaks, jobs wait until you fix it.

### What is a CI server?

A CI server is a computer that builds and tests your code each time you push. It is also called a build server. With GitHub Actions, GitHub keeps the list of jobs, and a runner on the CI server does the work.

### Do I need to open a port on my router?

No. The runner on the mini PC connects out to GitHub over HTTPS and asks for jobs. Nothing on the internet connects in, so there is no port to forward.

### How many jobs can a mini PC run at once?

Codemany gives each job 4 CPU threads, 4 GB of memory and 15 GB of disk. A mini PC with 16 threads, 32 GB and 1 TB runs 4 jobs at once. `codemany capacity` prints the number for your machine.

### Can jobs on it use Docker?

Yes. Codemany's setup installs Docker from Ubuntu's own packages, and the runners carry the `docker` label while Docker is running. Ask for it with `runs-on: [self-hosted, Linux, codemany, docker]`.

### Can I use a newer Ubuntu, like 26.04?

This guide uses Ubuntu Server 24.04 LTS. Codemany's docs list Ubuntu 22.04 and 24.04 for its apt repository. The one-line installer also runs on other Linux versions, but 24.04 is the path this guide covers.

## Related

Read next: [self-hosted runner on Linux](https://codemany.com/docs/guides/linux-runner), [Linux runners](https://codemany.com/features/linux-runners), [GitHub Actions runner pricing](https://codemany.com/articles/github-actions-runner-pricing) and [no space left on device](https://codemany.com/problems/self-hosted-runner-disk-full).

Not sure the box pays off? The calculator shows what GitHub Actions has cost you, and what you'd save on your own machines. It's read-only.

[See what your CI cost you](https://codemany.com/calculator)

## Site links

- Menu: [codemany home](https://codemany.com/) · [Changelog](https://codemany.com/changelog) · [Download](https://codemany.com/download)
- Documentation: [Overview](https://codemany.com/docs) · [Get started](https://codemany.com/docs/get-started) · [Machines](https://codemany.com/docs/machines) · [Plan & Billing](https://codemany.com/docs/billing) · [Troubleshooting](https://codemany.com/docs/troubleshooting) · [FAQ](https://codemany.com/docs/faq) · [Security & privacy](https://codemany.com/docs/security) · [What is a self-hosted runner?](https://codemany.com/docs/guides/self-hosted-runner) · [Self-hosted runner on a Mac](https://codemany.com/docs/guides/mac-runner) · [iOS and Xcode builds](https://codemany.com/docs/guides/ios-xcode) · [Self-hosted runner on Linux](https://codemany.com/docs/guides/linux-runner) · [Single-use runners](https://codemany.com/docs/guides/ephemeral-runners) · [Actions Runner Controller](https://codemany.com/docs/guides/actions-runner-controller) · [Cut GitHub Actions costs](https://codemany.com/docs/guides/actions-cost) · [GitHub Actions alternatives](https://codemany.com/docs/guides/github-actions-alternatives) · [Runner security](https://codemany.com/docs/guides/runner-security) · [Articles](https://codemany.com/articles) · [AI agents and CI costs](https://codemany.com/articles/ai-coding-agents-ci-costs) · [Actions cache](https://codemany.com/articles/github-actions-cache) · [timeout-minutes](https://codemany.com/articles/github-actions-timeout-minutes) · [Actions limits](https://codemany.com/articles/github-actions-limits) · [Docker in Docker](https://codemany.com/articles/github-actions-docker-in-docker) · [Docker layer caching](https://codemany.com/articles/docker-layer-caching-github-actions) · [ARM runners](https://codemany.com/articles/github-actions-arm-runners) · [Matrix builds](https://codemany.com/articles/github-actions-matrix) · [Blacksmith vs GitHub](https://codemany.com/articles/blacksmith-vs-github-actions) · [Runner pricing](https://codemany.com/articles/github-actions-runner-pricing) · [Features](https://codemany.com/features) · [Problems and fixes](https://codemany.com/problems) · [Advanced](https://codemany.com/docs/advanced) · [Compare](https://codemany.com/docs/compare) · [Pricing](https://codemany.com/pricing) · [Privacy Policy](https://codemany.com/privacy)
- Product: [Console](https://console.codemany.com/)
- Company: [Status](https://codemany.com/status) · [Contact](https://x.com/arpwal) · [Terms](https://codemany.com/terms) · [Codemany on X](https://x.com/codemanyhq)
