Install on Podman

Before you begin

Use Podman's native Libpod API, version 4 or newer. The rootless installation below manages resources belonging to your current user. It does not expose another user's or root's containers.

You need the server key from Setup and the Podman management plan feature. Mounting the API socket gives the agent that user's Podman permissions.

Start the rootless API and agent

systemctl --user enable --now podman.socket
podman run -d --name enderdash-agent \
  --restart unless-stopped \
  --group-add keep-groups \
  -e ENDERDASH_AGENT_KEY='<agentKey>' \
  -e CONTAINER_HOST=unix:///run/podman/podman.sock \
  -v enderdash-agent-data:/enderdash/data \
  -v "${XDG_RUNTIME_DIR}/podman/podman.sock:/run/podman/podman.sock" \
  ghcr.io/enderdash-com/enderdash-agent:latest

Run these commands from the intended user's login session, where XDG_RUNTIME_DIR is set. If a container named enderdash-agent already exists, update that installation instead of creating another.

Verify the scope

podman ps --filter name=enderdash-agent
podman logs --tail 100 enderdash-agent

Confirm Online, then open Podman in EnderDash. Compare its container list with podman ps -a as the same user.

Socket permission errors need a host-side fix. On SELinux systems, review the socket mount policy with the host administrator. Do not switch to a rootful socket merely to make a missing container appear.

Run as a Quadlet service

Use this instead of the direct podman run installation. The public Quadlet files manage the agent container and data volume.

mkdir -p ~/.config/containers/systemd
curl -fsSL https://raw.githubusercontent.com/enderdash-com/deploy/main/agent/quadlet/enderdash-agent.container \
  -o ~/.config/containers/systemd/enderdash-agent.container
curl -fsSL https://raw.githubusercontent.com/enderdash-com/deploy/main/agent/quadlet/enderdash-agent-data.volume \
  -o ~/.config/containers/systemd/enderdash-agent-data.volume
cat > ~/.config/containers/systemd/enderdash-agent.env <<'EOF'
ENDERDASH_AGENT_KEY=<agentKey>
EOF
chmod 600 ~/.config/containers/systemd/enderdash-agent.env
systemctl --user enable --now podman.socket
systemctl --user daemon-reload
systemctl --user start enderdash-agent.service
systemctl --user status enderdash-agent.service

The downloaded unit's [Install] section supplies startup activation. Podman-generated services cannot be enabled with systemctl enable. For operation outside login sessions, configure user lingering according to your host policy.

Host tools and updates

Quadlet management needs Linux and systemd in the agent's execution environment. Buildah actions need the Buildah CLI. Podman kube actions need the Podman CLI. A socket mount alone does not provide those tools or the host's user-service directories.

Update the container image through your container or service workflow, then verify the live panel. See container platform requirements and agent maintenance.