ComfyUI-Manager/docs/en/v3.38-userdata-security-migration.md

ComfyUI-Manager V3.38: Userdata Security Migration Guide

Introduction

ComfyUI-Manager V3.38 introduces a security patch that migrates Manager's configuration and data to a protected system path. This change leverages ComfyUI's new System User Protection API (PR #10966) to provide enhanced security isolation.

This guide explains what happens during the migration and how to handle various situations.

---

What Changed

Finding Your Paths

When ComfyUI starts, it displays the full paths in the terminal:

** User directory: /path/to/ComfyUI/user
** ComfyUI-Manager config path: /path/to/ComfyUI/user/__manager/config.ini

Look for these lines in your startup log to find the exact location on your system. In this guide, paths are shown relative to the user directory.

Path Migration

Data	Legacy Path	New Path
Configuration	user/default/ComfyUI-Manager/	user/__manager/
Snapshots	user/default/ComfyUI-Manager/snapshots/	user/__manager/snapshots/

Why This Change

In older ComfyUI versions, the default/ directory was unprotected and accessible via web APIs. If you ran ComfyUI with --listen 0.0.0.0 or similar options to allow external connections, this data may have been tampered with by malicious actors.

Note: If you only used ComfyUI locally (without --listen or with --listen 127.0.0.1), your data was not exposed to this vulnerability.

The new __manager path uses ComfyUI's protected system directory, which:

• Cannot be accessed from outside (protected by ComfyUI)
• Isolates system settings from user data
• Enables stricter security for remote access

This is why only config.ini is automatically migrated - other files (snapshots) may have been compromised and should be manually verified before copying.

---

Automatic Migration

When you start ComfyUI with the new System User Protection API, Manager automatically handles the migration:

Step 1: Configuration Migration

Only config.ini is migrated automatically.

Important: Snapshots are NOT automatically migrated. You must copy them manually if needed.

Step 2: Security Level Check

During migration, if your security level is below normal (i.e., weak or normal-), it will be automatically raised to normal. This is a safety measure because the security level setting itself may have been tampered with in the old version.

======================================================================
[ComfyUI-Manager] WARNING: Security level adjusted
  - Previous: 'weak' → New: 'normal'
  - Raised to prevent unauthorized remote access.
======================================================================

If you need a lower security level, you can manually edit the config after migration.

Step 3: Legacy Backup

Your entire legacy directory is moved to a backup location:

user/__manager/.legacy-manager-backup/

This backup is preserved until you manually delete it.

---

Persistent Backup Notification

As long as the backup exists, Manager will remind you on every startup:

----------------------------------------------------------------------
[ComfyUI-Manager] NOTICE: Legacy backup exists
  - Your old Manager data was backed up to:
      /path/to/ComfyUI/user/__manager/.legacy-manager-backup
  - Please verify and remove it when no longer needed.
----------------------------------------------------------------------

To stop this notification: Delete the .legacy-manager-backup folder inside user/__manager/ after confirming you don't need any data from it.

---

Recovering Old Data

Snapshots

If you need your old snapshots, copy the contents of .legacy-manager-backup/snapshots/ to user/__manager/snapshots/.

---

Outdated ComfyUI Warning

If you're running an older version of ComfyUI without the System User Protection API, Manager will:

1. Force security level to strong - All installations are blocked
2. Display warning message:

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
[ComfyUI-Manager] ERROR: ComfyUI version is outdated!
  - Most operations are blocked for security.
  - ComfyUI update is still allowed.
  - Please update ComfyUI to use Manager normally.
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

Solution: Update ComfyUI to v0.3.76 or later.

---

Security Levels

Level	What's Allowed
strong	ComfyUI update only. All other installations blocked.
normal	Install/update/remove registered custom nodes and models.
normal-	Above + Install via Git URL or pip (localhost only).
weak	All operations allowed, including from remote connections.

Notes:

• strong is forced on outdated ComfyUI versions.
• normal is the default and recommended for most users.
• normal- is for developers who need to install unregistered nodes locally.
• weak should only be used in isolated development environments.

Changing Security Level

Edit user/__manager/config.ini:

[default]
security_level = normal

---

Error Messages

"comfyui_outdated" (HTTP 403)

This error appears when:

• Your ComfyUI doesn't have the System User Protection API
• All installations are blocked until you update ComfyUI

Solution: Update ComfyUI to the latest version.

"security_level" (HTTP 403)

This error appears when:

• Your security level blocks the requested operation
• For example, strong level blocks all installations

Solution: Lower your security level in config.ini if appropriate for your use case.

---

Security Warning: Suspicious Path

If you see this error on an older ComfyUI:

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
[ComfyUI-Manager] ERROR: Suspicious path detected!
  - '__manager' exists with low security level: 'weak'
  - Please verify manually:
      /path/to/ComfyUI/user/__manager/config.ini
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

On older ComfyUI versions, the __manager directory is not normally created. If this directory exists, it may have been created externally. For safety, manually verify the contents of this directory before updating ComfyUI.

---

Troubleshooting

All my installations are blocked

Check 1: Is your ComfyUI updated?

• Old ComfyUI forces security_level = strong
• Update ComfyUI to resolve

Check 2: What's your security level?

• Check user/__manager/config.ini
• security_level = strong blocks all installations

My snapshots are missing

Snapshots are not automatically migrated. You need to manually copy the snapshots folder from inside .legacy-manager-backup to the user/__manager/ directory.

I keep seeing the backup notification

Delete the .legacy-manager-backup folder inside user/__manager/ after confirming you don't need any data from it.

Snapshot restore is blocked

On old ComfyUI (without System User API), snapshot restore is blocked because security is forced to strong. Update ComfyUI to enable snapshot restore.

---

File Structure Reference

user/
└── __manager/
    ├── config.ini              # Manager configuration
    ├── channels.list           # Custom node channels
    ├── snapshots/              # Environment snapshots
    └── .legacy-manager-backup/ # Backup of old Manager data (temporary)

---

Requirements

• ComfyUI: v0.3.76 or later (with System User Protection API)
• ComfyUI-Manager: V3.38 or later