poly-hammer-worker 0.1.0.dev5

Poly Hammer self-hosted GPU worker agent

ph-worker — Poly Hammer Self-Hosted GPU Worker

A CLI agent that connects your GPU workstation to the Poly Hammer Portal, letting you run AI inference jobs on your own hardware instead of consuming cloud credits.

Requirements

• NVIDIA GPU with CUDA drivers installed
• Docker with NVIDIA Container Toolkit (--gpus support)
• Python 3.11+
• An active Poly Hammer Portal account with a registered worker key

Installation

cd workers/self-hosted/client
uv sync

Quick Start

1. Check GPU compatibility

ph-worker check-gpu

This will display your GPU model, VRAM, CUDA version, CPU cores, and RAM.

2. Register a worker in the Portal

Navigate to the Workers page in the Poly Hammer Portal and click Add Worker. You'll receive a worker key (ph_worker_...) — save it, it's shown only once.

3. Start the worker

ph-worker start --worker-key ph_worker_XXXXXXXX

Or use environment variables:

export PH_WORKER_KEY=ph_worker_XXXXXXXX
export PH_PORTAL_URL=https://portal.polyhammer.com   # default
ph-worker start

The worker will:

1. Detect your GPU/CUDA capabilities
2. Send heartbeats to the portal
3. Long-poll for inference jobs
4. Pull the correct Docker image (tagged by CUDA version) on first job
5. Run inference in an isolated container with GPU access
6. Upload results and report completion

How It Works

Portal API  ←→  ph-worker agent  ←→  Docker (GPU container)
                    │                        │
                    ├── heartbeat (60s)       ├── JSON stdin (job)
                    ├── poll for jobs         ├── JSON stdout (progress)
                    ├── report progress       └── S3 upload (result)
                    └── report complete/fail

• Images are pre-built with model weights baked in — no download delays at inference time
• CUDA-versioned tags (cuda13.1, etc.) ensure compatibility with your local drivers
• Dynamic pulling — the worker automatically pulls the right image when it receives a job for a model it hasn't run before

Configuration

Option	Env Var	Default	Description
--worker-key	PH_WORKER_KEY	(required)	Worker API key from the portal
--portal-url	PH_PORTAL_URL	https://portal.polyhammer.com	Portal API base URL

Docker Image Tags

Worker images are published to GHCR with CUDA-versioned tags:

Image	Tag	Description
ghcr.io/poly-hammer/hy-motion-worker	cuda13.1	HY-Motion models (latest stable)
ghcr.io/poly-hammer/mdm-worker	cuda13.1	MDM models (latest stable)
	cuda13.1-<sha>	Pinned to a specific commit
	latest	Latest build (any CUDA version)

Troubleshooting

"No CUDA detected"

• Ensure NVIDIA drivers are installed: nvidia-smi
• The NVIDIA Container Toolkit must be installed for Docker GPU support

Container fails to start

• Verify Docker GPU support: docker run --rm --gpus all nvidia/cuda:13.1.0-base-ubuntu22.04 nvidia-smi
• Check Docker daemon is running: docker info

Worker shows OFFLINE in portal

• Heartbeats are sent every 60 seconds; the portal marks workers offline after 120 seconds
• Check network connectivity to the portal URL
• Verify your worker key is correct

Development

cd workers/self-hosted/client
uv sync --group dev