How to set up a self-hosted GitHub Actions runner on a VPS

Register a self-hosted GitHub Actions runner on a VPS and install it as a service: download the runner as a non-root user, register with your repo token, run svc.sh so it survives reboots. Copy-paste commands.

A self-hosted runner gives you flat-cost CI with warm caches — no per-minute billing, your toolchain, your machine. This is the minimal setup how-to; for why self-hosting beats GitHub-hosted minutes and Docker-job details, see the full guide and the VPS for GitHub Actions use-case.

1. Create a non-root user (the runner refuses root)

adduser --disabled-password --gecos "" runner
su - runner

2. Download the runner

In GitHub: Settings → Actions → Runners → New self-hosted runner → Linux, which gives you the exact download and a one-time token. Then:

mkdir actions-runner && cd actions-runner
curl -o actions-runner-linux-x64.tar.gz -L \
  https://github.com/actions/runner/releases/latest/download/actions-runner-linux-x64.tar.gz
tar xzf actions-runner-linux-x64.tar.gz

3. Register it with your repo

./config.sh --url https://github.com/YOUR_ORG/YOUR_REPO --token YOUR_TOKEN

4. Install as a service (survives reboots)

Don't run ./run.sh in a terminal — install it:

sudo ./svc.sh install runner
sudo ./svc.sh start
sudo ./svc.sh status

The runner now shows as Idle in the GitHub UI and picks up jobs that target it.

5. Use it from a workflow

jobs:
  build:
    runs-on: self-hosted
    steps:
      - uses: actions/checkout@v4
      - run: make build && make test

Docker jobs (optional)

Install Docker once and workflows can build images with layer cache persisting between runs:

sudo apt install -y docker.io
sudo usermod -aG docker runner

See install Docker on a VPS. Sizing: Small ($8/mo) is comfortable for most CI; step up for heavy compilation. Root in about a minute, no KYC, pay in crypto.

FAQ

How do I register a self-hosted GitHub Actions runner?

In your repo (or org): Settings → Actions → Runners → New self-hosted runner → Linux. GitHub shows a download command and a one-time registration token. Download the runner as a non-root user, run ./config.sh with that URL and token, then install it as a service with svc.sh. Steps below.

Why can't the runner run as root?

The runner refuses to run as root by design. Create a dedicated non-root user (adduser runner) and set it up there. That also limits what a malicious workflow could touch on your box.

How do I keep the runner running after reboot?

Use the bundled svc.sh helper: sudo ./svc.sh install runner && sudo ./svc.sh start. It installs a systemd unit so the runner starts on boot and restarts on failure, and shows as Idle in the GitHub UI.

Do I need a dedicated IP for a runner?

No. The runner dials out to GitHub over HTTPS; nothing needs to reach it inbound. A NAT plan (from $3/mo) works. Take a dedicated IP only if you also self-host something that serves traffic.

Do you ask for ID or a card?

No. Email to sign up, pay in USDC or USDT — no documents, no card. Root in about a minute.

Comments

No comments yet. Be the first.