feat(multiuser mode): Support multiple isolated users on same backend

[lstein]

Summary

This enhancement introduces multiuser mode, which allows multiple users to share a single InvokeAI instance. The main use case is for friend and family sharing where the user can give the family access to a shared InvokeAI server on the home LAN, while isolating each individual so that they cannot see each others' boards, generated images, and image assets.

A privileged Administrator account is allowed to add and remove models, as well as alter their configuration and default parameters. Other users can view the models in read-only fashion, but cannot add new models or alter existing ones. The Administrator also has read-write access to all users' boards and images.

Websockets have been revised to isolate user sessions. A user can view the job queue and see where their jobs are relative to other user's jobs, but they cannot see the generation parameters (e.g. the prompt) of other users' jobs. Similarly, the preview image events are sent correctly to the user who initiated the generation.

Guided Tour

Multiuser mode is activated by placing multiuser: true in the Invoke configuration file. If this option is missing or False, then Invoke continues to operate as it previously did.

First launch

When Invoke is launched in multiuser mode for the very first time, it will prompt for an Administrator account:

After this one-time step, the administrator fills this out with their email address.

Logging in

Once at least one account is set up, InvokeAI will ask for login credentials when the page is loaded:

Once logged in, a new "User Profile" icon will appear on the left, just above the "What's New" icon. Clicking on this will display the user's login name, along with a yellow badge if logging in as an administrator:

If logged in as Administrator, the user will be able to do everything allowed by the traditional InvokeAI.

Adding a New User

Currently there is no GUI for managing users. For the time being, the administrator can use the invoke-useradd command to create regular users and assign their passwords. This script, along with other user management CLI commands, are installed by pyproject.toml when you run uv pip install -e ..

uv pip install -e .   # if not already done
invoke-useradd --email joeuser@example.com --name Joe --password TestPassword123
✅ User created successfully!
   User ID: 8a26af2a-31df-478c-b27b-9a03e6648791
   Email: joeuser@example.com
   Display Name: Joe
   Admin: No
   Active: Yes

This interface can also be used to add additional administrators. In addition to invoke-useradd, there is:

• invoke-userdel to delete a user
• invoke-usermod to modify a user, change password, add admin privileges, etc
• invoke-userlist list users in tabular or JSON format

User Login

When Joe logs in, his profile will lack the Admin badge:

Joe is free to create new boards, run generations with existing models, use the canvas and run workflows. He can view the models that are already installed, but cannot alter them. Joe has no access to other user's boards or images.

Job management

Joe can view the session queue and follow render job progress but other users' generation parameters will be hidden.
He can cancel his own jobs but not others'. (If he tries, he will get an Access Denied error message.)

When there are other users' jobs in the queue, the badge that appears on the queue menu button will display X/Y, where X is the number of pending jobs for the current user, and Y is the total number of pending jobs.

Read-only access to the Model Manager

Joe can see what models are installed, but not add or remove them. The user interface buttons to do this are gone, and the backend will not permit the corresponding endpoints to be called. The user can see a model's configuration and default parameters, but cannot save changes.

Administrator View

When someone with administrator privileges logs in, they will be able to see all the boards that each user has defined, browse their images, delete and move images, and edit board names. The name of the board's owner is displayed under the board name.

All images in "Uncategorized" will be pooled together into a single unified view. There is currently no way to distinguish one user's uncategorized image from anothers'.

Documentation

There is extensive documentation of the multiuser feature in the docs/multiuser directory, including a user guide, administrator's guide, an API guide and specifications. About a zillion new regression tests have been added to ensure correct behavior of the authentication system, user isolation, and restriction of unsafe API endpoints.

Limitations / Features in Progress

• Currently user accounts are managed by python command line scripts. This will be replaced by a user management GUI in the next iteration.
  • I am considering adding the ability to reset passwords via email and support Oauth2 authentication. However these features require network configuration, such as access to an outgoing SMTP server, that may be frustrating to our users.
• Another planned enhancement will allow users to designate shared boards that allow other users to access their image assets.
• Workflows are currently not isolated - one user can see all other users' workflows. This will be fixed in a future iteration.

Related Issues / Discussions

I keep getting asked by former customers of Invoke.ai to provide some sort of multiuser system for teams to share their assets. This is a step in the right direction, but really won't satisfy the use case until there is a robust system for federated processing on a cloud backend. Because of the single-threaded nature of the queueing system, if multiple users are trying to generate at once, they will quickly get frustrated at waiting for other user's jobs to run.

QA Instructions

Before you test, back up your database. This PR will do a database migration. Alternatively you can run it on an in-memory database by temporarily putting use_memory_db: true into your configuration file.

After pulling the PR, you will need to run uv pip install -e . because there are a couple of new dependencies.

Running as administrator

1. Add multiuser: true to your configuration file.
2. Navigate to http://localhost:9090
3. Fill out the Administrator credentials dialog (do not lose the password - it is nonrecoverable)
4. Log in
5. Browse around, make sure that
   • Image generation works
   • That you can create and edit boards, and move images from one board to another
   • That the canvas is working
   • That the node editor works
   • That you can add, delete and modify models
