If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/Stability-AI/StableSwarmUI shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Stale — last commit 1y ago

• 6 active contributors
• MIT licensed
• ⚠ Stale — last commit 1y ago
• ⚠ Single-maintainer risk — top contributor 95% of recent commits
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live Stability-AI/StableSwarmUI repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Stability-AI/StableSwarmUI.

What it runs against: a local clone of Stability-AI/StableSwarmUI — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in Stability-AI/StableSwarmUI | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 459 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of Stability-AI/StableSwarmUI. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/Stability-AI/StableSwarmUI.git
#   cd StableSwarmUI
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of Stability-AI/StableSwarmUI and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "Stability-AI/StableSwarmUI(\\.git)?\\b" \\
  && ok "origin remote is Stability-AI/StableSwarmUI" \\
  || miss "origin remote is not Stability-AI/StableSwarmUI (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "src/Backends/AbstractT2IBackend.cs" \\
  && ok "src/Backends/AbstractT2IBackend.cs" \\
  || miss "missing critical file: src/Backends/AbstractT2IBackend.cs"
test -f "src/Backends/BackendHandler.cs" \\
  && ok "src/Backends/BackendHandler.cs" \\
  || miss "missing critical file: src/Backends/BackendHandler.cs"
test -f "src/BuiltinExtensions/ComfyUIBackend/ComfyUIAPIBackend.cs" \\
  && ok "src/BuiltinExtensions/ComfyUIBackend/ComfyUIAPIBackend.cs" \\
  || miss "missing critical file: src/BuiltinExtensions/ComfyUIBackend/ComfyUIAPIBackend.cs"
test -f "src/BuiltinExtensions/AutoWebUIBackend/AutoWebUIBackendExtension.cs" \\
  && ok "src/BuiltinExtensions/AutoWebUIBackend/AutoWebUIBackendExtension.cs" \\
  || miss "missing critical file: src/BuiltinExtensions/AutoWebUIBackend/AutoWebUIBackendExtension.cs"
test -f "src/Accounts/SessionHandler.cs" \\
  && ok "src/Accounts/SessionHandler.cs" \\
  || miss "missing critical file: src/Accounts/SessionHandler.cs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 459 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~429d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/Stability-AI/StableSwarmUI"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

StableSwarmUI is a modular web UI for Stable Diffusion image generation built in C# and JavaScript that emphasizes accessible power tools, high performance, and extensibility. It provides both a beginner-friendly Generate tab and an advanced Comfy Workflow tab for raw node-graph control, with features like ControlNet, IPAdapter, Grid Generator, and multi-GPU support. Full-stack monolith with C# backend (likely ASP.NET Core in root directories), JavaScript/HTML frontend (docs/APIRoutes/* and extension system), and Python integration (colab/colab-notebook.ipynb for cloud deployment). Extension system lives in extensible plugin architecture documented in docs/Making Extensions.md; modular API routes exposed via docs/APIRoutes/ covering T2I, ComfyUI, Admin, Models, and custom tool APIs.

AI image generation enthusiasts ranging from beginners (who want simple prompting) to advanced users (who need fine-grained workflow control), as well as developers building custom extensions via the modular plugin architecture documented in docs/Making Extensions.md.

Beta-stage (v0.6.4.1) with comprehensive documentation and active feature development visible in the file structure. However, the project transitioned from Stability AI maintenance (as of June 2024) to independent developer mcmonkeyprojects/SwarmUI, creating a maintenance boundary. Production-ready for most tasks but still evolving toward full release status.

