Set up a mini PC server for GitHub Actions, from scratch
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.
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.
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.
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.
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.
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), $779 on Amazon in November 2026. Then follow the Mac runner guide, or download Codemany for Mac.
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.
Download Ubuntu Server
Go to 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.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.isoOn 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 SHA256Each 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.
Write it to the USB stick
Install balenaEtcher (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:
Boot menu
Choose Try or Install Ubuntu Server.
Language and keyboard
Pick yours. If it offers an installer update, either choice works.
Type of installation
Keep Ubuntu Server (not "minimized").
Network
Your Ethernet port shows an address, like
192.168.1.50. Write it down. You'll use it from your laptop.Proxy and mirror
Leave the proxy empty. Let the mirror test pass, then choose Done.
Guided storage
Keep Use an entire disk and Set up this disk as an LVM group. The next screen shows the plan. The
ubuntu-lvline is much smaller than your disk. That's normal, and you'll fix it in step 5. Choose Done, then Continue to confirm.Profile
Type your name, a name for the server (we use
ci-box), a username and a password. Your jobs run as this user.Ubuntu Pro
Choose Skip for now.
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.
Featured server snaps
Tick nothing. Codemany installs Docker and the other tools in step 6.
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 [email protected]
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.
Reach it by name
sudo apt install -y avahi-daemon
Now ssh [email protected] 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 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:
Sign in with GitHub
The page shows a code. Enter it on github.com.
Pick repositories
Choose repositories, or a whole organization.
Install the Codemany Runners App, if asked
Choose Install… and approve it on GitHub.
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.
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 ***, runcodemany pause --wait. It stops new jobs and waits for running ones to finish. Then runsudo reboot. After the restart, SSH in and runcodemany resume.
If GitHub shows the runners as Offline, or jobs wait in Queued:
- Check the power light. After a power cut, the box should start by itself (step 3).
- From your laptop, run
ping ci-box.local, or ping its address. - SSH in and run
codemany doctor. For the latest log lines, runjournalctl --user -u codemany -n 50. - Still stuck? Run
sudo reboot. Read runner shows 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, runsudo apt install -y openssh-server.df -h /shows far less than 1 TB. Run thelvextendcommand from step 5.- Jobs wait in Queued. Every label in
runs-onmust be on the runner:self-hosted,Linuxandcodemany. The repository must be one you picked in setup.codemany statuslists the runners. permission denied while trying to connect to the Docker daemon socket. Restart the box once after installing Codemany:sudo reboot.codemany setup-linksays "no daemon is waiting for setup". The service isn't running. Start it withcodemany 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).
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, Linux runners, GitHub Actions runner pricing and no space left on device.
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.