# 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

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

Install the container runtime for your distro:

```bash
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](docs/macos.md) for setting up a Linux VM
with lima-vm, then install sdme inside it.

## Quick start

```bash
# 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`.

- [docs/architecture.md](docs/architecture.md): internals, design, OCI
  bridging, Kubernetes mapping
- [docs/security.md](docs/security.md): container isolation model,
  comparison with other container runtimes