6. Log out using the User Profile dialog

Running as unprivileged users

Now create two users:

invoke-useradd --email joeuser@example.com --name Joe --password TestPassword123
invoke-useradd.py --email janeuser@example.com --name Jane --password TestPassword123

If you can, launch two different browsers, such as Chrome and Firefox (or Safari) and log in as Joe on one and Jane on the other. Running in two different tabs on the same browser will not usually work because the tabs will share the same authentication token.

1. In one browser, navigate to http://localhost:9090 and log in as joeuser@example.com
2. In the other browser, log in as janeuser@example.com
3. In each browser, check the following:
   • Boards created by one user cannot be seen by the other
   • Images generated by one user cannot be seen by the other
     • Check the Uncategorized board as well as the named boards
     • Check both Images and Assets
   • When image previews are being shown, make sure that Joe's previews are only visible to Joe, and the same for Jane.
   • Users can see Models but can't change them.
   • Users can see other user's queue jobs, but not the generation parameters (should display <hidden> instead)
   • Users can cancel their own jobs, but not others'
   • Do a generation as Joe and then reload his page. The previous generation parameters should be restored.
   • Reload Jane's page . Jane's last generation parameters should appear. There should be no leakage of Joe's generation parameters.
4. Log out of the Jane account.

Administrator mode again

1. Log in under the Administrator account again on the browser previously used for Jane.
   • Verify that you can see all users' boards and images.
   • Verify that the user's name is printed below their boards
   • Verify that you can delete images and move them form board to board
   • Start a generation on the open unprivileged user account (Joe) and confirm that the administrator can cancel it.
   • Start a generation as Administrator and confirm that Joe cannot cancel it.
2. Log out

Returning to single-user mode

1. Kill the server
2. Comment out the multiuser line in invokeai.yaml.
3. Restart the server and open a browser on it.
4. Do a shift-refresh to clear the browser cache of old Javascript
   • All boards from all users should be visible
   • No user names should appear under the boards
   • The user profile icon should be gone
   • All functions work as expected

NOTE: Queue User column. In both single-user and multiuser mode there is a new column in the Queue display that identifies the user who initiated the generation. Generations started in single-user mode will be owned by an internal user named "System". This column should maybe be suppressed in single-user mode? I'm not sure.

Merge Plan

This is a mammoth PR with too many commits to count! Sorry about this, but I made the mistake of rebasing against main several times over the course of a few weeks, and this makes it challenging to remove the small intermediate commits that I would ordinarily hide.

Many files were touched by this because of the need to pass the user id through multiple code paths. Hopefully the code is clean. I made lots of use of copilot code and copilot review for this, but did review the code as I went along.

This PR should use a Squash Merge to avoid cluttering up the commit history.

Checklist

• The PR has a short but descriptive title, suitable for a changelog
• Tests added / updated (if applicable)
• ❗Changes to a redux slice have a corresponding migration
• Documentation added / updated (if applicable)
• Updated What's New copy (if doing a release after this PR)

[JPPhoto]

Leaving comments prior to approval - things that need to be addressed in upcoming PRs after this is merged:

• What should happen to images generated by users when multiuser: false is set? What if it's set back to true?
• Global settings should be reviewed to see which are visible/changeable to non-admins (change logging level, clearing intermediates, etc.).
• Splash screens for the Viewer tab should be different for non-admins.
• We should address workflow and model visibility. Options:
  • Each user (admins included) has their own workflows and models.
  • Admins can set visibility of their own workflows and models to system-wide.
  • Workflows and models gain access groups.
  • Workflows and models can be enabled per-user.
  • Permissions for workflow creation/loading and model installation/loading.
• UIs for user management code.
• Optionally loosen password restrictions with a command-line option.

[JPPhoto]

This is a great feature and a fantastic major first step to true multi-user support. I recommend labeling this as experimental for now so everybody can have a turn testing it out, and that will have the advantage of locking these database changes down.

[Pfannkuchensack]

The clear endpoint in session_queue.py calls session_queue.clear(queue_id) which deletes ALL queue items for ALL users. The endpoint only checks ownership of the currently-executing item, but then unconditionally wipes the entire queue. A non-admin user can clear every other user's pending jobs. The underlying SqliteSessionQueue.clear() method has no user_id parameter, unlike prune and other similar methods that were updated for multi-tenancy.

InvokeAI/invokeai/app/api/routers/session_queue.py

