Multi-User Administrator Guide

Overview

This guide is for administrators managing a multi-user InvokeAI installation. It covers initial setup, user management, security best practices, and troubleshooting.

Prerequisites

Before enabling multi-user support, ensure you have:

• InvokeAI installed and running
• Access to the server filesystem (for initial setup)
• Understanding of your deployment environment
• Backup of your existing data (recommended)

Initial Setup

Activating Multiuser Mode

To put InvokeAI into multiuser mode, you will need to add the option multiuser: true to its configuration file. This file is located at INVOKEAI_ROOT/invokeai.yaml. With the InvokeAI backend halted, add the new configuration option to the end of the file with a text editor so that it looks like this:

# Internal metadata - do not edit:
schema_version: 4.0.2

# Enable/disable multi-user mode
multiuser: true

Then restart the InvokeAI server backend from the command line or using the launcher.

Reverting to single-user mode

If at any time you wish to revert to single-user mode, simply comment out the multiuser line, or change “true” to “false”. Then restart the server. Because of the way that browsers cache pages, users with open InvokeAI sessions may need to force-refresh their browsers.

Queue Scheduling

The image generation queue is processed by a single worker, so jobs run one at a time. The session_queue_mode option controls the order in which pending jobs are selected:

Mode	Behavior
round_robin (default)	Interleaves jobs across users — each user is served one job before any user is served a second. A single user enqueuing a large batch can no longer monopolize the queue.
FIFO	Strict first-come, first-serve. Jobs run in the order they were enqueued (respecting priority), so a large batch drains completely before the next user’s jobs start.

Set it in invokeai.yaml:

multiuser: true
session_queue_mode: round_robin   # or FIFO

Or via the INVOKEAI_SESSION_QUEUE_MODE environment variable:

INVOKEAI_SESSION_QUEUE_MODE=FIFO

Note

session_queue_mode only applies in multiuser mode. In single-user mode the queue is always FIFO regardless of this setting, since all jobs belong to the same account.

Round-robin fairness is determined from when each user’s jobs were last started. Retained terminal queue history (see max_queue_history) does not slow dequeue scheduling — each dequeue’s cost scales with the number of users who currently have pending jobs, not with the size of the history.

First Administrator Account

When InvokeAI starts for the first time in multi-user mode, you’ll see the Administrator Setup dialog.

Setup Steps:

1. Email Address: Enter a valid email address (this becomes your username)

   • Example: [email protected] or admin@localhost for testing
   • Must be a valid email format
   • Cannot be changed later without database access

2. Display Name: Enter a friendly name

   • Example: “System Administrator” or your real name
   • Can be changed later in your profile
   • Visible to other users in shared contexts

