diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index 8b265e5..26bfe9c 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -62,6 +62,15 @@ jobs:
           build-args: |
             VERSION=${{ github.ref_name }}
 
+      - name: Update Docker Hub description
+        uses: peter-evans/dockerhub-description@v4
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+          repository: torrentclaw/unarr
+          readme-filepath: DOCKERHUB.md
+          short-description: "Powerful terminal tool for torrent search and management"
+
   virustotal:
     needs: release
     runs-on: ubuntu-latest
diff --git a/DOCKERHUB.md b/DOCKERHUB.md
new file mode 100644
index 0000000..206138d
--- /dev/null
+++ b/DOCKERHUB.md
@@ -0,0 +1,130 @@
+# unarr
+
+Powerful terminal tool for torrent search and management. Search 30+ sources, inspect quality, discover popular content, find streaming providers, and manage downloads — all from your terminal.
+
+**[GitHub](https://github.com/torrentclaw/unarr)** | **[Documentation](https://github.com/torrentclaw/unarr#readme)** | **[Releases](https://github.com/torrentclaw/unarr/releases)**
+
+## Quick Start
+
+### 1. Setup (interactive wizard)
+
+```bash
+docker run -it --rm \
+  -v ~/.config/unarr:/config \
+  torrentclaw/unarr setup
+```
+
+### 2. Run the daemon
+
+```bash
+docker run -d --name unarr \
+  --restart unless-stopped \
+  --network host \
+  --read-only --memory 512m \
+  -v ~/.config/unarr:/config \
+  -v ~/Media:/downloads \
+  torrentclaw/unarr
+```
+
+## Docker Compose
+
+```yaml
+services:
+  unarr:
+    image: torrentclaw/unarr:latest
+    container_name: unarr
+    restart: unless-stopped
+    user: "1000:1000"
+    read_only: true
+    tmpfs:
+      - /tmp:size=64m,mode=1777
+    volumes:
+      - ./config:/config
+      - ~/Media:/downloads
+      - unarr-data:/data
+    environment:
+      - TZ=UTC
+      # - UNARR_API_KEY=tc_your_key_here
+    deploy:
+      resources:
+        limits:
+          memory: 512M
+          cpus: "2.0"
+    network_mode: host
+
+volumes:
+  unarr-data:
+```
+
+## Volumes
+
+| Path | Purpose |
+|------|---------|
+| `/config` | Configuration file (`config.toml`) |
+| `/downloads` | Finished media downloads |
+| `/data` | Internal state: torrent metadata, cache |
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `TZ` | Timezone | `UTC` |
+| `UNARR_API_KEY` | TorrentClaw API key | from config |
+| `UNARR_API_URL` | API endpoint | `https://torrentclaw.com` |
+| `UNARR_DOWNLOAD_DIR` | Download directory | `/downloads` |
+| `UNARR_CONFIG_DIR` | Config directory | `/config` |
+| `UNARR_COUNTRY` | Country code (ISO 3166) | `US` |
+
+## Networking
+
+**Host mode** (recommended) gives full P2P performance with no port management:
+
+```yaml
+network_mode: host
+```
+
+**Bridge mode** — more isolated, but requires explicit ports:
+
+```yaml
+ports:
+  - "6881-6889:6881-6889/tcp"
+  - "6881-6889:6881-6889/udp"
+```
+
+## Running Commands
+
+Use `docker exec` for one-off commands while the daemon is running:
+
+```bash
+docker exec unarr unarr search "inception" --quality 1080p
+docker exec unarr unarr popular --limit 10
+docker exec unarr unarr status
+docker exec unarr unarr doctor
+```
+
+## Supported Architectures
+
+| Architecture | Tag |
+|-------------|-----|
+| `linux/amd64` | `latest`, `0.3`, `0.3.5` |
+| `linux/arm64` | `latest`, `0.3`, `0.3.5` |
+
+## Tags
+
+| Tag | Description |
+|-----|-------------|
+| `latest` | Latest stable release |
+| `X.Y.Z` | Specific version (e.g. `0.3.5`) |
+| `X.Y` | Latest patch for minor version (e.g. `0.3`) |
+
+## Image Details
+
+- **Base image:** Alpine 3.21
+- **User:** `unarr` (UID 1000, GID 1000)
+- **Entrypoint:** `unarr start` (daemon mode)
+- **Read-only filesystem** — only mounted volumes are writable
+- **No root required** — runs as non-root by default
+
+## License
+
+MIT License — see [LICENSE](https://github.com/torrentclaw/unarr/blob/main/LICENSE) for details.