Lines 327 to 346 in b4ab173

	async def clear(
	current_user: CurrentUserOrDefault,
	queue_id: str = Path(description="The queue id to perform this operation on"),
	) -> ClearResult:
	"""Clears the queue entirely. If there's a currently-executing item, users can only cancel it if they own it or are an admin."""
	try:
	queue_item = ApiDependencies.invoker.services.session_queue.get_current(queue_id)
	if queue_item is not None:
	# Check authorization for canceling the current item
	if queue_item.user_id != current_user.user_id and not current_user.is_admin:
	raise HTTPException(
	status_code=403, detail="You do not have permission to cancel the currently executing queue item"
	)
	ApiDependencies.invoker.services.session_queue.cancel_queue_item(queue_item.item_id)
	clear_result = ApiDependencies.invoker.services.session_queue.clear(queue_id)
	return clear_result
	except HTTPException:
	raise
	except Exception as e:
	raise HTTPException(status_code=500, detail=f"Unexpected error while clearing queue: {e}")

---

The resume and pause endpoints use AdminUser which requires an authenticated token. In single-user mode (default deployment), no tokens exist, so these endpoints return 401. Other admin-only endpoints correctly use AdminUserOrDefault which falls back to a system admin in single-user mode.

https://github.com/invoke-ai/InvokeAI/blob/b4ab173b3c7a1d4551b6be0fe45af9af9aeb8bd3/invokeai/app/api/routers/session_queue.py

---

Both endpoints inject current_user but never verify the board belongs to that user. The docstrings say "user must have access to it" but no validation occurs. Any authenticated user can modify or delete any other user's boards by board ID.

https://github.com/invoke-ai/InvokeAI/blob/b4ab173b3c7a1d4551b6be0fe45af9af9aeb8bd3/invokeai/app/api/routers/boards.py

---

The invoke-useradd function cannot work with --root, which is why I cannot create users if I use a different root directory.

---

Otherwise, the points from #8822 (comment)

[lstein]

@Pfannkuchensack Thanks so much for the review and for finding several security holes that I misised.

I've made these changes in the last series of commits:
✅ The session queue clear() endpoint now only clears the logged-in user's queue items. The administrator can clear the entire queue.
✅ The session queue resume() and pause() endpoints now work in single-user mode.
✅ The get_board(), update_board(), delete_board() and list_all_board_image_names() endpoints now respect the current user authorization.
✅ --root options added to all the invoke-user* commands.

I also found and fixed a bug in which the login credentials were persisting after changing from multiuser mode to singleuser mode.

[lstein]

Leaving comments prior to approval - things that need to be addressed in upcoming PRs after this is merged:

• What should happen to images generated by users when multiuser: false is set? What if it's set back to true?

The behavior right now is that when changing from multiuser to singleuser mode, all boards become visible to the single user. If two boards have the same name, they are both shown. All images in Uncategorized are merged into a single Uncategorized board.

If multiuser is turned on, the boards are restored to their previous multiuser visibility.

• Global settings should be reviewed to see which are visible/changeable to non-admins (change logging level, clearing intermediates, etc.).

Indeed. I'd like to defer this to a subsequent PR (Phase 2)

• Splash screens for the Viewer tab should be different for non-admins.

Agreed. I'd like to defer this to a subsequent PR (Phase 2)

• We should address workflow and model visibility. Options:

  • Each user (admins included) has their own workflows and models.
  • Admins can set visibility of their own workflows and models to system-wide.
  • Workflows and models gain access groups.
  • Workflows and models can be enabled per-user.
  • Permissions for workflow creation/loading and model installation/loading.

Agreed. I think this would be phased.

• Phase 2: Give each user their own private workflows and models.
• Phase 3: Establish groups, group privileges, and the ability to share assets within and across groups.

• UIs for user management code.

Phase 2

• Optionally loosen password restrictions with a command-line option.

Phase 2

[JPPhoto]

One follow-up question.

Leaving comments prior to approval - things that need to be addressed in upcoming PRs after this is merged:

• What should happen to images generated by users when multiuser: false is set? What if it's set back to true?

The behavior right now is that when changing from multiuser to singleuser mode, all boards become visible to the single user. If two boards have the same name, they are both shown. All images in Uncategorized are merged into a single Uncategorized board.

If multiuser is turned on, the boards are restored to their previous multiuser visibility.

Does this restoration include Uncategorized? So the merger is logical, not in-database?

[lstein]

One follow-up question.

Leaving comments prior to approval - things that need to be addressed in upcoming PRs after this is merged:

• What should happen to images generated by users when multiuser: false is set? What if it's set back to true?

The behavior right now is that when changing from multiuser to singleuser mode, all boards become visible to the single user. If two boards have the same name, they are both shown. All images in Uncategorized are merged into a single Uncategorized board.
If multiuser is turned on, the boards are restored to their previous multiuser visibility.

Does this restoration include Uncategorized? So the merger is logical, not in-database?

Yes, after a round trip from multiuser to singleuser back to multiuser, the Uncategorized images end up back where they started. This also includes images generated by admin.

[lstein]

@Pfannkuchensack Is there anything more that you'd advise prior to merging? If not, could you give an "approve?" Then I will get to work on the workflow isolation and user management UI.

Thanks.

[lstein]

@blessedcoolant I think you may be away because you've been quiet on Discord for a couple of weeks? I'm going to go ahead and merge this in.