ywpc05/localsend-cli repository overview

⁠LocalSend CLI Container

Run the official LocalSend⁠ CLI as a LAN file receiver in a podman container. Images are pre-built in the cloud (GitHub Actions) and pulled from Docker Hub — the container itself is never built locally.

简体中文⁠

⁠Features

• Host networking — multicast discovery and port 53317 work directly on the LAN
• Persistent config — settings live in config/localsend-cli/config.toml (mirrors the container's ~/.config/localsend-cli), survive rebuilds and recreates
• Pairing — press P once per device; paired devices are auto-accepted forever after
• Auto-update — resolves the latest GitHub release, pulls the pre-built image from Docker Hub and recreates the container (manual or via systemd timer)

⁠Requirements

• podman with podman-compose
• curl and python3 on the host
• (optional) an HTTP proxy reachable via HTTP_PROXY/HTTPS_PROXY if GitHub is not directly accessible

⁠Podman vs Docker

This project targets podman (podman compose, podman build, podman attach). If you use Docker, apply these changes:

1. Replace podman with docker in every command:
   • podman compose up -d --force-recreate → docker compose up -d --force-recreate
   • podman attach localsend → docker attach localsend
   • podman image prune -f → docker image prune -f
2. Remove userns_mode: keep-id from docker-compose.yml — it is a podman-only key. Docker maps container UIDs directly to host UIDs by default, so a bind mount owned by UID 1000 on the host is already writable by the container's UID 1000. Keep everything else in the file as-is.
3. build.sh only pulls, never builds. It resolves the latest release and pulls the pre-built image from Docker Hub (see Auto-update⁠). With Docker, run the equivalent docker pull ywpc05/localsend-cli:<version> + docker tag + docker compose up -d --force-recreate, or convert the script with sed -i 's/\bpodman\b/docker/g' build.sh.
4. The :z mount option is harmless on non-SELinux systems and works on SELinux-enabled Docker daemons as well; keep it.
5. Dockerfile, docker-compose.yml, .env.example and the systemd units are fully compatible as-is.

⁠Quick Start

cp .env.example .env        # then edit if needed
bash build.sh              # pulls the latest pre-built image and starts the container
systemctl --user enable --now localsend-update.timer   # weekly auto-update (optional)

⁠Usage

1. Devices on the LAN will discover the receiver by its alias (default localsend-nas) and can send files to it.
2. The first request from a new device needs a decision. Attach to the TUI:

   podman attach localsend
   

   Copy
   Press Y (accept), N (decline) or P (accept and pair). Paired devices are auto-accepted afterwards.
3. Detach with Ctrl+P, Ctrl+Q.

Received files land in the directory set in .env (LOCALSEND_DESTINATION).

⁠Configuration

⁠Auto-update

build.sh fetches the latest release tag from the GitHub API and compares it with the VERSION file (machine state, gitignored). On a new version it pulls the pre-built image from Docker Hub (ywpc05/localsend-cli, built by GitHub Actions) and recreates the container — the image is never built locally. If the CI build is not ready yet it exits with a warning and retries on the next run. Run manually with bash build.sh, or let the included systemd user timer do it weekly:

systemctl --user enable --now localsend-update.timer

⁠GitHub Actions build

The repository ships a GitHub Actions workflow⁠ that runs daily (Monday–Sunday 09:00 UTC), on every relevant push and on manual dispatch. It resolves the latest LocalSend release, checks Docker Hub for an existing image of that version and — only when a new version is found — builds and pushes the image (ywpc05/localsend-cli), tagging both latest and the release version.

You can use the pre-built image directly on any machine with Docker:

docker pull ywpc05/localsend-cli:latest
docker run -d --name localsend --network host \
  -v "$PWD/downloads:/downloads" \
  -v "$PWD/config:/home/localsend/.config" \
  ywpc05/localsend-cli:latest

Note the compose file (userns_mode: keep-id) is podman-specific; for Docker omit that key (see Podman vs Docker⁠).

⁠Notes

• The container occupies port 53317 on the host.
• Sending files from this host through the container is not possible while the receiver is running (port conflict). Run the CLI binary directly on the host instead.
• VERSION, .env and config/ are machine-specific and gitignored; commit the rest.

⁠Layout

├── Dockerfile          # multi-stage; version passed via --build-arg (no hardcoding)
├── docker-compose.yml # host network, keep-id userns, persistent config mount
├── build.sh           # check latest release → pull pre-built image → recreate
├── .env.example        # template for .env (LOCALSEND_DESTINATION)
└── config/             # persistent config & pairing data (gitignored)
    └── localsend-cli/
        ├── config.toml
        ├── identity.pem
        └── paired-v2.json