Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/lllyasviel/Fooocus/llms.txt

Use this file to discover all available pages before exploring further.

By default, Fooocus runs without any authentication — anyone who can reach the web UI can use it. When you expose Fooocus beyond localhost (via --listen or --share), you should add HTTP basic authentication by placing an auth.json file in the main Fooocus directory before starting the application.

​
When authentication matters

Authentication is not needed when Fooocus is only accessible on 127.0.0.1 (the default). It becomes important in two scenarios:
  • --listen — you have bound Fooocus to a LAN or external IP, making it reachable from other machines on the network.
  • --share — you have enabled Gradio’s live endpoint, which creates a public URL accessible from anywhere on the internet.
Even for short-lived --share sessions, setting up auth.json prevents unexpected access while your share link is active.

​
Creating auth.json

Create a file named auth.json in the root of your Fooocus directory (the same directory that contains entry_with_update.py). The file must contain a JSON array of objects, each with a user key and either a pass key (plain-text password) or a hash key (SHA-256 hex digest of the password). 
[
  {"user": "alice", "pass": "password123"},
  {"user": "bob", "pass": "securepass"}
]
You can add as many user entries as you need. An example file is provided at auth-example.json in the repository: 
[
  {
    "user": "sitting-duck-1",
    "pass": "very-bad-publicly-known-password-change-it"
  }
]
The example file uses a publicly known password. Always replace it with a strong, unique password before using auth.json in any real deployment.

​
How authentication is applied

When Fooocus starts, modules/auth.py reads auth.json from the path defined in modules/constants.py (AUTH_FILENAME = 'auth.json'). If the file exists and contains at least one valid entry, authentication is automatically enabled for all UI access — no additional flags are required. Passwords stored as plain text (pass) are hashed with SHA-256 in memory at load time. You can also pre-hash passwords and store them directly as the hash value if you prefer not to store plain-text credentials on disk. 
# Simplified logic from modules/auth.py
auth_dict = load_auth_data(constants.AUTH_FILENAME)
auth_enabled = auth_dict != None   # True when auth.json is present and valid
If auth.json is absent or contains no valid entries, auth_enabled is False and the UI is open to all visitors.

​
Multi-user mode

The --multi-user flag pairs naturally with authentication. When enabled, each authenticated user session maintains its own independent generation queue and state, preventing one user’s jobs from blocking another’s. 
python entry_with_update.py --listen --multi-user
With auth.json present and --multi-user active, each user in the JSON file gets a separate, isolated session on the same Fooocus instance.

​
Using —share for temporary access

The --share flag registers a temporary public URL through Gradio’s sharing infrastructure: 
python entry_with_update.py --share
The URL expires when the Fooocus process stops. Combine it with auth.json for controlled temporary sharing: 
python entry_with_update.py --share
# Place auth.json in the Fooocus directory beforehand
--share is ideal for giving a collaborator brief access without configuring port forwarding or firewall rules. The Gradio .gradio.live endpoint handles the tunnel for you.

​
Security considerations

HTTP basic authentication transmits credentials in Base64 encoding, which is not encrypted. Anyone who can intercept the network traffic can decode the credentials. Do not rely on Fooocus’s built-in basic auth alone for sensitive deployments.For production use, place Fooocus behind a reverse proxy (such as nginx or Caddy) that terminates HTTPS, and let the proxy handle TLS. Only then does basic auth provide meaningful protection.
ScenarioRecommendation
Local use only (127.0.0.1)No auth.json needed
LAN sharing (--listen)Add auth.json with strong passwords
Public sharing (--share)Add auth.json; treat the link as temporary
Internet-facing deploymentUse a TLS-terminating reverse proxy + auth.json

Build docs developers (and LLMs) love

Get started for freeTalk to us