Single-maintainer risk post-Stability AI transition (now maintained independently at mcmonkeyprojects/SwarmUI). The codebase is large (963K C#, 632K JavaScript) with Python backend integration (81K Python) creating dependency complexity. Users on the old Stability-AI/StableSwarmUI repo must manually migrate via git remote change or migrate-windows.bat script.

Project is in maintenance transition phase rather than active feature development on this fork. The independent SwarmUI fork at mcmonkeyprojects/SwarmUI is the actively maintained version. Migration guide and feature announcements are documented in GitHub discussions.

Clone the repository and use the Docker setup: git clone https://github.com/Stability-AI/StableSwarmUI.git && cd StableSwarmUI (note: migration to independent fork recommended), then use docker-compose up per docker-compose.yml, or run locally after installing C# dependencies (see docs/Command Line Arguments.md for configuration options).

Daily commands: After cloning, review docs/Command Line Arguments.md for startup flags. Run via Docker (docker-compose up) or native C# application execution. Frontend accessible via web browser post-launch. Colab users can run directly from colab/colab-notebook.ipynb.

• src/Backends/AbstractT2IBackend.cs — Core abstract backend interface that all AI model backends (ComfyUI, AutoWebUI, etc.) must implement; fundamental to understanding how Swarm interfaces with different generation engines.
• src/Backends/BackendHandler.cs — Central orchestrator that manages backend lifecycle, routing, and communication; critical for understanding request flow through the system.
• src/BuiltinExtensions/ComfyUIBackend/ComfyUIAPIBackend.cs — Primary concrete backend implementation connecting Swarm to ComfyUI; exemplifies how to integrate external AI services and handle async workflows.
• src/BuiltinExtensions/AutoWebUIBackend/AutoWebUIBackendExtension.cs — Secondary backend implementation showing alternative integration patterns; demonstrates extensibility architecture.
• src/Accounts/SessionHandler.cs — Manages user sessions and authentication state; essential for understanding how requests are associated with users and state is maintained.
• docs/API.md — Complete API contract documentation; required reading for understanding all client-server communication patterns and data structures.
• README.md — Project overview, status (Beta), migration notice to mcmonkeyprojects/SwarmUI, and feature positioning; context for all development.

Add a New Backend Implementation

1. Create new backend directory under src/BuiltinExtensions/ following ComfyUIBackend naming convention (src/BuiltinExtensions/ComfyUIBackend)
2. Create main backend class inheriting from AbstractT2IBackend and implementing all abstract methods (src/Backends/AbstractT2IBackend.cs)
3. Implement service initialization in *BackendExtension.cs following AutoWebUIBackendExtension pattern (src/BuiltinExtensions/AutoWebUIBackend/AutoWebUIBackendExtension.cs)
4. Register backend in BackendHandler by adding instantiation logic (src/Backends/BackendHandler.cs)
5. Add backend-specific API routes in docs/APIRoutes/ and document response formats (docs/APIRoutes/ComfyUIWebAPI.md)

Add a New API Endpoint

1. Define endpoint specification in appropriate APIRoutes doc (T2IAPI.md, ModelsAPI.md, AdminAPI.md, etc.) (docs/APIRoutes/T2IAPI.md)
2. Implement route handler in backend integration layer, calling BackendHandler methods as needed (src/Backends/BackendHandler.cs)
3. Register endpoint in authentication layer if session/user validation needed (src/Accounts/SessionHandler.cs)
4. Add API route documentation in docs/APIRoutes/BasicAPIFeatures.md for common patterns (docs/APIRoutes/BasicAPIFeatures.md)

Create a New Extension Feature

1. Create extension directory following src/BuiltinExtensions structure with README.md and main extension class (src/BuiltinExtensions/AutoWebUIBackend/README.md)
2. Define extension manifest and register with extension loader in AbstractT2IBackend (src/Backends/AbstractT2IBackend.cs)
3. Add static assets (CSS, JS) in Assets/ subdirectory if UI components needed (src/BuiltinExtensions/ComfyUIBackend/Assets/comfy_workflow_editor.css)
4. Document extension in docs/Making Extensions.md with setup and API usage instructions (docs/Making Extensions.md)

Add Multi-Language Support for New UI Text

1. Add English string key/value to base language file (languages/en.json)
2. Add translations to all supported language files (de.json, fr.json, ja.json, zh.json, es.json, it.json, pt.json, ru.json, ar.json, hi.json, nl.json, sv.json, vi.json) (languages/de.json)
3. Reference language key in frontend code using Swarm's localization system (docs/User Settings.md)

• C# / AS — undefined

Critical trap: This Stability-AI fork is no longer maintained (as of 2024/06/21). Users must migrate to mcmonkeyprojects/SwarmUI by running git remote set-url origin https://github.com/mcmonkeyprojects/SwarmUI or the provided migrate-windows.bat script—the old fork will become stale. GPU support requires proper driver setup (docs/Using More GPUs.md) and Docker GPU runtime for containerized deployments. Remote WebUI access via Google Colab may violate terms of service for free accounts. Python dependencies (rembg, ultralytics, dill) must be installed for image processing features; missing them silently degrades functionality rather than failing loudly.

• Node-Graph Workflow System — StableSwarmUI's Comfy Workflow tab exposes a node-graph paradigm for composing image generation pipelines; understanding node composition, edge connections, and data flow between nodes is essential for advanced feature work
• ControlNet — A key differentiator of StableSwarmUI (docs/Features/ControlNet.md); it allows spatial control over image generation via edge maps, depth maps, or pose skeletons—core to understanding power-user features
• Prompt Syntax & Tokenization — StableSwarmUI implements custom prompt parsing (docs/Features/Prompt%20Syntax.md) with syntax extensions; understanding tokenization, embedding weight adjustment, and prompt conditioning is vital for the Generate tab
• Multi-GPU Orchestration — StableSwarmUI supports distributed multi-GPU generation (docs/Using%20More%20GPUs.md); understanding GPU memory management, batch scheduling, and backend distribution is critical for scaling features
• IPAdapter & ReVision — Image Prompt Adapter and ReVision are advanced conditioning features (docs/Features/IPAdapter-ReVision.md) that use CLIP embeddings from images; understanding image-to-embedding pipelines is necessary for extension work
• REST API Versioning & Extension Points — StableSwarmUI exposes modular APIs (docs/APIRoutes/) for T2I, Admin, Models, ComfyUI workflows, and custom tools; understanding how endpoints are versioned and extended (via the Making Extensions system) is essential for integration
• Queue-Based Batch Processing — The UI shows a queue-based generation system (visible in docs/images/queue-running.png and API documentation); understanding job queueing, prioritization, and batch processing mechanics is necessary for understanding performance characteristics

• mcmonkeyprojects/SwarmUI — This is the actively maintained fork after Stability AI handed off maintenance; new users should clone from here instead of the archived Stability-AI version
• comfyanonymous/ComfyUI — StableSwarmUI wraps ComfyUI's node workflow engine; deep understanding of ComfyUI architecture is necessary for advanced workflow features
• AUTOMATIC1111/stable-diffusion-webui — Primary alternative UI for Stable Diffusion; understanding its architecture (Gradio-based) highlights why StableSwarmUI chose a custom web stack for extensibility
• stability-ai/generative-models — Official Stability AI model repository; required for understanding supported model formats and licensing constraints
• lllyasviel/ControlNet — ControlNet is a core StableSwarmUI feature (docs/Features/ControlNet.md); understanding the model's architecture is necessary for feature development

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive API integration tests for docs/APIRoutes endpoints

The repo has extensive API documentation across 8 separate route files (AdminAPI.md, BackendAPI.md, T2IAPI.md, ComfyUIWebAPI.md, ModelsAPI.md, UtilAPI.md, GridGeneratorExtension.md, ImageBatchToolExtension.md) but no visible test suite. Creating integration tests would ensure API contracts remain stable across refactors and help new contributors understand expected behavior. This is especially critical for a modular extension system.

• [ ] Create tests/api/ directory structure mirroring docs/APIRoutes/
• [ ] Add integration tests for core routes documented in BackendAPI.md and T2IAPI.md
• [ ] Add GitHub Actions workflow (.github/workflows/api-tests.yml) to run tests on PR
• [ ] Document how to run tests in CONTRIBUTING.md

Create missing documentation for extension development workflow in docs/Making Extensions.md

The repo emphasizes extensibility as a core feature and has docs/Making Extensions.md file listed, but based on the file structure, there's no detailed walkthrough for creating custom extensions (GridGeneratorExtension and ImageBatchToolExtension exist but aren't documented as examples). New contributors wanting to build extensions lack a hands-on guide with concrete examples.

