安装到云主机
在一台装着 Linux、用 GRUB 启动的 x86_64 云主机（KVM，virtio 磁盘和网卡）上，以 root 运行：
curl -fsSL https://rustros.com/install.sh | sh
安装分两步，中间可以停下来：
- 准备并试启动。脚本下载最新发布版，用内置的公钥校验签名、逐个核对 SHA-256，按这台机器现在的网络（Linux 用 DHCP 就用 DHCP，否则沿用当前的静态地址）做出磁盘镜像，生成更新密钥，然后让 GRUB 只引导 RustROS 一次。试启动不写磁盘，5 分钟后自动重启回 Linux。这段时间里它应该能 ping 通；云控制台（VNC）上能看到它识别到的网卡和地址。
- 写盘。回到 Linux 后确认没问题，再运行：
它会要求输入
python3 /root/rustros/install.py --write
yes，然后把镜像写到系统盘并重启进 RustROS。这块盘上原来的一切都会丢失。UEFI 机器会先把固件自己的磁盘启动项排到最前面。
/root/rustros/update.key。写盘后 Linux 就没了，先把密钥复制到别处——在线更新和远程管理都要用它。要求
- x86_64，至少 2 GiB 的系统盘（根文件系统直接在磁盘分区上，不支持 LVM/RAID）
- 现有系统用 GRUB 2 引导（只用来试启动一次；装好的 RustROS 不带 GRUB，用自己的启动程序）；BIOS 或 UEFI 都行，UEFI 要关掉 Secure Boot
- python3 和 OpenSSL 3（Debian 12、Ubuntu 22.04 及以后都自带）
- virtio 网卡和磁盘（KVM 云主机基本都是）。有多块网卡时 RustROS 用第一块
选项
通过 sh -s -- 传给脚本，例如 curl -fsSL https://rustros.com/install.sh | sh -s -- --apps ext4,shell,webadmin：
| 选项 | 作用 |
|---|---|
--apps a,b | 首次启动时安装的应用（默认 ext4,shell） |
--ip A/N --gw G | 静态地址 |
--dhcp | 用 DHCP |
--panel URL | 接入管理面板 |
--key K | 指定更新密钥（默认随机生成） |
--no-test | 跳过试启动 |
--yes | 不询问（试启动后直接重启；写盘时不要求输入 yes） |
用 ISO 安装到虚拟机
新建的虚拟机（Proxmox、libvirt/QEMU 等）不必先装 Linux：从首页下载安装 ISO，挂到虚拟机的光驱上启动。
- BIOS（SeaBIOS）和 UEFI（OVMF，关掉 Secure Boot）都可以。
- 磁盘和网卡用 VirtIO。磁盘至少 768 MiB；不到 2 GiB 时没有文件分区（只做路由足够），2 GiB 起才有放网站、容器等文件的分区。
启动后控制台上是安装程序（整个系统和默认应用 netstack、vfs、ext4、tls、shell 都在 ISO 里，不用联网）：
install vda
默认在 nic0 上用 DHCP；静态地址写成 install vda ip=192.0.2.10/24 gw=192.0.2.1；地址放在别的网卡或 VLAN 上加 if=，例如 install vda if=nic1.105 ip=192.0.2.10/24（VLAN 接口会一起建好；这样 nic0 不再用 DHCP，之后在控制台设）。输入 yes 后写盘并逐块读回核对。然后把 ISO 从虚拟机上取下（或把磁盘排到启动顺序最前），按回车重启。
配对管理工具
装好的机器没有更新密钥，远程管理端口只接受配对（像路由器的 WPS）：
- 在这台机器的控制台输入
pair：配对窗口开 120 秒。 - 在管理机上运行
rustros-update.py <地址> pair --key-file 密钥文件：两边都显示同一个 6 位校验码。 - 校验码一样，就在控制台输入
pair yes（不一样就pair no）。新密钥由双方的 X25519 密钥交换算出，管理机存进密钥文件，机器存进启动状态，谁都不用抄写。
密钥丢了就在控制台再配对一次，旧密钥随之作废。需要自动化时安装命令仍可用 key=... 直接给密钥。
在 QEMU 里试
每个发布版都有一个磁盘镜像 rustros-x86_64.img（发布页上有链接）。把它扩到 2 GiB 以上再启动：
truncate -s 2G rustros-x86_64.img qemu-system-x86_64 -m 256 -nographic \ -drive file=rustros-x86_64.img,format=raw,if=virtio \ -nic user,model=virtio-net-pci
它会用 DHCP 取地址。这个镜像里没有更新密钥，所以在线更新不可用；控制台和其他功能都正常。
控制台
串口和显示器上都是同一个控制台。开机先进 rescue（内置的救援控制台）；装了 shell 应用后控制台交给它，提示符变成 rustros>。Ctrl-] 在两者之间切换。help 列出命令。
shell 常用命令：
ip / arp / conns | 网卡与计数、ARP 表、连接和监听端口 |
ping / curl | 连通性测试；curl 支持 HTTPS |
mod / modules | 已安装 / 正在运行的模块 |
cfg <应用> [键 [值 | -]] | 查看、设置、删除应用的设置；密码类的键不带值时会隐藏输入 |
pkg ... | 包管理，见下文 |
log / crash | 每次启动的控制台日志（保存在磁盘上）/ 最近一次崩溃 |
slot / confirm | 内核 A/B 槽；确认正在试运行的内核 |
df / uptime / date | 存储用量、运行时间、时间 |
reboot / poweroff |
网络设置
改网络有“候选配置”保护，改错了不会把自己锁在外面：
cand ip nic0 203.0.113.10/24 203.0.113.1 apply # 生效，然后问你要不要保留；10 秒内不回答 yes 就恢复原样 save # 写进启动状态，重启后也用它
直接 ip nic0 A/N GW 立即生效但不保存，重启恢复。ip nic0 add A 给网卡加额外地址（NAT 出口用）。
应用与 pkg
功能都在模块里，内核只带 rescue、dhcp 和 updater。应用、文件系统驱动（ext4）、WebAssembly 运行时都是模块，从签名的发布版安装：
pkg update # 读取最新清单并校验签名 pkg list # 已装版本、可用版本、哪些能升级 pkg install nat router wireguard pkg upgrade # 升级所有能升级的应用 pkg upgrade kernel # 新内核写进备用槽，重启试运行，confirm 后保留 pkg remove cake
正在读取应用列表…
应用的设置都用 cfg 查看和修改，例如 cfg nat 列出 NAT 的所有设置和说明。
在线更新与远程管理
用 rustros-update.py（Python 3，无依赖）从另一台机器管理，流量用更新密钥加密：
export RUSTROS_KEY=$(cat update.key) python3 rustros-update.py 203.0.113.10 info python3 rustros-update.py 203.0.113.10 upload rustros-x86_64.elf --wait python3 rustros-update.py 203.0.113.10 module-install nat nat-x86_64.mod python3 rustros-update.py 203.0.113.10 module-config webadmin allow 198.51.100.7 python3 rustros-update.py 203.0.113.10 log prev
upload --wait 把内核写进备用槽，重启试运行一次，起来后自动确认。新内核起不来或没确认，下次启动就回到原来的内核；连续三次启动不稳定会进安全模式，第四次换回另一个槽。
镜像 1 MiB，只有一个 EFI 分区：UEFI 上固件启动 RustROS 的启动程序和内核文件，BIOS 上由 MBR 里 RustROS 自己的启动程序启动，不用 GRUB。两个内核槽是分区里大小可变的文件；新内核放不下时，EFI 分区在线原地变大（512 MiB 以内），任何一次写入后断电都能启动。2026.10.25.1 以前装的机器用 GRUB：升级到 2026.10.25.1 后用 rustros-update.py HOST migrate 在线换成现在的启动方式（BIOS 机器加 --bios，并先装上发布目录里的 storage-mbr-x86_64.mod）。
网页管理
装上 webadmin 后在 8080 端口提供网页管理，每个应用的设置页按它声明的参数自动生成。默认只允许没有网关的网卡所在网段访问，所以在云主机上要先放行自己的地址并设置密码：
pkg install webadmin cfg webadmin allow 198.51.100.7 cfg webadmin password # 输入两次，不回显
面板
panel 应用把机器接入管理面板：面板可以查看状态、安装和配置应用、更新内核。安装时用 --panel https://面板地址，或者之后 cfg panel url https://面板地址。第一次连接时控制台会显示认领码，在面板上输入即可认领。面板下发的下载只能来自 cfg panel downloads 指定的前缀（默认 https://rustros.com/）。
存储
| 位置 | 内容 |
|---|---|
| 0 – 512 MiB | 引导区：GPT、1 MiB 的 EFI 分区（启动程序、两个内核槽、启动状态）、随镜像带的应用；其余留给 EFI 分区以后变大 |
| 512 MiB – 1 GiB | 数据分区：崩溃安全的键值存储（设置、已安装的应用）和每次启动的控制台日志 |
| 1 GiB – 磁盘末尾 | 文件分区：标准 ext4，带 jbd2 日志和元数据校验（metadata_csum、64bit），应用各有自己的目录 |
分区都在第一次启动时创建。文件分区由文件系统驱动模块挂载（现在是 ext4；没装驱动时文件分区不挂载，其他功能照常）；它认不出的分区不会被格式化。文件分区可以拿到 Linux 上直接挂载和 e2fsck；Linux 用默认参数格式化的 ext4，RustROS 也能读写。
安全
- 发布清单用 Ed25519 签名，公钥内置在安装脚本、
pkg和面板应用里；每个文件都核对 SHA-256。 - 在线更新和远程管理的流量用更新密钥认证和加密。
- 更新密钥以明文保存在磁盘的启动状态里：能读这块盘的人就能拿到它。
- 内核之外的代码都是
#![forbid(unsafe_code)]的 Rust。
许可
RustROS 是闭源的专有软件（许可条款）：这里发布的内核、模块和镜像可以免费装在自己的机器上使用，不能转卖、再分发或逆向。
其中用到的第三方软件按各自的许可使用，版权声明和许可全文见 THIRD-PARTY-NOTICES.txt。2026.10.25.2 起镜像里不再有 GRUB；更早的版本带着 GRUB（GPLv3），它们的许可说明和 GRUB 源码仍在各自的发布目录里。
Install on a VPS
On an x86_64 VPS running Linux and booting with GRUB (KVM, virtio disk and NIC), as root:
curl -fsSL https://rustros.com/install.sh | sh
It goes in two steps, with a stop in between:
- Prepare and test-boot. The script downloads the latest release, checks its signature against the key built into it and every file's SHA-256, makes the disk image with this machine's network (DHCP if Linux uses DHCP, else the static address it has now), makes an update key, and has GRUB boot RustROS once. The test boot does not write the disk and restarts into Linux after 5 minutes. Meanwhile it should answer ping; the cloud console (VNC) shows the NICs and address it found.
- Write the disk. Back in Linux, if it worked:
It asks you to type
python3 /root/rustros/install.py --write
yes, writes the image over the system disk and restarts into RustROS. Everything on that disk is lost. On UEFI machines the firmware's own disk entries are put first in the boot order.
/root/rustros/update.key. Once the disk is written Linux is gone: copy the key somewhere else first — online updates and remote management need it.Requirements
- x86_64, a system disk of 2 GiB or more (the root file system on a plain partition: no LVM or RAID)
- the present system boots with GRUB 2 (only for the one test boot; RustROS itself carries no GRUB, it boots with its own loaders); BIOS or UEFI, with Secure Boot off
- python3 and OpenSSL 3 (Debian 12, Ubuntu 22.04 and later have them)
- virtio NIC and disk (as KVM clouds give). With several NICs RustROS uses the first
Options
Passed through sh -s --, e.g. curl -fsSL https://rustros.com/install.sh | sh -s -- --apps ext4,shell,webadmin:
| Option | What it does |
|---|---|
--apps a,b | apps installed at first boot (default ext4,shell) |
--ip A/N --gw G | a static address |
--dhcp | DHCP |
--panel URL | connect to a management panel |
--key K | the update key (default: a new random one) |
--no-test | no test boot |
--yes | do not ask (reboot for the test straight away; no typed yes before writing) |
Install a VM from the ISO
A new virtual machine (Proxmox, libvirt/QEMU, ...) needs no Linux first: download the installer ISO from the home page and boot the VM from it.
- BIOS (SeaBIOS) or UEFI (OVMF, Secure Boot off).
- VirtIO disk and NIC. The disk at least 768 MiB; under 2 GiB there is no files partition (enough for a router), from 2 GiB on there is one for sites, containers and other files.
The console then shows the installer (the whole system and the default apps netstack, vfs, ext4, tls, shell are on the ISO; no network needed):
install vda
DHCP on nic0 by default; a static address: install vda ip=192.0.2.10/24 gw=192.0.2.1; on another NIC or a VLAN with if=, e.g. install vda if=nic1.105 ip=192.0.2.10/24 (the VLAN interface is made too; nic0 then gets no DHCP, set it on the console later). After yes it writes the disk and reads every block back. Then take the ISO out of the VM (or put the disk first in the boot order) and press Enter to restart.
Pairing the admin tool
An installed machine has no update key; its remote management port only answers pairing (like a router's WPS):
- On the machine's console type
pair: the pairing window is open for 120 s. - On the admin machine run
rustros-update.py <address> pair --key-file KEYFILE: both show the same 6-digit check code. - If the codes match, type
pair yeson the console (otherwisepair no). The new key comes from an X25519 exchange: the admin machine keeps it in the key file, the machine in its boot state; nobody copies it by hand.
Lost the key? Pair again from the console; the old key stops working. For automation the installer still takes key=....
Try it in QEMU
Every release has a disk image, rustros-x86_64.img (linked on the releases page). Grow it to 2 GiB or more and boot it:
truncate -s 2G rustros-x86_64.img qemu-system-x86_64 -m 256 -nographic \ -drive file=rustros-x86_64.img,format=raw,if=virtio \ -nic user,model=virtio-net-pci
It gets its address by DHCP. The image has no update key, so online updates are off; the console and everything else work.
The console
The serial port and the screen show the same console. It starts in rescue, the built-in console; once the shell app is installed the console is its, with the prompt rustros>. Ctrl-] switches between them. help lists the commands.
The shell's everyday commands:
ip / arp / conns | NICs and counters, the ARP table, connections and listening ports |
ping / curl | connectivity; curl speaks HTTPS |
mod / modules | installed / running modules |
cfg <app> [key [value | -]] | show, set or remove an app's settings; a password key without a value asks for it, hidden |
pkg ... | the package manager, below |
log / crash | each boot's console log (kept on disk) / the last crash |
slot / confirm | the A/B kernel slots; keep a kernel on trial |
df / uptime / date | storage use, uptime, the time |
reboot / poweroff |
Network settings
Network changes go through a candidate, so a mistake does not lock you out:
cand ip nic0 203.0.113.10/24 203.0.113.1 apply # in effect, then it asks; no "yes" within 10 s and it goes back save # into the boot state: kept across reboots
ip nic0 A/N GW applies at once but is not saved. ip nic0 add A adds an address (for NAT egress).
Apps and pkg
What RustROS does is in modules; the kernel carries only rescue, dhcp and the updater. Apps, file system drivers (ext4) and the WebAssembly runtime are modules, from the signed releases:
pkg update # the latest manifest, signature checked pkg list # installed and available versions, what can be upgraded pkg install nat router wireguard pkg upgrade # every app with a newer version pkg upgrade kernel # the new kernel into the spare slot: reboot to try it, confirm to keep it pkg remove cake
Reading the list of apps…
Every app's settings are shown and changed with cfg: cfg nat lists NAT's settings with what each does.
Online updates and remote management
rustros-update.py (Python 3, no dependencies) manages a machine from another one; the traffic is authenticated and encrypted with the update key:
export RUSTROS_KEY=$(cat update.key) python3 rustros-update.py 203.0.113.10 info python3 rustros-update.py 203.0.113.10 upload rustros-x86_64.elf --wait python3 rustros-update.py 203.0.113.10 module-install nat nat-x86_64.mod python3 rustros-update.py 203.0.113.10 module-config webadmin allow 198.51.100.7 python3 rustros-update.py 203.0.113.10 log prev
upload --wait writes the kernel into the spare slot, boots it once and confirms it once it is up. A kernel that does not come up, or is not confirmed, is followed by the old one at the next boot; after three unstable boots it starts in safe mode, at the fourth the other slot takes over.
The image is 1 MiB with one EFI partition: on UEFI the firmware starts RustROS's loader and kernel file, on BIOS RustROS's own loader in the MBR does; no GRUB. The two kernel slots are files of any size in the partition; when a new kernel does not fit, the EFI partition grows in place online (within 512 MiB), and a power cut after any write still boots. Machines installed before 2026.10.25.1 use GRUB: after updating to 2026.10.25.1, rustros-update.py HOST migrate moves them over online (BIOS machines with --bios, after installing storage-mbr-x86_64.mod from that release's directory).
Web admin
The webadmin app serves a web admin on port 8080; each app's page is generated from the settings it declares. By default only the networks of NICs without a gateway may connect, so on a VPS allow your own address and set a password first:
pkg install webadmin cfg webadmin allow 198.51.100.7 cfg webadmin password # asked twice, not shown
Panel
The panel app connects the machine to a management panel, which shows its state, installs and configures apps and updates the kernel. Install with --panel https://your-panel, or later cfg panel url https://your-panel. On first contact the console shows a claim code to enter in the panel. What the panel has it download must come from cfg panel downloads (default https://rustros.com/).
Storage
| Where | What |
|---|---|
| 0 – 512 MiB | the boot area: GPT, the 1 MiB EFI partition (the loaders, two kernel slots, the boot state), apps carried by the image; the rest is room for the EFI partition to grow |
| 512 MiB – 1 GiB | data partition: a crash-safe key-value store (settings, installed apps) and each boot's console log |
| 1 GiB – the end | files partition: a standard ext4 with a jbd2 journal and metadata checksums (metadata_csum, 64bit); each app has its own directory |
The partitions are made at first boot. A file system driver module mounts the files partition (ext4 for now; without one it stays unmounted and the rest works as usual); a partition it does not recognise is never formatted. Linux mounts and e2fscks the files partition as it is, and RustROS reads and writes ext4 that Linux formatted with its defaults.
Security
- Release manifests are signed with Ed25519; the public key is built into the installer,
pkgand the panel app; every file's SHA-256 is checked. - Online updates and remote management are authenticated and encrypted with the update key.
- The update key is kept in plain text in the boot state on the disk: whoever reads the disk has it.
- Outside the kernel, all code is Rust with
#![forbid(unsafe_code)].
License
RustROS is proprietary software (the license): the kernel, modules and images published here may be installed and used free of charge on machines you operate; they may not be sold, redistributed or reverse engineered.
The third-party software in them is used under its own licenses; their notices and texts are in THIRD-PARTY-NOTICES.txt. From 2026.10.25.2 on the images carry no GRUB; earlier releases did (GPLv3), and their notices and GRUB's source stay in their release directories.