Layer 3 · self-hosting reality check
What it actually takes to self-host Woodpecker CI
The docs say 512 MB server. In practice you want 2 GB server + whatever the builds need on the agents. Here is the honest version — real requirements, real monthly cost, what you will be maintaining, and the one thing that catches people out.
Usually reached from GitHub Actions alternatives, where Woodpecker CI is one of the picks.
| RAM — documented minimum | 512 MB server |
|---|---|
| RAM — what it really needs | 2 GB server + whatever the builds need on the agents |
| CPU | 2 vCPU server; agents sized to your builds |
| Disk | Small for the server; agents need room for Docker layers and caches |
| Monthly cost | $12/mo server plus agent capacity — often the biggest saving on this list, because CI minutes are billed brutally |
| Setup time | 2 hours |
| How you install it | container for the server, one or more agents registered against it |
| Ongoing maintenance | Low for the server. The agents are where the work is: disk fills with Docker layers, and caches need pruning. |
| Where it stops scaling | Add agents horizontally; the server is light. This scales further than most people need. |
The thing that catches people out
Agent disk exhaustion is the failure everyone hits. Docker layers and build caches accumulate silently until builds start failing with confusing errors that look like application bugs. Set a pruning cron on every agent on day one and alert on disk usage — this is not optional, it is the maintenance.
When not to self-host Woodpecker CI
Your builds need macOS or Windows runners, or you rely heavily on the GitHub Actions marketplace. Woodpecker is Linux-and-containers.
Every guide here carries this section. A site that only ever tells you to self-host is selling something — the useful answer is sometimes no.
Other Layer 3 self-hosting guides
Common questions
- How much RAM does Woodpecker CI actually need?
- 2 GB server + whatever the builds need on the agents in practice. The documented minimum is 512 MB server, which is the figure at which the process starts rather than the figure at which it works under real use. 2 vCPU server; agents sized to your builds alongside it.
- What does self-hosting Woodpecker CI cost per month?
- $12/mo server plus agent capacity — often the biggest saving on this list, because CI minutes are billed brutally This is commodity VPS pricing and excludes your time, which is the larger cost for most people — budget for low for the server. The agents are where the work is: disk fills with Docker layers, and caches need pruning.
- How long does it take to set up Woodpecker CI?
- 2 hours, via container for the server, one or more agents registered against it.
- When should I NOT self-host Woodpecker CI?
- Your builds need macOS or Windows runners, or you rely heavily on the GitHub Actions marketplace. Woodpecker is Linux-and-containers.
- What is the most common mistake when self-hosting Woodpecker CI?
- Agent disk exhaustion is the failure everyone hits. Docker layers and build caches accumulate silently until builds start failing with confusing errors that look like application bugs. Set a pruning cron on every agent on day one and alert on disk usage — this is not optional, it is the maintenance.