{"id":44771618,"url":"https://github.com/tinkerbell/captain","last_synced_at":"2026-02-17T06:00:57.753Z","repository":{"id":337674318,"uuid":"1154712536","full_name":"tinkerbell/captain","owner":"tinkerbell","description":"In-memory Operating System Installation Environment for Executing Tinkerbell Workflows based on systemd","archived":false,"fork":false,"pushed_at":"2026-02-13T18:36:19.000Z","size":48,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-16T10:48:01.322Z","etag":null,"topics":["bare-metal","baremetal","containerd","linux","operating-system","os","systemd","tinkerbell"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tinkerbell.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-10T17:38:51.000Z","updated_at":"2026-02-13T18:36:24.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tinkerbell/captain","commit_stats":null,"previous_names":["tinkerbell/captain"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/tinkerbell/captain","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tinkerbell%2Fcaptain","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tinkerbell%2Fcaptain/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tinkerbell%2Fcaptain/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tinkerbell%2Fcaptain/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tinkerbell","download_url":"https://codeload.github.com/tinkerbell/captain/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tinkerbell%2Fcaptain/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29535934,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-17T05:00:25.817Z","status":"ssl_error","status_checked_at":"2026-02-17T04:57:16.126Z","response_time":100,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bare-metal","baremetal","containerd","linux","operating-system","os","systemd","tinkerbell"],"created_at":"2026-02-16T05:34:34.712Z","updated_at":"2026-02-17T06:00:57.743Z","avatar_url":"https://github.com/tinkerbell.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# CaptainOS\n\nA minimal, systemd-based in-memory OS for [Tinkerbell](https://tinkerbell.org) bare-metal provisioning.\n\nCaptainOS boots via PXE/iPXE, runs entirely from RAM as a compressed CPIO initramfs, and provides a container runtime environment for the [tink-agent](https://github.com/tinkerbell/tinkerbell) — the component that drives hardware provisioning workflows.\n\n## Output sizes (amd64)\n\n| Artifact | Size |\n| --- | --- |\n| `initramfs-amd64.cpio.zst` | ~88 MB |\n| `vmlinuz-amd64` | ~9.5 MB |\n\n## How it works\n\n1. The machine PXE boots a kernel (`vmlinuz`) and initramfs (`initramfs.cpio.zst`)\n2. A custom `/init` script transitions the rootfs to tmpfs, then exec's systemd\n3. systemd-networkd configures DHCP on all ethernet interfaces\n4. containerd starts, then `tink-agent-setup` pulls the tink-agent container image (configured via kernel cmdline), extracts the binary, and runs it as a host process\n5. tink-agent connects to the Tinkerbell server and executes provisioning workflows\n\n## Building\n\n**Prerequisites:** Docker (or Podman)\n\n```bash\n# Build with defaults (amd64, kernel 6.12.69)\n./build.sh\n\n# Build for ARM64\nARCH=arm64 ./build.sh\n\n# Use a local kernel source tree\nKERNEL_SRC=~/linux ./build.sh\n\n# Force kernel rebuild\nFORCE_KERNEL=1 ./build.sh\n\n# Force tool re-download\nFORCE_TOOLS=1 ./build.sh\n\n# Rebuild builder image without cache\nNO_CACHE=1 ./build.sh\n```\n\nOutput artifacts are placed in `out/`:\n\n- `out/initramfs-\u003carch\u003e.cpio.zst` — the initramfs\n- `out/vmlinuz-\u003carch\u003e` — the kernel\n\n### Other commands\n\n```bash\n./build.sh shell       # Interactive shell inside the builder container\n./build.sh clean       # Remove build artifacts\n./build.sh summary     # Print mkosi configuration summary\n./build.sh qemu-test   # Boot the image in QEMU for quick testing\n```\n\n## Architecture\n\nThe build has three stages, all running inside a Docker container:\n\n1. **Kernel compilation** (`scripts/build-kernel.sh`) — builds a Linux kernel from source using minimal defconfigs (`config/defconfig.{amd64,arm64}`)\n2. **Tool download** (`scripts/download-tools.sh`) — fetches pinned binary releases of the container runtime stack\n3. **mkosi image build** (`mkosi.conf`) — assembles a Debian Trixie CPIO initramfs with systemd, injecting the kernel, modules, and tools\n\n### Included tools\n\n| Component | Version | Purpose |\n| --- | --- | --- |\n| containerd | 2.2.1 | Container runtime |\n| nerdctl | 2.2.1 | Container CLI (Docker-compatible) |\n| runc | 1.4.0 | OCI runtime |\n| CNI plugins | 1.6.0 | Container networking (bridge, host-local, loopback, portmap, firewall, tuning) |\n\n### Key design decisions\n\n- **Custom `/init` instead of `MakeInitrd`** — systemd's initrd mode expects to switch-root to a real rootfs. CaptainOS runs entirely from RAM, so a custom init transitions rootfs → tmpfs before exec'ing systemd. This makes `pivot_root(2)` work for container runtimes.\n- **No UPX compression** — the final image is compressed with zstd level 19. Raw ELF binaries compress better under zstd than UPX-packed ones (UPX output looks like random data to zstd).\n- **iptables-nft backend** — uses the nftables-backed iptables for container networking, with the necessary `CONFIG_NF_TABLES_*` kernel options enabled.\n- **IP forwarding via sysctl** — enabled at boot for container network traffic.\n\n## Kernel cmdline parameters\n\nCaptainOS reads provisioning configuration from the kernel command line:\n\n| Parameter | Description |\n| - | - |\n| `tink_worker_image` | Container image for the tink-agent (e.g. `registry.example.com/tink-agent:latest`) |\n| `docker_registry` | Registry to pull from |\n| `registry_username` | Registry auth username |\n| `registry_password` | Registry auth password |\n| `tinkerbell_tls` | Set to `false` to disable TLS for tink-agent |\n| `syslog_host` | Remote syslog host (IP or hostname) |\n| `syslog_port` | Remote syslog port (default: 514) |\n| `insecure_registries` | Comma-separated list of registries to configure as HTTP |\n\n## Project layout\n\n```bash\n.\n├── build.sh                    # Main build orchestrator\n├── Dockerfile                  # Builder container definition\n├── mkosi.conf                  # mkosi image configuration\n├── mkosi.postinst              # Post-install hooks (symlinks, cleanup)\n├── mkosi.finalize              # Final image adjustments\n├── config/\n│   ├── defconfig.amd64         # Kernel config for x86_64\n│   └── defconfig.arm64         # Kernel config for aarch64\n├── scripts/\n│   ├── build-kernel.sh         # Kernel compilation script\n│   └── download-tools.sh       # Binary tool downloader\n└── mkosi.extra/                # Files overlaid into the image\n    ├── init                    # Custom PID 1 (rootfs → tmpfs → systemd)\n    └── etc/\n        ├── containerd/         # containerd configuration\n        ├── systemd/system/     # systemd units\n        ├── acpi/               # ACPI power button handler\n        ├── sysctl.d/           # Kernel tunables\n        └── os-release          # OS identification\n```\n\n## Testing with QEMU\n\n```bash\n./build.sh qemu-test\n\n# With extra kernel cmdline parameters\nQEMU_APPEND='tink_worker_image=reg.local/tink-agent:latest docker_registry=reg.local' ./build.sh qemu-test\n\n# With more resources\nQEMU_MEM=4G QEMU_SMP=4 ./build.sh qemu-test\n```\n\nThis boots the image in QEMU with a virtio NIC and serial console. `console=ttyS0 audit=0` is always appended. Press `Ctrl-A X` to exit.\n\n## License\n\nSee [Tinkerbell](https://github.com/tinkerbell/hook) for license information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftinkerbell%2Fcaptain","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftinkerbell%2Fcaptain","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftinkerbell%2Fcaptain/lists"}