Sogni: Learn logo
Markdown
Running Sogni Fast Worker Locally cover image

⬇️Running Sogni Fast Worker Locally

The current installer creates a Docker Compose deployment, authenticates the worker, selects a supported worker image, and prepares the eligible model cache. Before installing, review the requirements and operator responsibilities.

Treat the worker as sustained GPU compute. Install it only on a physically stable system with adequate airflow, cooling, power delivery, free storage, and independent monitoring. Sogni's software controls cannot make an unsafe physical installation safe. See Protecting your hardware.

#Windows with Docker Desktop

Use Docker Desktop's Linux/WSL2 backend. This is the supported production-shaped Windows configuration; do not run worker workloads directly on bare-metal Windows unless Sogni support specifically asks you to test that path.

  1. Install a current NVIDIA driver for the GPU and restart Windows if the installer requests it.
  2. Install Docker Desktop for Windows and enable its WSL2 backend.
  3. Make sure the Docker/WSL2 VM has enough memory for the selected worker and leaves enough memory for Windows, drivers, and other applications. Avoid an undersized or heavily swapping VM.
  4. Download the Sogni Fast Worker Windows installer, extract the complete folder to a persistent local drive, and open that folder.
  5. Run worker-install.bat and follow the prompts for worker type, Sogni API key, and Fast Worker NFT token ID.
  6. Keep Windows awake, keep Docker Desktop running, and open dashboard.sogni.ai/fast-workers to confirm that the worker is online.

The worker folder contains the generated .env, Compose file, management scripts, persistent worker data, and—unless customized—its model cache. Do not move individual files out of that folder after installation.

Current Windows installers report both Windows RAM and the RAM actually usable by Docker's WSL2 VM. Larger Comfy video workloads generally need a WSL allocation of at least 40 GB; image workloads can need less. If the allocation is low during an interactive install or manual start, the installer can offer Update .wslconfig now? [y/N]. It changes only the [wsl2] memory entry after explicit confirmation, preserves the file's other settings/comments/encoding/line endings, and makes a timestamped backup. Automatic startup and noninteractive sessions only write advice to worker-wsl-memory.log; they never modify .wslconfig.

A saved memory change does not take effect immediately, and the installer never shuts WSL down for you. Stop the worker, quit Docker Desktop, save work in every WSL distribution, run wsl --shutdown as the user who runs Docker Desktop, reopen Docker Desktop, and start the worker again. Leave at least 16 GB for Windows on a PC with 64 GB or more, and additional headroom when other applications or GPU shared memory need it. Increasing swap is not a substitute for sufficient RAM.

#Linux with Docker Engine

  1. Install a current NVIDIA driver and confirm that nvidia-smi can see the GPU.

  2. Install Docker Engine for the distribution.

  3. Install and configure the NVIDIA Container Toolkit, then use NVIDIA's documented sample command to confirm that a Docker container can see the GPU.

  4. Download and extract the current Linux installer into a persistent directory:

    mkdir -p sogni-fast-worker && curl -L "https://api.sogni.ai/v1/download/worker/linux" | tar -xz -C sogni-fast-worker --strip-components=1

  5. Enter that directory, run ./worker-install.sh, and follow the prompts.

  6. Open dashboard.sogni.ai/fast-workers and confirm that the worker is online.

Docker group membership grants host-level privileges. If you choose to run Docker without sudo, follow Docker's Linux post-install guidance and account for that security model.

#Operate and update the worker

Run management scripts from the installation directory so they use the correct Compose project and .env file.

Action Windows Linux
Start worker-start.bat ./worker-start.sh
Stop worker-stop.bat ./worker-stop.sh
View diagnostic logs worker-debug.bat ./worker-debug.sh
Run the installer or change worker type worker-install.bat ./worker-install.sh

When a compatible online worker offers Upgrade worker, the dashboard can request a managed upgrade that finishes the current job before pulling and recreating the worker. If the banner offers Update instructions instead, follow the manual installer/update process from the worker folder. Afterward, verify the reported version, reconnect, and successful jobs in the Workers Dashboard.

Configuration edited in .env requires a restart. Current Comfy Workers can apply supported live settings from the dashboard; see Advanced Configuration.

#Multiple GPUs

The installer includes a generator for creating one Compose service per GPU. Each concurrently running GPU worker needs a unique Fast Worker NFT token ID, even when the workers use the same Sogni account API key. Follow Multiple GPUs on one host and size host RAM, storage, cooling, and power for the combined load.

#Troubleshooting

If the worker does not appear online:

  1. Confirm that Docker is running and the host is not asleep.
  2. Confirm nvidia-smi works on the host and that Docker has GPU access.
  3. Run the worker debug script and inspect the most recent startup error.
  4. Verify that the API key belongs to the account that owns the configured NFT token ID and that no other live worker is using that NFT.
  5. Check free disk space, host memory, Internet connectivity, and model-download progress.
  6. Review Active Job, Failed Jobs & Errors, Worker Health, and Worker Care in the dashboard.

An online worker can still receive little or no work when demand is low, when its cached/eligible model set does not match demand, or when faster eligible workers are available. Connection status is not an earnings guarantee.

For help, email [email protected] or join the Sogni Discord.

Last updated 2026-09-06