Podman (rootless + Quadlet)

Podman is the bridge between "one Docker host" and "full Kubernetes". It runs the exact same OCI image as the other wrappers — rootless, with systemd-native lifecycle management via Quadlet.

Two deployment shapes

flowchart LR
    IMG[["moe-sovereign/orchestrator"]]:::art

    IMG --> Q["Quadlet unit<br/>single container<br/>(for edge/LXC)"]
    IMG --> KP["podman kube play<br/>Pod manifest<br/>(for multi-container bundles)"]

    Q -- systemd user --> SYS1[systemd]
    KP -- podman pod --> POD[Pod]

    classDef art fill:#eef2ff,stroke:#6366f1,font-weight:bold;

• Quadlet (deploy/podman/systemd/moe-orchestrator.container) is the right choice when you want systemd-native lifecycle for a single orchestrator container — used by the LXC wrapper.
• podman kube play (deploy/podman/kube.yaml) is the right choice when you want to bundle orchestrator + mcp + admin as a Pod that can later be lifted into Kubernetes without a rewrite.

Rootless execution

# Create a dedicated user (same UID the image expects)
sudo useradd -u 1001 -m moe
sudo loginctl enable-linger moe

# Pull and start
sudo -u moe podman pull ghcr.io/moe-sovereign/orchestrator:latest
sudo -u moe podman run -d --name moe \
    --user 1001 --read-only --tmpfs /tmp:rw \
    -p 8000:8000 \
    -v /home/moe/moe/logs:/app/logs:Z \
    -e MOE_PROFILE=team \
    ghcr.io/moe-sovereign/orchestrator:latest

No sudo docker and no privileged flags: Podman's user-namespace mapping handles everything.

Lifting a pod into Kubernetes

The Pod YAML at deploy/podman/kube.yaml is a valid Kubernetes manifest. The same file can be applied directly:

# Local: run as rootless Podman pod
podman kube play deploy/podman/kube.yaml

# Later, same YAML on k8s
kubectl apply -f deploy/podman/kube.yaml

This is the "compose → k8s bridge" that makes moving between tiers painless.

Why prefer Quadlet over podman generate systemd?

podman generate systemd is deprecated as of Podman 4.4. Quadlet is the successor: you drop a .container file into ~/.config/containers/systemd/, reload systemd, and a matching .service unit is auto-generated. See the LXC page for the full unit file.