vps2gentoo: Reinstall Your VPS as Gentoo, In Place, Over SSH, No ISO Required

Your provider doesn’t offer a Gentoo image? You don’t need one anymore.

Gentoo has always had a reputation problem on VPS hosting. It’s not that it runs badly on a VPS. It runs beautifully. The problem is getting it there. Almost no provider ships a Gentoo image, custom ISO uploads are hit-or-miss, and following the Handbook through a laggy web console is nobody’s idea of a good afternoon.

vps2gentoo fixes that. It’s one shell script you run on your existing Linux VPS, and when it finishes, the machine is Gentoo. It does this in place, over the SSH session you already have open. No rescue mode, no ISO, no second disk.

It’s a Gentoo port of the well-known vps2arch, written to work on any Linux, and tested on Ubuntu images.

If you’ve been waiting for an excuse to run Gentoo on your servers, this is it. Let’s look at what it does and how it pulls it off.

TL;DR

# as root, inside tmux or screen
curl -fsSLO https://raw.githubusercontent.com/oguzcodes/vps2gentoo/main/vps2gentoo.sh
less vps2gentoo.sh   # read it before you run it
sh vps2gentoo.sh

On arm64 machines, use vps2gentoo.arm64.sh instead.

The script shows you a summary of everything it detected, and nothing happens until you type YES in capitals. When it’s done, reboot with:

sync; echo b > /proc/sysrq-trigger

…and log back in to Gentoo.

What you get: a minimal binary workspace

vps2gentoo deliberately doesn’t hand you a personalized Gentoo. It hands you a minimal, binary-based starting point that boots reliably on whatever virtual hardware your provider uses:

The official stage3 for your CPU, OpenRC by default (systemd if you choose).
Binary packages enabled. On amd64 and arm64, the stage3 ships the official Gentoo binhost config, so the script turns on getbinpkg with binpkg-request-signature. Packages arrive prebuilt and signature-checked instead of compiling on a small VPS.
A prebuilt distribution kernel (sys-kernel/gentoo-kernel-bin) with a generic dracut initramfs (hostonly="no"). The chroot can’t see your real hardware, so the initramfs is built to boot anywhere.
Only what’s needed to boot and reach the machine: OpenSSH, the network tools for your setup (netifrc and dhcpcd on OpenRC, systemd-networkd on systemd), GRUB, efibootmgr on UEFI, and filesystem tools for whatever you actually use (LVM, mdadm, XFS, Btrfs, and so on).
Sane build defaults: MAKEOPTS is set to the smaller of your CPU count and your RAM in GiB, so a 1 vCPU / 1 GB box won’t run out of memory the first time you compile something.

That’s intentional. This is a workspace, not a final product. Advanced users can change all of it later: profile, USE flags, CFLAGS, kernel, init system, everything. More on that below.

How it works

The interesting part about replacing a running OS is that you’re standing on the floor you’re trying to remove. vps2gentoo handles this by splitting the work into a safe phase, one irreversible step, and a cleanup phase.

Phase 0: Detection

Before touching anything, the script inspects the machine:

Architecture. It maps uname -m to the right Gentoo stage3: amd64, x86, arm64, armv7/v6/v5, ppc64(le), riscv64, loongarch64, s390x, sparc64, mips and more.
Environment. It recognizes OpenVZ and LXC containers, where it skips the kernel and bootloader, and BIOS vs. 32/64-bit UEFI.
Storage. It finds out what lives on /, /boot and /var, detects LVM, RAID, XFS, Btrfs, F2FS and others, and refuses layouts it can’t handle safely, such as a separate /usr or a LUKS-encrypted root that nobody could unlock at boot.
Network. It reads your live configuration: DHCP vs. static IPv4, static IPv6, gateways (including off-subnet /32 setups and venet-style point-to-point links), and DNS. It even looks past systemd-resolved’s 127.0.0.53 stub to find your real resolvers.
Sanity checks. It requires root, at least 4 GiB free on /, and a kernel ≥ 3.2. It switches SELinux to permissive if needed, and warns you loudly if you’re not inside tmux or screen.

You then get a full summary: stage3, bootloader, network, DNS, what will be wiped and what will be carried over. Nothing happens until you type YES.

Phase 1: Prepare (safe)

Everything in this phase happens inside /vps2gentoo.root, next to your running system:

Download and verify the latest stage3: SHA512 from the official DIGESTS file, plus a GPG check against the Gentoo Release Engineering key when gpg is available.
Unpack it with xattrs and numeric ownership preserved.
Chroot in and sync the Gentoo repository with emerge-webrsync.
Install the kernel, bootloader, network and filesystem packages listed above.
Write the config: /etc/fstab with UUIDs, resolv.conf, network config for netifrc or systemd-networkd, hostname, timezone, root credentials and SSH keys.
Enable services: sshd and your network interface.

If anything fails in this phase, your running system is untouched. The script tells you so and leaves the prepared tree for you to inspect.

Phase 2: Swap (the point of no return)

This is the clever bit. Once the old root is deleted, there’s no libc left on /, so most normal commands stop working. vps2gentoo plans for that.