3. Password: Create a strong administrator password

   • Minimum requirements:

     • At least 8 characters long
     • Contains uppercase letters (A-Z)
     • Contains lowercase letters (a-z)
     • Contains numbers (0-9)

   • Recommended:

     • Use 12+ characters
     • Include special characters (!@#$%^&*)
     • Use a password manager to generate and store
     • Don’t reuse passwords from other services

4. Confirm Password: Re-enter the password

5. Click Create Administrator Account

Important

Store these credentials securely! The first administrator account can reset the password to something new, but cannot retrieve a lost one.

Configuration

InvokeAI can run in single-user or multi-user mode, controlled by the multiuser configuration option in invokeai.yaml:

# Enable/disable multi-user mode
multiuser: true   # Enable multi-user mode (requires authentication)

# Optional password policy
strict_password_checking: true  # Enforce uppercase/lowercase/number requirements

JWT secrets are generated automatically and stored in the database. Session lifetimes default to 24 hours, or 7 days when the user selects “Remember me”. See Secret Key Management below if you need to rotate the JWT secret.

Mode Switching Behavior

Switching to Single-User Mode: If boards or images were created in multi-user mode, they will all be combined into a single unified view when switching to single-user mode.

Switching to Multi-User Mode: Legacy boards and images created under single-user mode will be owned by an internal user named “system.” Only the Administrator will have access to these legacy assets. A utility to migrate these legacy assets to another user will be part of a future release.

Migration from Single-User

When upgrading from a single-user installation or switching modes:

1. Automatic Migration: The database will automatically migrate to multi-user schema when multi-user mode is first enabled
2. Legacy Data Ownership: Existing data (boards, images, workflows) created in single-user mode is assigned to an internal user named “system”
3. Administrator Access: Only administrators will have access to legacy “system”-owned assets when in multi-user mode
4. No Data Loss: All existing content is preserved

Migration Process:

# Backup your database first
cp databases/invokeai.db databases/invokeai.db.backup

# Enable multi-user mode in invokeai.yaml
# multiuser: true

# Start InvokeAI (migration happens automatically)
invokeai-web

# Complete the administrator setup dialog
# Legacy data will be owned by "system" user

Legacy Asset Migration

A utility to migrate legacy “system”-owned assets to specific user accounts will be available in a future release. Until then, administrators can access and manage all legacy content.

User Management

Creating Users

Administrators can create and modify users (including other administrators) via a built-in web interface or using command-line scripts.

Via the Web Frontend:

Please see the Multi-User Guide’s section on Adding and Modifying Users for a walk-through.

Via Command Line Scripts:

Command-line User Management Scripts

Administrators can also use a series of command-line scripts to add, modify, or delete users. If you use the launcher, click the ”>” icon to enter the command-line interface. Otherwise, if you are a native command-line user, activate the InvokeAI environment from your terminal.

All command-line arguments are optional. The scripts will prompt you to provide any missing arguments.

The commands are:

Name	Function	Example CLI Usage
invoke-useradd	add a user	invoke-useradd --email [email protected] --name "Example User" --password "badpassword"
invoke-usermod	modify a user	invoke-usermod --email [email protected] --name "Mr. Example User" --password "8adsf2**%"
invoke-userdel	delete a user	invoke-userdel --email [email protected] --force
invoke-userlist	list all users	invoke-userlist

Pass the --help argument to get the usage of each script. For example:

> invoke-useradd --help
usage: invoke-useradd [-h] [--root ROOT] [--email EMAIL] [--password PASSWORD] [--name NAME] [--admin]

Add a user to the InvokeAI database

options:
  -h, --help            show this help message and exit
  --root ROOT, -r ROOT  Path to the InvokeAI root directory. If omitted, the root is resolved in this order: the $INVOKEAI_ROOT environment
                        variable, the active virtual environment's parent directory, or $HOME/invokeai.
  --email EMAIL, -e EMAIL
                        User email address
  --password PASSWORD, -p PASSWORD
                        User password
  --name NAME, -n NAME  User display name (optional)
  --admin, -a           Make user an administrator

If no arguments are provided, the script will run in interactive mode.

Data Loss

Deleting a user removes the user record and cascades to their sessions, board shares, sent invitations, and per-user client state. It does not delete the boards, images, videos, workflows, queue items, or style presets they created — those rows remain in the database, owned by a user_id that no longer exists, and will not appear in other (non-admin) users’ galleries. Administrators keep gallery visibility of the orphaned images and videos and can review or delete them from there. Physical media files in outputs/images and outputs/videos are also left in place: orphan image files can be removed with a gallery maintenance script, while video files should be deleted through the gallery (which removes the file along with the record) or cleaned up manually.

If you want their content gone as well, reassign or delete it before deleting the user. Back up the database first if recovery might be needed.

Viewing User Activity

Queue Management:

There is no separate admin-only queue view. When signed in as an administrator, the regular queue panel automatically shows every user’s queue items (each item is labelled with the submitting user’s display name or email), and you can cancel or clear any of them. There is no built-in UI to filter the queue by user; use your browser’s find-in-page to scan by name if needed.

Model Management

As an administrator, you have full access to the Model Manager and can install, edit and delete models just as in single-user mode. Unprivileged users, however, can view the models previously installed, but cannot add or modify them.

Security

Download URL Restrictions

These restrictions apply to every download the server performs on your behalf — model installs from URLs are the main case. (The old general-purpose /api/v1/download_queue REST endpoint, which accepted an arbitrary URL and destination path, has been removed.)

Downloads are refused when the URL resolves to a loopback, link-local or private-network address. This stops a download URL from being used to reach services that only the server can see, such as an admin interface bound to 127.0.0.1 or a cloud instance-metadata endpoint. Redirects are checked at every hop, so a public URL cannot bounce the server onto a private address.

If you install models from a mirror on your own network, re-enable those addresses in invokeai.yaml:

allow_private_download_urls: true

For security, the guarded downloader ignores ambient HTTP_PROXY, HTTPS_PROXY, and ALL_PROXY settings. It still honors REQUESTS_CA_BUNDLE, CURL_CA_BUNDLE, and .netrc. If direct outbound access is unavailable, set download_proxy to an explicit proxy whose destination policy blocks private addresses; proxy-side DNS cannot be checked by InvokeAI. Do not enable allow_private_download_urls merely to make an untrusted proxy work. The two settings are independent: download_proxy is honored whether or not allow_private_download_urls is enabled.

Strict Password Checking

It is recommended that you enable strict password checking. This will force all users to select good passwords that follow the “minimal requirements” below. Do this by adding strict_password_checking to the invokeai.yaml configuration file:

strict_password_checking: true

Password Policies

Minimal Requirements:

• Minimum 8 characters
• Must contain uppercase letters
• Must contain lowercase letters
• Must contain numbers

If strict_password_checking is active (recommended), then these minimal requirements will be enforced and users will not be able to proceed until they have picked a password that satisfies them. Otherwise, the user will simply be warned when they use a weak password.

Recommended Policies:

• Require 12+ character passwords
• Include special characters
• Implement password rotation every 90 days
• Prevent password reuse

Session Management

Session Security and Token Management:

This system uses stateless JWT tokens with HMAC signatures to identify users after they provide their initial credentials. The tokens will persist for 24 hours by default, or for 7 days if the user clicks the “Remember me” checkbox at login. Expired tokens are automatically rejected and the user will have to log in again.

At the client side, tokens are stored in browser localStorage. Logging out clears them. No server-side session storage is required.

The tokens include the user’s ID, email, admin status, and a revocation counter, along with an HMAC signature.

Revocation: A token proves identity only — expiry is not the only thing that can end a session. Every authenticated request re-reads the account from the database, so administrative changes take effect on the target’s next request, without waiting for their token to expire and without requiring them to log out:

• Role changes. The admin status carried in a token is ignored; each request uses the role currently recorded for the account. A demoted administrator loses administrative endpoints immediately, and a promoted user gains them without logging in again.
• Deactivation and deletion. Requests from a deactivated or deleted account are rejected, its open connections are closed, and any of its queue items are canceled — a running one stops at the next node, or is canceled rather than recorded as completed if it was already on its last one, and pending ones are rejected when they reach the front of the queue. A generation that reports its progress (image generation does) stops part-way through the node instead of running it out. Work already completed is not undone.
• Password changes. Changing or resetting a password increments the account’s revocation counter, which invalidates every token issued before it. All of that account’s other sessions are signed out, including any stolen token. The session that performed the change is issued a replacement automatically and stays signed in.

Changes made through the web UI apply to open connections immediately. Changes made with the invoke-usermod and invoke-userdel commands run in a separate process from the server: everything the server derives per request (above) still changes the instant the command commits, but connections that are already open — and generations that are already running — are re-checked on a periodic sweep, so stopping them can take up to about a minute. The sweep covers a running generation whether or not its owner still has the browser open.

If that sweep cannot read the database at all — the server is under enough load that its reads keep timing out, say — it does not assume the connections it cannot check are still entitled to what they hold. After a few consecutive failures, open connections lose their administrator privileges and stop receiving other users’ events, while staying connected; the privilege comes back on its own once the record can be read again. An administrator who sees admin-only updates go quiet during a period of database trouble is seeing this, not a change to their account.

That safeguard covers administrator privileges specifically. Closing a deactivated or deleted account’s connection still waits for a successful read, so while the database is unreadable such a connection keeps receiving that account’s own events until the sweep can confirm the change — every HTTP request it makes is rejected in the meantime, and it is closed as soon as a read succeeds.

Two limits are worth stating plainly. Revocation is enforced by this server, so a token remains cryptographically valid until it expires — anything that accepts these tokens without consulting the database would still honor it. And a session already in flight is stopped, not rewound: media already delivered to the client and outputs already written stay written.

Secret Key Management

Important: The JWT secret key must be kept confidential.

To generate tokens, each InvokeAI instance has a distinct secret JWT key that must be kept confidential. The key is stored in the app_settings table of the InvokeAI database within a field value named jwt_secret.

The secret key is automatically generated during database creation or migration. If you wish to change the key, you may generate a replacement using either of these commands:

# Python
python -c "import secrets; print(secrets.token_urlsafe(32))"

# OpenSSL
openssl rand -base64 32

Then cut and paste the printed secret into this Sqlite3 command:

sqlite3 INVOKE_ROOT/databases/invokeai.db 'update app_settings set value="THE_SECRET" where key="jwt_secret"'

(replace INVOKE_ROOT with your InvokeAI root directory and THE_SECRET with the new secret).

After this, restart the server. All logged in users will be logged out and will need to provide their usernames and passwords again.

Hosting a Shared InvokeAI Instance

The multiuser feature allows you to run an InvokeAI backend that can be accessed by your friends and family across your home network. It is also possible to host a backend that is accessible over the Internet.

By default, InvokeAI runs on localhost, IP address 127.0.0.1, which is only accessible to browsers running on the same machine as the backend. To make the backend accessible to any machine on your home or work LAN, add the line host: 0.0.0.0 to the InvokeAI configuration file, usually stored at INVOKE_ROOT/invokeai.yaml.

Here is a minimal example.

# Internal metadata - do not edit:
schema_version: 4.0.2

# Put user settings here - see https://invoke-ai.github.io/InvokeAI/configuration/:
multiuser: true
host: 0.0.0.0

After relaunching the backend you will be able to reach the server from other machines on the LAN using the server machine’s IP address or hostname and port 9090.

Making InvokeAI Accessible to the Internet

Use at your own risk

The InvokeAI team has done its best to make the software free of exploitable bugs, but the software has not undergone a rigorous security audit or intrusion testing. Use at your own risk.

It is also possible to create a (semi) public server accessible from the Internet. The details of how to do this depend very much on your home or corporate router/firewall system and are beyond the scope of this document.

If you expose InvokeAI to the Internet, there are a number of precautions to take. Here is a brief list of recommended network security practices.

HTTPS Configuration:

For internet deployments, always use HTTPS:

# Use a reverse proxy like nginx or Traefik
# Example nginx configuration:

server {
    listen 443 ssl http2;
    server_name invoke.example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://localhost:9090;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # WebSocket support
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Firewall Rules:

It is best to restrict access to trusted networks and remote IP addresses, or use a VPN to connect to your home network. Rate limit connections to InvokeAI’s authentication endpoint http://your.host:9090/api/v1/auth/login.

Backup and Recovery:

It is always a good idea to periodically backup your InvokeAI database and images, but especially so if the server is publicly accessible to the Internet.

Manual Backup:

# Stop InvokeAI
# Copy database file
cd INVOKE_ROOT
cp databases/invokeai.db databases/invokeai.db.$(date +%Y%m%d)

# Or create compressed backup
tar -czf invokeai_backup_$(date +%Y%m%d).tar.gz databases/

Automated Backup Script:

backup_invokeai.sh

#!/bin/bash
INVOKE_ROOT="/path/to/invoke_root"
BACKUP_DIR="/path/to/backups"
DB_PATH="$INVOKE_ROOT/databases/invokeai.db"
DATE=$(date +%Y%m%d_%H%M%S)

# Create backup directory
mkdir -p "$BACKUP_DIR"

# Copy database
cp "$DB_PATH" "$BACKUP_DIR/invokeai_$DATE.db"

# Keep only last 30 days
find "$BACKUP_DIR" -name "invokeai_*.db" -mtime +30 -delete

echo "Backup completed: invokeai_$DATE.db"

Schedule with cron:

# Edit crontab
crontab -e

# Add daily backup at 2 AM
0 2 * * * /path/to/backup_invokeai.sh

Restore from Backup:

# Stop InvokeAI
# Replace current database with backup
cd INVOKE_ROOT
cp databases/invokeai.db databases/invokeai.db.old  # Save current
cp databases/invokeai_backup.db databases/invokeai.db

# Restart InvokeAI
invokeai-web

Disaster Recovery — Complete System Backup:

Include these directories/files:

• databases/ — All database files
• models/ — Installed models (if locally stored)
• outputs/ — Generated images
• invokeai.yaml — Configuration file
• Any custom scripts or modifications

Recovery Process:

1. Install InvokeAI on new system
2. Restore configuration file
3. Restore database directory
4. Restore models and outputs
5. Verify file permissions
6. Start InvokeAI and test

Troubleshooting

User Cannot Login

Symptom: User reports unable to log in

Diagnosis:

1. Verify account exists and is active

   sqlite3 databases/invokeai.db "SELECT * FROM users WHERE email = '[email protected]';"

2. Check password (have user try resetting)

3. Verify account is active (is_active = 1)

4. Check for account lockout (if implemented)

Solutions:

• Reset user password
• Reactivate disabled account
• Verify email address is correct
• Check system logs for auth errors

Database Locked Errors

Symptom: “Database is locked” errors

Causes:

• Concurrent write operations
• Long-running transactions
• Backup process accessing database
• File system issues

Solutions:

# Check for locks
fuser databases/invokeai.db

# Increase timeout (in config)
# Or switch to WAL mode:
sqlite3 databases/invokeai.db "PRAGMA journal_mode=WAL;"

Forgotten Admin Password

Recovery Process:

1. Stop InvokeAI

2. Direct database access:

   sqlite3 databases/invokeai.db

3. Reset admin password (requires password hash):

   -- Generate hash first using Python:
   -- from passlib.context import CryptContext
   -- pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
   -- print(pwd_context.hash("NewPassword123"))
   
   UPDATE users
   SET password_hash = '$2b$12$...'
   WHERE email = '[email protected]';

4. Restart InvokeAI

Alternative Step 3

Remove the admin from the database entirely in order to trigger the setup process when InvokeAI restarts:

DELETE FROM users
WHERE email = '[email protected]';

Performance Issues

Symptom: Slow generation or UI

Diagnosis:

1. Check active generation count
2. Review resource usage (CPU/GPU/RAM)
3. Check database size and performance
4. Review network latency

Solutions:

• Limit concurrent generations
• Increase hardware resources
• Optimize database (VACUUM, ANALYZE)
• Add indexes for slow queries
• Consider load balancing

Migration Failures

Symptom: Database migration fails on upgrade

Prevention:

• Always backup before upgrading
• Test migration on copy of database
• Review migration logs

Recovery:

# Restore backup
cp databases/invokeai.db.backup databases/invokeai.db

# Try migration again with verbose logging
invokeai-web --log-level DEBUG

Configuration Reference

Complete Configuration Example for a Public Site

# invokeai.yaml - Multi-user configuration

# Internal metadata - do not edit:
schema_version: 4.0.2

# Put user settings here
multiuser: true

# Server
host: "0.0.0.0"
port: 9090

# Performance
enable_partial_loading: true
precision: float16
pytorch_cuda_alloc_conf: "backend:cudaMallocAsync"
hashing_algorithm: blake3_multi

Frequently Asked Questions

How many users can InvokeAI support?

The backend will support dozens of concurrent users. However, because the image generation queue is single-threaded, only one job runs at a time. By default jobs are scheduled round-robin across users, so each user is served one job per turn and no single user can monopolize the queue with a large batch. You can switch to strict first-come, first-serve ordering with session_queue_mode: FIFO — see Queue Scheduling.

A future version of InvokeAI may support concurrent execution on systems with multiple GPUs/graphics cards.

Can I integrate with existing authentication systems?

OAuth2/OpenID Connect support is planned for a future release. Currently, InvokeAI uses its own authentication system.

How do I audit user actions?

Full audit logging is planned for a future release. Currently, you can:

• Monitor the generation queue
• Review database changes
• Check application logs

Can users have different model access?

Currently all users can view and use all installed models. Per-user model access is a possible enhancement. Please let the development team know if you want this feature.

How do I handle user data when they leave?

Best practice:

1. Deactivate the account first
2. Transfer ownership of shared boards
3. After transition period, delete the account
4. Or keep the account deactivated for audit purposes

What’s the licensing impact of multi-user mode?

InvokeAI remains under its existing license. Multi-user mode does not change licensing terms.

Getting Help

Support

• General Documentation: InvokeAI Docs
• User Guide: For Users
• API Guide: For Developers
• Discord: Join Community
• GitHub Issues: Report Problems