Built for people who want a compact, approachable, and capable server system.
CapOS combines low resource usage, a browser-first management experience, and room to grow from simple setups to serious self-hosted workloads.
Website · Download Releases · Package Repository · Quick Start · Documentation
Maintained by the FWERKOR Team, especially Castronaut.
CapOS is an open-source server operating system focused on clarity, efficiency, and day-to-day usability. It is designed for homelabs, learning environments, edge devices, and compact servers where a full management workflow matters just as much as raw functionality.
Instead of feeling like a stripped-down build environment, CapOS aims to feel like a complete server platform from the moment it boots: easy to access, easy to manage, and flexible enough to expand as your needs change.
|
Runs with a small footprint and works well across a broad range of hardware, from compact devices to full PCs. |
Manage the system and install applications from the official Snap ecosystem directly in CapOS WebDesktop. Web services are discovered and integrated automatically. |
|
Start simple, then grow into richer services and more advanced workloads without leaving the same platform. |
A clean command-line workflow and simplified management flow help new users get productive quickly. |
|
Built on a mature Linux foundation with a strong focus on dependable behavior and practical security defaults. |
Released under GPL-2.0 and open to community contributions, improvements, and ecosystem growth. |
| Area | Default |
|---|---|
| WebDesktop | 2000/tcp (HTTP), 2020/tcp (HTTPS) |
| Remote access | 23/tcp for Telnet before a root password is set, 22/tcp for SSH |
| Network mode | Uses DHCP and DHCPv6 by default |
| Firewall | Accepts inbound traffic from LAN; rejects inbound traffic from WAN except 2000/tcp and 2020/tcp |
More usage details are available in the User Guide.
CapOS separates system packages from user applications:
apkmanages CapOS itself: the kernel, drivers, WebDesktop, snapd, networking, storage, and other system components.snapdinstalls user applications directly from the official Snap Store.systemd-on-procdimplements the systemd command/unit boundary needed by systemd-centric software while keeping procd as PID 1.capos-webdesktoptalks to snapd over/run/snapd.socket, manages install/update/remove operations, and discovers Web entrypoints from Snap-owned listening sockets. It probes HTTP/HTTPS and proxies the best Web endpoint without a curated CapOS application catalog.
This means CapOS does not repackage third-party Snap applications or maintain a parallel application ecosystem.
| Resource | Link |
|---|---|
| Releases | GitHub Releases |
| Package repository | repo.capos.top |
| Quick start | Wiki Quick Start Guide |
CapOS welcomes contributors and maintainers. System components continue to use CapOS/OpenWrt packages, while user applications are installed from the official Snap Store. Application authors do not need a CapOS-specific package format.
| Topic | Link |
|---|---|
| Developer guide | CapOS Developer Guide |
| Application packaging | Snapcraft documentation |
| systemd compatibility | systemd-on-procd |
To make repository access easier across different regions, CapOS provides:
- Primary repository: https://github.com/fwerkor/capos
- Read-only mirror for users in Mainland China: https://gitcode.com/fwerkor/capos
Issues, discussions, and pull requests should be submitted through the GitHub primary repository.
To build your own firmware, use a GNU/Linux, BSD, or macOS system with a case-sensitive filesystem. Cygwin is not supported.
Required tools vary by distribution, but the typical dependency set includes:
binutils bzip2 diff find flex gawk gcc-6+ getopt grep install libc-dev libz-dev
make4.1+ perl python3.7+ rsync subversion unzip which
An automatic dependency installer is available at scripts/auto_install_dependencies.sh, but manual installation is recommended if the script does not match your environment.
Build steps:
- Run
bash ./scripts/auto_install_dependencies.shto install dependencies. - Run
make menuconfigto choose the target platform, toolchain, and packages. - Run
maketo build the firmware.
Use a non-root user for builds.
CapOS can also be built as a Linux OCI system image. The OCI build uses a separate tar-based root filesystem profile; normal firmware builds continue to use ArgosFS.
# linux/amd64 (default)
make capos-oci
# linux/arm64
make capos-oci CAPOS_OCI_TARGET=armsr/armv8The resulting *.oci.tar archive is written under the matching
bin/targets/<target>/<subtarget>/ directory. CAPOS_OCI_REF,
CAPOS_OCI_VERSION, and CAPOS_OCI_JOBS can be set to override the embedded
tag, image version, and build parallelism. CAPOS_OCI_REF must use standard
container tag syntax (for example, latest or v1.0-test).
The archive is a standard OCI Image Layout with /sbin/init as its entrypoint.
It is intended as a system container image; running the full CapOS service stack
and Snap confinement requires a sufficiently privileged container runtime and
host kernel support.
- GitHub Issues for bug reports and feature requests
- GitHub Discussions for questions, ideas, and community conversations
CapOS is licensed under GPL-2.0.
