sdme 0.5.2

The systemd machine editor
Documentation

sdme

Run Linux distros as containers on your machine. Each container boots a real systemd init, so it looks and works like a normal system: services, journalctl, systemctl, the whole stack. Changes stay in the container; the base filesystem is never touched.

sudo sdme new

This uses your root filesystem as a template, creates an overlayfs snapshot, boots systemd inside it, and drops you into a shell. You can import other root filesystems (Ubuntu, Fedora, etc.) and use them as templates to spin up containers from. Changes are written to the overlayfs upper layer; the template is never modified.

Why sdme?

sdme containers are full systems, not single processes.

  • Full init: containers boot systemd. Services start, timers fire, journald collects logs. It looks and works like a real machine.
  • Test real scenarios: systemd units, multi-service setups, distro packaging, upgrade paths. Anything that needs a booted system.
  • Clone your machine: sudo sdme new gives you your system with your shell, your $HOME, and your configs.
  • Any systemd distro: Ubuntu, Fedora, Arch, NixOS, openSUSE, CentOS, CachyOS, and more. Import from OCI registries, tarballs, directories, or QCOW2 images.
  • OCI images too: run nginx, redis, postgres from Docker Hub as systemd services inside a booted system.
  • Kubernetes Pod YAML: deploy multi-container pods from standard manifests, with volumes, secrets, configmaps, and health probes.
  • No daemon: single static binary, no background service needed.

Install

curl -fsSL https://fiorix.github.io/sdme/install.sh | sudo sh

Install the container runtime for your distro:

sudo apt install systemd-container   # Debian / Ubuntu
sudo dnf install systemd-container   # Fedora / CentOS
sudo pacman -S systemd               # Arch (included in base)

Requires Linux with systemd 252+. Runs as root.

On macOS? See docs/macos.md for setting up a Linux VM with lima-vm, then install sdme inside it.

Quick start

# Clone your machine
sudo sdme new

# Import and boot Ubuntu
sudo sdme fs import ubuntu docker.io/ubuntu:24.04
sudo sdme new -r ubuntu

# Import and boot Fedora
sudo sdme fs import fedora docker.io/fedora:41
sudo sdme new -r fedora

What you can do

Manage containers

  • sdme new: create, start, and enter a container in one step
  • sdme create / start / stop / rm: full lifecycle control
  • sdme join: enter a running container
  • sdme exec: run a command inside a container
  • sdme ps: list containers with status and health
  • sdme logs: view container logs via journalctl
  • sdme enable / disable: auto-start containers on boot

Import and export filesystems

  • sdme fs import: from OCI registries, directories, tarballs, URLs, or QCOW2 images
  • sdme fs export: to directories, tarballs, or raw disk images (ext4/btrfs)
  • sdme fs build: build a rootfs from a config file with resumable steps
  • sdme fs ls / rm: list and remove imported filesystems

Run OCI application images

Run Docker Hub images (nginx, redis, postgres, etc.) as systemd services inside a booted container. Port bindings and volumes are wired through automatically.

Networking and security

Private networking, port forwarding, bind mounts, environment variables. Three security tiers: individual flags, --hardened, and --strict (seccomp filters, capability restrictions, AppArmor). User namespace support included.

Pods

Shared network namespaces for multi-container setups. Containers in a pod communicate over localhost.

Kubernetes Pod YAML

sdme kube apply -f pod.yaml --base-fs ubuntu creates multi-container pods from standard Kubernetes manifests.

Further reading

Every command is documented via sdme <command> --help.