@@ -7,14 +7,21 @@ Instance settings control authentication, storage, and memo policies. Admins can
 
 Common areas include:
 
+- Instance access policy: public or private access, stored independently of the canonical instance URL.
 - General access controls: user registration, password auth, username and nickname changes, week start day, and custom instance profile.
-- Storage settings: database, local filesystem, or S3-compatible attachment storage, file path templates, and upload limits.
+- Storage settings: named database, local filesystem, or S3-compatible configurations with stable IDs, a default for new uploads, file path templates, and upload limits.
 - Memo-related settings: content length limits, double-click editing, and allowed reaction values.
 - Notification settings: SMTP email delivery, sender details, reply-to address, and the email test endpoint.
 - AI settings: instance-level OpenAI or Gemini providers and speech-to-text transcription defaults.
 
 Tag colors and content-blur rules are user settings in Memos 0.30 and later, not instance settings. See [Tags](/docs/usage/tags).
 
+## Access policy
+
+In 0.31, the `ACCESS` setting determines whether anonymous visitors may read public content. `MEMOS_INSTANCE_URL` supplies the canonical external address and no longer changes an existing access policy. Use [deployment-managed access configuration](/docs/configuration/deployment-configuration#access-policy) when infrastructure should own this setting.
+
+Instance admins manage these policies but do not become members of every Space or gain editing authority over other authors' memos. See [Users & Roles](/docs/admin/users-roles).
+
 ## Sensitive settings
 
 Storage, notification, and AI settings can contain credentials. API responses do not return stored S3 secrets, SMTP passwords, or AI provider API keys in plaintext. When updating those settings, submit a new secret only when you intend to replace it.
 
@@ -3,9 +3,22 @@ title: Users & Roles
 description: Manage users and permissions.
 ---
 
-Memos supports two roles:
+Memos has two instance roles: **Admin** and **User**. The first account created during setup becomes an instance admin. Instance admins manage accounts, instance configuration, and access policy.
 
-- Admin
-- User
+## Instance roles and Space roles
 
-Admins can create users, update profiles, and manage access. The first account created during setup becomes an admin.
+Each [Space](/docs/usage/spaces) has its own accepted **Admin** and **User** memberships. Instance roles and Space roles are independent: an instance User can create and administer a Space, while an instance Admin has no automatic membership in another user's Space.
+
+Space admins manage the Space's metadata, invitations, and members. Neither kind of admin can edit another author's memo, change its visibility or placement, or manage its attachments, relations, or shares. Reading also follows the memo's visibility; instance administration does not grant access to private or members-only content.
+
+## Usernames
+
+Sign-in and username lookup are case-sensitive: `Alice` and `alice` are different spellings. New and renamed usernames must contain 1–36 ASCII letters or digits, with hyphens allowed only inside the name. Underscores, email addresses, and non-ASCII usernames cannot be newly assigned.
+
+Legacy usernames remain addressable with their exact spelling. Spellings outside the new grammar cannot be written as new mentions. See [Authentication](/docs/configuration/authentication) and [Mentions](/docs/usage/reactions-comments#mentions).
+
+## Removing access or accounts
+
+Removing a Space member leaves their contributions in that Space. A Space must always retain an active admin, so assign another admin before removing or archiving the last one.
+
+Deleting an account is blocked while it has active Space memberships, including when the API request sets `force`. Resolve those memberships first. Deleting a Space instead permanently deletes all directly assigned memos; it is not an equivalent way to remove one user's access.
@@ -35,6 +35,10 @@ Password auth is usually the right starting point when:
 
 Users sign in with their Memos username and password. Archived users cannot sign in. Failed sign-in attempts use the same error message for unknown usernames and wrong passwords, so the login page does not reveal whether a username exists.
 
+### Username spelling
+
+In 0.31, sign-in and lookup use exact-case usernames. `Alice` and `alice` are distinct spellings. New or renamed usernames must contain 1–36 ASCII letters or digits, with hyphens only inside the name. Existing legacy names remain addressable, but unsupported spellings cannot be used for new mentions. When diagnosing a failed sign-in after upgrading, check the stored username and its case before resetting credentials.
+
 ### Disable password authentication
 
 Admins can disable password sign-in for regular users after SSO is configured. When password auth is disabled:
 
@@ -1,11 +1,11 @@
 ---
 title: Deployment-Managed Configuration
-description: Manage authentication, storage, notifications, memo behavior, and AI settings from mounted JSON files.
+description: Manage access, authentication, storage, notifications, memo behavior, and AI settings from mounted JSON files.
 category: configuration
 tags: ["configuration", "self-hosting", "docker", "kubernetes"]
 difficulty: advanced
 estimatedTime: 15 minutes
-lastUpdated: "2026-07-22"
+lastUpdated: "2026-09-06"
 ---
 
 Memos 0.30 and later can load selected configuration from JSON files mounted under `/etc/secrets`. Use this when settings such as SSO, storage credentials, or registration policy should be controlled by Docker Compose, Kubernetes, GitOps, or a secret manager instead of the admin UI.
@@ -74,6 +74,7 @@ Memos scans direct children of `/etc/secrets` and reads only these filename patt
 | Resource | Filename | Stable key |
 | --- | --- | --- |
 | OAuth2 identity provider | `memos-idp-<label>.json` | `uid` |
+| Access policy (0.31+) | `memos-instance-setting-access.json` | `ACCESS` |
 | General settings | `memos-instance-setting-general.json` | `GENERAL` |
 | Storage settings | `memos-instance-setting-storage.json` | `STORAGE` |
 | Memo behavior | `memos-instance-setting-memo-related.json` | `MEMO_RELATED` |
@@ -136,6 +137,25 @@ See [Authentication](/docs/configuration/authentication) for provider setup and
 
 Each instance-setting file contains a `key` and the matching settings object. A file supplies the complete effective group: omitted scalar fields use their default values instead of inheriting values from the database. Empty secret fields are also treated as empty values.
 
+### Access policy
+
+In 0.31, use `memos-instance-setting-access.json` to select access independently of the canonical instance URL:
+
+```json
+{
+  "key": "ACCESS",
+  "accessSetting": {
+    "accessMode": "INSTANCE_ACCESS_MODE_PRIVATE"
+  }
+}
+```
+
+Use `INSTANCE_ACCESS_MODE_PUBLIC` to allow eligible anonymous public reads. The mode must be explicit; an omitted or unspecified mode is rejected. This setting does not revoke existing share links.
+
+Set `MEMOS_INSTANCE_URL` separately to the canonical external HTTP(S) URL. Credentials, queries, and fragments are not allowed. A private instance can have a canonical URL behind a reverse proxy.
+
+The first upgraded startup initializes a missing database access setting from the old URL-based behavior. Later URL changes do not change access. Upgrade every replica before changing the policy; older binaries still infer public access from the URL. See [Upgrading to 0.31](/docs/operations/upgrade#upgrading-to-031).
+
 ### General
 
 Use `memos-instance-setting-general.json` with `key: "GENERAL"`. The complete format is shown in the [Docker Compose quick start](#quick-start-with-docker-compose).
@@ -144,28 +164,37 @@ Use `memos-instance-setting-general.json` with `key: "GENERAL"`. The complete fo
 
 ### Storage
 
-Storage types are `DATABASE`, `LOCAL`, and `S3`. S3 requires all credential and location fields shown below.
+For 0.31, use named entries in `storages` and select one with `defaultStorageId`. Types are `DATABASE`, `LOCAL`, and `S3`. Each entry has a stable ID; existing attachments continue to use the configuration identified at upload time.
 
 ```json
 {
   "key": "STORAGE",
   "storageSetting": {
-    "storageType": "S3",
     "filepathTemplate": "assets/{timestamp}_{uuid}_{filename}",
     "uploadSizeLimitMb": "30",
-    "s3Config": {
-      "accessKeyId": "access-key",
-      "accessKeySecret": "secret-key",
-      "endpoint": "https://s3.example.com",
-      "region": "us-east-1",
-      "bucket": "memos-assets",
-      "usePathStyle": false,
-      "insecureSkipTlsVerify": false
-    }
+    "defaultStorageId": "team-assets",
+    "storages": [
+      {
+        "id": "team-assets",
+        "name": "Team assets",
+        "type": "S3",
+        "s3Config": {
+          "accessKeyId": "access-key",
+          "accessKeySecret": "secret-key",
+          "endpoint": "https://s3.example.com",
+          "region": "us-east-1",
+          "bucket": "memos-assets",
+          "usePathStyle": false,
+          "insecureSkipTlsVerify": false
+        }
+      }
+    ]
   }
 }
 ```
 
+Keep every configuration referenced by existing attachments when replacing this complete settings group. Changing the default affects new uploads only. Legacy `storageType` and top-level `s3Config` remain supported for compatibility, but new configurations should use the named format. This example requires 0.31; pin the candidate image to `neosmemo/memos:0.31.0-rc.1` when testing it before the stable release.
+
 Only enable `insecureSkipTlsVerify` for a trusted S3-compatible endpoint using a self-signed certificate. It disables TLS certificate verification.
 
 ### Memo behavior
 
@@ -17,9 +17,10 @@ All flags and their corresponding environment variables:
 | `--data` | `MEMOS_DATA` | auto | Data directory |
 | `--driver` | `MEMOS_DRIVER` | `sqlite` | Database backend (`sqlite`, `mysql`, `postgres`) |
 | `--dsn` | `MEMOS_DSN` | auto | Database connection string |
-| `--instance-url` | `MEMOS_INSTANCE_URL` | `` | Public instance URL; empty enables private mode |
+| `--instance-url` | `MEMOS_INSTANCE_URL` | `` | Canonical external URL; independent of access policy |
 | `--demo` | `MEMOS_DEMO` | `false` | Demo mode |
-| `--allow-private-webhooks` | `MEMOS_ALLOW_PRIVATE_WEBHOOKS` | `false` | Allow webhook URLs that resolve to private or reserved IP ranges |
+| `--webhook-private-network-allowlist` | `MEMOS_WEBHOOK_PRIVATE_NETWORK_ALLOWLIST` | empty | Allowed private destinations: exact hostnames, IP addresses, or CIDRs |
+| `--allow-private-webhooks` | `MEMOS_ALLOW_PRIVATE_WEBHOOKS` | `false` | Deprecated blanket exception for private webhook destinations |
 | `--log-level` | `MEMOS_LOG_LEVEL` | `info` | Log verbosity (`debug`, `info`, `warn`, `error`) |
 
 ### Data directory defaults
@@ -36,9 +37,16 @@ When `MEMOS_DRIVER=sqlite` and `MEMOS_DSN` is empty, the database file defaults
 
 ### Public and private mode
 
-Since Memos 0.30, an empty `MEMOS_INSTANCE_URL` puts the instance in **private mode**. Anonymous visitors are redirected to sign-in, RSS is unavailable, and anonymous API access is limited to setup, authentication, registration when allowed, and shared-memo routes.
+In Memos 0.31, access is controlled by the `ACCESS` instance setting, through `accessSetting.accessMode`:
 
-Set `MEMOS_INSTANCE_URL` to the canonical external URL when you intentionally want public profiles, public memos, Explore, RSS, and other anonymous reads. The value must include the scheme, for example `https://memos.example.com`.
+- `INSTANCE_ACCESS_MODE_PRIVATE`: anonymous visitors are sent to sign-in; anonymous API access is limited to endpoints such as setup, authentication, registration when allowed, and explicit shared memos.
+- `INSTANCE_ACCESS_MODE_PUBLIC`: eligible public memos, profiles, and Explore can be read anonymously.
+
+Configure access in instance settings or with a [deployment-managed JSON file](/docs/configuration/deployment-configuration#access-policy). It is not a runtime flag or environment variable.
+
+`MEMOS_INSTANCE_URL` supplies the canonical external address, including for a private instance behind a proxy. It must be an absolute HTTP(S) URL without credentials, a query, or a fragment, such as `https://memos.example.com`.
+
+When the access setting is first initialized, Memos preserves the earlier behavior: a configured URL initializes public access; an empty URL initializes private access. Once the setting exists, changing the URL never changes the access policy. See [Upgrading to 0.31](/docs/operations/upgrade#upgrading-to-031).
 
 ## Priority order
 
@@ -50,10 +58,10 @@ An explicit flag always wins over the environment variable for the same setting.
 
 ## Practical guidance
 
-- leave `MEMOS_INSTANCE_URL` empty for a private-only instance
-- set it to the canonical public URL when you want anonymous public access or when the app sits behind a proxy
+- select private or public access explicitly in the `ACCESS` instance setting
+- set `MEMOS_INSTANCE_URL` to the canonical external URL when the app sits behind a proxy
 - prefer explicit `MEMOS_DRIVER` and `MEMOS_DSN` when you are not using SQLite defaults
-- leave `MEMOS_ALLOW_PRIVATE_WEBHOOKS` disabled unless your webhook targets intentionally live on a trusted private network
+- allow only required private webhook destinations with `MEMOS_WEBHOOK_PRIVATE_NETWORK_ALLOWLIST`; leave the deprecated blanket option disabled
 - keep secrets such as database credentials outside committed compose files
 - treat these values as part of deployment config and back them up accordingly
 
 
@@ -15,9 +15,10 @@ Memos can be configured through command-line flags, `MEMOS_*` environment variab
 | `--data` | `MEMOS_DATA` | data directory |
 | `--driver` | `MEMOS_DRIVER` | database backend |
 | `--dsn` | `MEMOS_DSN` | database connection string |
-| `--instance-url` | `MEMOS_INSTANCE_URL` | public instance URL; empty enables private mode |
+| `--instance-url` | `MEMOS_INSTANCE_URL` | canonical external URL; independent of access policy |
 | `--demo` | `MEMOS_DEMO` | demo mode |
-| `--allow-private-webhooks` | `MEMOS_ALLOW_PRIVATE_WEBHOOKS` | allow webhook URLs that resolve to private or reserved IP ranges |
+| `--webhook-private-network-allowlist` | `MEMOS_WEBHOOK_PRIVATE_NETWORK_ALLOWLIST` | Allowed private destinations: exact hostnames, IP addresses, or CIDRs |
+| `--allow-private-webhooks` | `MEMOS_ALLOW_PRIVATE_WEBHOOKS` | deprecated blanket exception for private webhook destinations |
 | `--log-level` | `MEMOS_LOG_LEVEL` | log verbosity (`debug`, `info`, `warn`, `error`) |
 
 ## Configuration layers
@@ -27,7 +28,7 @@ Memos can be configured through command-line flags, `MEMOS_*` environment variab
 - instance settings control storage, registration, and some auth behavior
 - reverse proxy settings affect HTTPS, cookie behavior, and public URL correctness
 
-`MEMOS_INSTANCE_URL` is also an access-mode switch in Memos 0.30 and later. Leave it empty for private mode; set it to the canonical external URL to enable anonymous public surfaces such as Explore and RSS.
+In Memos 0.31, the `ACCESS` instance setting selects public or private access independently of `MEMOS_INSTANCE_URL`. Set the URL to the canonical external HTTP(S) address, including for private instances behind a proxy. Manage access in instance settings or a [deployment-managed access file](/docs/configuration/deployment-configuration#access-policy).
 
 ## Related topics
 
 
@@ -19,7 +19,8 @@ The JWT secret is auto-generated as a UUID on first run and stored in the databa
 
 ## Core recommendations
 
-- leave `MEMOS_INSTANCE_URL` empty for private mode; set it only when anonymous public access is intended and to the canonical URL used by your reverse proxy
+- select private access in the `ACCESS` instance setting when anonymous public access is not intended
+- set `MEMOS_INSTANCE_URL` to the canonical URL used by your reverse proxy; changing this URL does not change access policy
 - disable user registration if your instance is private
 - disable public memo visibility if you do not want any public content
 - use HTTPS in front of the instance
 
@@ -11,6 +11,14 @@ Memos supports three storage backends for attachments:
 
 Storage is usually configured at the instance level rather than purely through startup flags.
 
+## Named storage configurations
+
+In 0.31, storage settings contain named configurations with stable IDs. Choose a default for new uploads. Existing attachments retain their storage ID, so switching the default does not move old files or change where Memos reads them.
+
+Keep configurations that existing attachments still reference, including their credentials and backing objects. A new default is not a storage migration. Legacy settings migrate automatically on upgrade.
+
+API and deployment-file clients should use `storages` and `defaultStorageId`. The older `storageType` and top-level `s3Config` fields remain compatibility fields. See the [deployment configuration example](/docs/configuration/deployment-configuration#storage).
+
 ## Database storage
 
 Database-backed attachments are the default.
@@ -52,6 +60,12 @@ certificate verification for that connection, so use it only for an endpoint
 you control and trust. Prefer installing a trusted certificate whenever
 possible.
 
+### Authenticated delivery
+
+Memos proxies managed S3 files through its file routes and checks authorization there. Range requests support seeking and partial media reads. Managed S3 attachments no longer return presigned object URLs in `externalLink`; clients should use the Memos file route and preserve any share authorization supplied for a shared memo.
+
+Back up all referenced storage configurations alongside the database and file objects. Changing the default storage only affects new uploads.
+
 ## Operational reminders
 
 - set an upload limit appropriate for your environment
 
@@ -49,7 +49,7 @@ docker compose up -d
 
 - keep your data directory on persistent storage
 - place Memos behind a reverse proxy for HTTPS
-- leave `MEMOS_INSTANCE_URL` empty for private mode, or set it to the canonical public URL to enable anonymous public access
+- set `MEMOS_INSTANCE_URL` to the canonical external URL and configure private or public access separately through the [ACCESS setting](/docs/configuration/deployment-configuration#access-policy)
 - back up both the database and any local assets if you do not use database-backed attachment storage
 
 ## When to add more services
 
@@ -67,9 +67,10 @@ All `MEMOS_*` variables correspond directly to command-line flags. Common ones:
 | `MEMOS_DATA` | `/var/opt/memos` | Data directory |
 | `MEMOS_DRIVER` | `sqlite` | Database backend |
 | `MEMOS_DSN` | auto | Database connection string |
-| `MEMOS_INSTANCE_URL` | `` | Public instance URL; empty enables private mode |
+| `MEMOS_INSTANCE_URL` | `` | Canonical external URL; independent of access policy |
 | `MEMOS_DEMO` | `false` | Demo mode |
-| `MEMOS_ALLOW_PRIVATE_WEBHOOKS` | `false` | Allow webhook URLs that resolve to private or reserved IP ranges |
+| `MEMOS_WEBHOOK_PRIVATE_NETWORK_ALLOWLIST` | empty | Exact hostnames, IP addresses, or CIDRs allowed as private webhook destinations |
+| `MEMOS_ALLOW_PRIVATE_WEBHOOKS` | `false` | Deprecated blanket exception for private webhook destinations |
 | `MEMOS_LOG_LEVEL` | `info` | Log verbosity (`debug`, `info`, `warn`, `error`) |
 
 Typical example:
@@ -86,7 +87,7 @@ docker run -d \
   neosmemo/memos:stable
 ```
 
-The quick-start command at the top of this page omits `MEMOS_INSTANCE_URL`, so it runs in private mode. The example above enables public mode and anonymous public surfaces by setting the canonical external URL.
+On a fresh instance, the quick-start command initializes private access because it omits `MEMOS_INSTANCE_URL`. A configured URL initializes public access only when the access setting does not yet exist. In 0.31, select the desired `ACCESS` policy in instance settings or [deployment configuration](/docs/configuration/deployment-configuration#access-policy); changing the URL of an existing instance does not change that policy.
 
 ## External databases