custom_nodes/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`:
```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