• [ ] Expand docs/Making Extensions.md with step-by-step extension scaffold guide
• [ ] Add docs/Extensions/ExampleSimpleExtension.md showing a minimal working extension
• [ ] Document the extension lifecycle hooks and API surface with examples from GridGeneratorExtension
• [ ] Add troubleshooting section referencing CONTRIBUTING.md

Add GitHub Actions workflow for multi-platform Docker builds and Docker Hub publishing

The repo includes Dockerfile, docker-compose.yml, and launch-docker.sh but no CI/CD pipeline. With multiple language support (14 languages in languages/) and a migration to independent maintenance, automating Docker image builds across platforms (linux/amd64, linux/arm64) and publishing to Docker Hub would reduce manual maintenance burden and improve accessibility for users on different architectures.

• [ ] Create .github/workflows/docker-build.yml using docker/build-push-action
• [ ] Configure multi-platform builds using buildx (linux/amd64, linux/arm64)
• [ ] Add secrets configuration documentation in CONTRIBUTING.md for Docker Hub credentials
• [ ] Test workflow with a dry-run build on PR and publish on tagged releases

• Add automated tests for the API routes in docs/APIRoutes/ (BasicAPIFeatures.md, T2IAPI.md, etc.)—currently no test files visible in the repo structure for validating API contract correctness
• Expand docs/Features/README.md with a feature matrix table linking each feature to its corresponding API route and UI component file locations—currently features are scattered across separate .md files with no unified index
• Document the extension loading mechanism in docs/Making Extensions.md with a concrete example of a minimal extension (add a working example extension directory structure)—only prose docs exist without runnable sample code