Before deleting anything, it locates the stage3’s own dynamic loader (ld-linux*.so) and runs a self-test: it executes the new system’s mv through that loader. If the test fails, the script aborts with nothing deleted.

If the test passes:

Signals are ignored, so a stray Ctrl+C can’t interrupt the swap halfway.
One find … -delete wipes the old / (plus /boot and /var if they’re separate), skipping the prepared tree and any active swap files.
One mv, run through the stage3 loader, moves the prepared tree into /. It’s the same filesystem, so this is a rename, not a copy, and it’s nearly instant.

From here on, the system on disk is Gentoo.

Phase 3: Finalize

Directories that couldn’t be renamed because they’re mount points (/boot, /var, an ESP) get their stage3 contents copied in instead.
GRUB is installed natively from the new system. On BIOS it goes to every disk backing / and /boot. On UEFI it registers a gentoo boot entry and installs to the removable-media path EFI/BOOT/, because VPS firmware often forgets NVRAM entries.
installkernel is rebuilt with the grub USE flag, so future kernel upgrades regenerate grub.cfg automatically.

What carries over, what doesn’t

Carried over	Wiped
Root password hash	Everything on `/`
`/root/.ssh/authorized_keys`	`/boot` and `/var` (even if separate)
SSH host keys (no “host key changed” warning)	`/root` and `/home`, unless they’re separate filesystems
Hostname and timezone	All installed packages, users and services
Network and DNS configuration
Other separate mounts (`/home`, `/srv`, …)

If root has neither a password nor SSH keys, the script sets the password to vps2gentoo and forces you to change it on first login.

Options

Flag	What it does
`-i openrc\|systemd`	Init system / stage3 flavour (default: `openrc`)
`-s STAGE`	Exact stage3 flavour, e.g. `amd64-hardened-openrc`, `amd64-musl`, `arm64-desktop-systemd`
`-b auto\|grub\|none`	Bootloader (default: GRUB wherever it’s native)
`-n auto\|none`	Clone the current network setup, or write nothing
`-m URL`	Use a different Gentoo mirror
`-y`	Skip the confirmation prompt

Want a hardened or musl system from day one? -s takes any flavour published on the mirrors. Pass a name that doesn’t exist and the script lists the available ones for your architecture.

Before you press Enter

Yes, I’m telling you to reinstall your VPS. I’m also telling you to do it like a professional:

Take a snapshot or backup. The script wipes your root filesystem. Treat it like a reinstall, because it is one.
Check your provider’s terms of service. Some don’t allow this kind of in-place reinstall.
Run it inside tmux or screen. An SSH drop during the swap leaves the machine unbootable.
Make sure you can log in as root directly. Only root’s keys and password are carried over; other users and (non-separate) /home are wiped. On cloud images where you normally log in as ubuntu, root’s authorized_keys often contains a forced “please log in as ubuntu” command, so clean that up first and consider setting a root password as a fallback.
Know where your provider’s web or serial console is, just in case.
Don’t open new SSH sessions after it finishes. The old sshd is still running from deleted files. Keep the session open and reboot.

After the first boot

The script prints your next steps, and they’re the right ones:

emerge --sync && emerge -avuDN @world
eselect news read
emerge -av app-admin/sysklogd sys-process/cronie net-misc/chrony   # logger, cron, NTP

The stage3 is deliberately bare, so a system logger, cron and NTP are the first things to add on a server.

Making it yours (for advanced users)

The binary workspace is a starting line. Gentoo is about choice, and nothing the script sets up is permanent:

Pick your profile: eselect profile list / eselect profile set …
Tune /etc/portage/make.conf: set your own COMMON_FLAGS (e.g. -march=native), global USE flags, and MAKEOPTS.
Go full source: remove getbinpkg from FEATURES to compile everything with your own flags.
Build your own kernel: swap gentoo-kernel-bin for gentoo-kernel or gentoo-sources, and switch dracut to a host-only initramfs once you’re on the real machine.
Change init later if you started with OpenRC and want systemd, or the reverse.
Rebuild: emerge -avuDN @world applies it all.

vps2gentoo’s job is to get you to a working, reachable Gentoo box. What you build on it is up to you.

arm64 notes

The dedicated vps2gentoo.arm64.sh adds a few things ARM cloud instances need:

It keeps your current console= and earlycon= kernel arguments, so your provider’s serial console keeps working after the switch.
It detects iSCSI boot volumes and refuses them, with a hint to switch the instance to a paravirtualized boot volume.
It writes fstab last, so Gentoo’s mount-boot checks don’t trip over a separate /boot during the install.

Credits & license

It comes as-is, with no warranty. You run it at your own risk, and the authors accept no liability for data loss, downtime or lost access. That’s exactly why the snapshot step above isn’t optional.

Go reinstall your VPS

Spin up a test instance, take a snapshot, open tmux, and give it ten minutes of your attention. Then you’ll have the thing most VPS providers never offered: a clean Gentoo server you control from the toolchain up.

👉 github.com/oguzcodes/vps2gentoo

Found a bug, tested it on a provider or distro that isn’t Ubuntu, or got it running somewhere exotic? Open an issue or a PR. Every report makes the next reinstall safer for everyone.