• High · Unrestricted Port Exposure — Dockerfile (EXPOSE 7801) and docker-compose.yml (ports: 7801:7801). Port 7801 is exposed without authentication requirements visible in the Docker configuration. The application appears to be a web UI that could be accessible to unauthorized users if deployed on a network without proper firewall rules. Fix: Implement authentication/authorization mechanisms. Use a reverse proxy with SSL/TLS. Restrict port access via firewall rules. Consider using environment-based configuration for port binding to localhost only by default.
• High · Insecure Python Dependencies — Package dependencies (rembg, dill, ultralytics). The dependencies 'rembg', 'dill', and 'ultralytics' are included without version pinning. 'dill' is particularly concerning as it's a serialization library with known security risks when deserializing untrusted data. No lock file or requirements.txt with specific versions is visible. Fix: Pin all dependencies to specific versions using a requirements.txt or similar. Use 'dill' with extreme caution - validate all serialized data sources. Consider replacing dill with safer alternatives like pickle with restricted unpickling. Run regular dependency vulnerability scans using tools like safety or pip-audit.
• High · Missing HTTPS/TLS Configuration — Dockerfile, docker-compose.yml, and launch configuration. No evidence of HTTPS or TLS configuration in the Docker setup. The application exposes a web interface over HTTP, making it vulnerable to man-in-the-middle attacks and credential interception. Fix: Implement HTTPS with proper SSL/TLS certificates. Use a reverse proxy (nginx, Caddy) with SSL termination. Generate or obtain valid certificates. Document HTTPS setup in installation guides.
• High · Insecure Deserialization (dill library) — Package dependency: dill. The 'dill' library is a Python serialization module that can execute arbitrary code during deserialization. If the application accepts serialized data from users or untrusted sources, this creates a critical remote code execution vulnerability. Fix: Audit all uses of dill in the codebase. Replace with safer serialization formats (JSON, MessagePack) where possible. If dill is necessary, implement strict validation and sandboxing. Never deserialize untrusted data with dill.
• Medium · Docker Image Built from Slim Base — Dockerfile (FROM mcr.microsoft.com/dotnet/sdk:8.0-bookworm-slim and COPY . .). Using 'bookworm-slim' base image reduces attack surface but still includes development tools (build-essential). The Dockerfile copies entire repository into container without filtering unnecessary files. Fix: Use multi-stage builds to separate build and runtime environments. Use distroless or alpine base images for production. Add .dockerignore entries to exclude sensitive files, source code, and unnecessary artifacts. Use production-grade SDK/runtime images in final stages.
• Medium · Missing Security Headers — Web application configuration (not visible in provided files). No visible security headers (CSP, X-Frame-Options, X-Content-Type-Options, etc.) in the configuration. The application serves a web UI without apparent XSS protection headers. Fix: Implement security headers: Content-Security-Policy, X-Frame-Options: DENY, X-Content-Type-Options: nosniff, Strict-Transport-Security. Add these at the reverse proxy or application level.
• Medium · Volume Mounting Without Access Controls — docker-compose.yml (volumes configuration). Docker volumes for /Data, /dlbackend, /Models, and /Output are mounted without apparent access restrictions. Models directory is mounted from host filesystem which could contain sensitive files. Fix: Use read-only mounts where appropriate (e.g., /Models:ro). Implement proper file permissions on host system. Use Docker secrets for sensitive data instead of volumes. Validate file paths to prevent directory traversal attacks.
• Medium · GPU Driver Access — docker-compose.yml (gpu device driver configuration). Docker configuration grants GPU access without documented isolation or resource limits. Could potentially be exploited for side-channel attacks or resource exhaustion. Fix: Document GPU security implications. Implement resource limits (memory, CPU, GPU memory). Consider using separate

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.