Skip to content

Instance settings

The settings that define how your instance is run: registration mode, post length, default locale, who can see the timelines, the instance name, description, terms, rules, theme, and custom emoji.

Configuration Instance settings
What How the deployment is built: roles, adapters, endpoints, host names, secrets How the instance is run: registration mode, post length limit, default locale, who can see the timelines, the instance name, description, and terms
Where Environment variables MY_* and the configuration file (configuration reference) The database. Every change is kept as a revision
Changing Takes effect when the process restarts Takes effect immediately with my instance set, the admin screens of the web client, or the client API (admin screens and the client API)
When unset The default in the schema (the server does not start if the key is required) The default defined in the code
  • No key is in both. Neither overrides the other. You cannot give an instance setting through an environment variable or the configuration file, and you cannot store a configuration value in the database.
  • A value that is fixed per deployment and changes the structure of the process is configuration; a value that changes while the instance is running is an instance setting.
  • The configuration is given as described in the configuration reference (my config check).
  • The schema is applied to the database (my schema apply; see Database).
Key Type Default Description
registration_mode open / approval / invite / closed approval The registration mode (registration). While a service shutdown is announced and after it is closed, and on a one-person server, the effective value is closed. The stored value does not change, and cancelling the announcement or turning single_user off restores it. GET /instance and NodeInfo show the effective value
max_status_length integer 1-100000 500 The maximum length of a post, in characters
default_locale BCP 47 language tag en The default locale. It is the initial UI locale of new users, and the fallback when no catalog matches a user’s preference
local_timeline_visibility off / signed_in / everyone everyone Who can see the local timeline (GET /api/v1/timelines/local): nobody, signed-in users, or everyone. off answers 404 and signed_in answers visitors who are not signed in with 401; in both cases the navigation hides it. Unless the value is everyone, the landing page shows no sample posts. On a one-person server it reads as off
federated_timeline_visibility off / signed_in / everyone signed_in Who can see the federated timeline (GET /api/v1/timelines/federated). The values mean the same as for the local timeline, and it reads as off on a one-person server too
preview_image media ID (empty = unset) empty The link preview image (og:image) for the pages without an image of their own, under “Link previews” on Settings → General. When unset, the thumbnail, then the logo, then the bundled image is used (link previews)
contact_account username of a local account (empty = unset) empty The account to contact the operators. See contact and thumbnail
contact_email email address (empty = unset) empty The email address to contact the operators. It is also the Reply-To and the signature of the emails the server sends
thumbnail media ID (empty = unset) empty An image that represents the instance (thumbnail), on the about and landing pages, and in link previews when preview_image is unset
remote_media_policy none / avatars / all none Whether to keep copies of remote media. none: the media proxy relays every request. avatars: avatars, headers, and custom emoji are cached in blob storage for remote_media_cache_ttl_seconds. all: all remote media is. The total size of the cache is limited by the configuration remote_media_cache_max_bytes
remote_media_cache_ttl_seconds integer 60-31536000 (seconds) 86400 How long fetched remote media may be kept. It is also the Cache-Control: max-age of the media proxy responses, so CDNs and browsers cache for this long
remote_media_cache_max_bytes integer from 1 (bytes) 1073741824 The size limit of the copies of remote media the media proxy keeps. The hourly cleanup deletes the expired copies, then the least recently accessed ones over this limit
authorized_fetch true / false false Authorized Fetch (secure mode). When true, an ActivityPub GET without a verifiable HTTP signature is answered with 401 for objects and collections, and with a minimal document that carries the key for a user’s actor. The instance actor always returns its whole document, so any server can fetch the key to verify a signature
federation_mode off / inbound / outbound / both both The direction of federation. off: no federation. inbound: you follow and read remote accounts, but local posts, profiles, and reactions are not sent out, and follows from outside are refused (Reject). outbound: you accept follows from outside and deliver local posts, but remote posts and reactions are not taken in. both: send and receive. A change takes effect at once and needs the permission manage_settings
federation_scope open / allowlist open Which servers this server federates with. open: every server that no domain action suspends. allowlist: only the domains on the allowlist and their subdomains; every other server is treated as suspended, and ActivityPub GETs need a signature from an allowed server whatever authorized_fetch says. Switching to allowlist ends the follows with the servers it cuts off for good; see federating only with allowed servers. A change takes effect at once and needs the permission manage_settings
dynamic_client_registration true / false true Dynamic client registration (RFC 7591). While true, POST /oauth/register accepts the registration of public clients without authentication. When false, the endpoint refuses every request with 403 (access_denied); clients that are already registered keep working. A periodic job deletes dynamically registered clients that are not used, following the configuration dynamic_client_unredeemed_retention and dynamic_client_idle_retention. A change takes effect at once and needs manage_settings
domain_actions_visibility off / signed_in / everyone off Who can see the list of domains with actions taken (GET /api/v1/instance/domain_actions): nobody, signed-in users, or everyone (moderation)
domain_actions_rationale_visibility off / signed_in / everyone off Who can see the public comments of that list. Someone who cannot see the list never sees them
appeal_window_days integer 20-365 (days) 180 How many days after an action the person concerned can appeal (moderation). Changing it also changes the deadline of actions already taken
session_origins_retention_days integer 90-3650 (days) 180 How many days after a login to keep the IP address and User-Agent of the login (moderation)
registration_origins_retention_days integer 90-3650 (days) 180 How many days after registration to keep the IP address of the registration
reports_retention_days integer 180-3650 (days) 365 How many days after the last resolution to keep a report. A report that an action refers to is kept as long as the action
moderation_actions_retention_days integer 180-3650 (days) 365 How many days after the end of an action (the lift, the expiry, or the review of an appeal, whichever is later) to keep account actions and appeals
audit_log_retention_days integer 365-3650 (days) 730 How many days after being recorded to keep an audit log row
remote_status_retention_days integer 1-3650 (days) 90 How many days a remote post is kept after its publication when nothing on this instance refers to it (a local reply, boost, favourite, bookmark, notification, or a thread with a local post)
remote_status_max_retention_days integer 0-3650 (days) 0 The most days any remote post is kept after its publication, even when this instance refers to it. Local replies, boosts, favourites, and bookmarks stay and show it as deleted. 0 sets no limit
relay_status_retention_days integer 1-3650 (days) 7 How many days a remote post that only a relay brought in is kept, when nothing on this instance refers to it and no local account follows its author
oauth_client_rate_limits comma-separated client_id=requests pairs empty Caps on the client API requests of OAuth clients, to hold back a client that overloads the server: the requests all its users together may make in 5 minutes. A change takes up to a minute to apply
search_indexing allow / deny deny Whether search engines may index the instance. Even with allow, only the profiles of indexable accounts and public posts are indexed (search engines and AI crawlers)
ai_usage allow / deny_training / deny deny The statement to AI services. deny_training refuses training; deny refuses training and use by AI (AI search, assistants, agents)
indexable_default true / false false The default of indexable for new accounts. Changing it does not change existing accounts
auto_delete_default_enabled true / false false Whether new accounts start with the automatic deletion of their old posts on. With the other auto_delete_default_* keys it is the policy that a new account receives (automatic deletion of old posts)
auto_delete_default_min_age_days integer 1-3650 (days) 30 How many days after its publication the policy of a new account deletes a post
auto_delete_default_keep_pinned, auto_delete_default_keep_bookmarked, auto_delete_default_keep_favourited true / false true Whether the policy of a new account keeps the posts its author pinned, bookmarked, or favourited
auto_delete_default_keep_media, auto_delete_default_keep_polls true / false false Whether the policy of a new account keeps the posts with media or a poll
auto_delete_default_keep_articles true / false true Whether the policy of a new account keeps articles
auto_delete_default_keep_public, auto_delete_default_keep_local, auto_delete_default_keep_unlisted, auto_delete_default_keep_private true / false false Whether the policy of a new account keeps the posts of that visibility
auto_delete_default_keep_direct true / false true Whether the policy of a new account keeps direct posts
auto_delete_default_keep_min_boosts, auto_delete_default_keep_min_favourites integer 0-1000000 0 The policy of a new account keeps a post boosted or favourited at least this many times. 0 sets no threshold
auto_delete_max_age_days integer 0-3650 (days) 0 The most days after its publication that any local post is kept (maximum). 0 sets no maximum
auto_delete_max_allow_pinned true / false true Whether pinned posts may still be kept under the maximum
auto_delete_max_kept_pins integer 1-5 5 How many pins keep posts under the maximum, the most recently pinned first. 5, the most pins of an account, keeps every pinned post
auto_delete_max_allow_bookmarked, auto_delete_max_allow_favourited, auto_delete_max_allow_media, auto_delete_max_allow_polls true / false false Whether the posts that the author bookmarked or favourited, or with media or a poll, may still be kept under the maximum
auto_delete_max_allow_articles true / false true Whether articles may still be kept under the maximum
auto_delete_max_allow_visibilities true / false false Whether posts may still be kept by their visibility under the maximum
auto_delete_max_allow_thresholds true / false false Whether posts may still be kept by their boosts and favourites under the maximum
auto_delete_grace_days integer 0-365 (days) 30 How many days an account that the maximum newly applies to keeps its own settings after it is told. A change does not move the dates of the accounts already told
search_visibilities public / local / public,local public Which posts the full-text search of a server with a search backend covers. unlisted, private, and direct posts are never covered, and only accounts with indexable are. Leaving a visibility out removes its posts from the index. Adding one finds only new posts of it, until you rebuild the index. It does nothing with search = none
security_contact https: or mailto: URI (empty = unset) empty Where to report security problems of this server: how it is configured and run, and its accounts and data. When set, the server serves /.well-known/security.txt (RFC 9116). This is your contact, not the software’s: forward a report of a vulnerability in the software itself to the project as its security policy describes
require_media_description true / false false Whether every media file (image, video, or audio) attached to a local post needs a description. When true, a post or an edit with a file whose description is missing or only whitespace is rejected with 422. It is published as limits.require_media_description in GET /api/v1/instance, and the web client makes the description field required. It is separate from the per-user setting require_media_description, which only checks before sending
link_cards true / false true Whether to show cards for links in posts. When true, the server fetches the linked page to build a card. When false, it stops fetching and also hides cards already built. To stop it only on some domains, see link card domains
link_cards_ignore_robots_txt true / false false Whether the fetches of link cards skip robots.txt. When false, the server obeys the robots.txt of the linked sites, so a site that disallows my-linkcard or * gets no card (link previews). /about/crawler tells linked sites which it is. When true, the server neither fetches nor uses robots.txt, and a linked site can no longer refuse these fetches with it; the server still names itself my-linkcard. Turn it on only when too many cards are missing. Cards built while it was on are checked at their next refetch after it is off. The directives of a page and the link card domains apply either way
ux_measurement true / false false Whether the web client sends samples of how fast it responds, and this server keeps them (UX measurements). The samples carry no account, address, or URL. When false, the server takes none, and ux_measurement in GET /api/v1/instance tells the client not to send them
ux_measurement_share integer 1-100 (percent) 10 The share of browser sessions whose web client sends samples while ux_measurement is true. Each session is drawn once, when the web client starts; a small server can measure every session with 100
oauth_metadata_document_clients true / false true Whether to accept Client ID Metadata Document clients. When true, for an authorization request whose client_id is an https URL, the server fetches the metadata at that URL and treats it as the client (no prior registration). The fetch follows no redirects, reads at most 5 KB, and reuses the response for at most 24 hours following its cache directives. When false, it stops fetching and refuses authorization requests, token exchanges, and refreshes of these clients
finance_visibility private / totals / breakdown private How much of the running costs (recorded on /admin/finance/costs, and set on /admin/finance/publication) to publish. private: nothing is published (GET /api/v1/instance/cost_totals is 404). totals: only the total per period and currency. breakdown: the totals and a breakdown by provider and category, shown to everyone on the information pages (/about and /about/costs) and in the API. breakdown reveals which provider (for example, which cloud) you run on. At every level, item names, memos, and individual payments stay private. Periods up to and including the one containing today (UTC) are published
finance_viewer_item_names true / false false Whether users with the permission view_finance see cost item names and the service names of imported costs on the finance screen (/finance, GET /api/v1/finance/cost_totals). Totals and the breakdown by provider and category are always shown, whatever this setting is
finance_viewer_item_memos true / false false Whether users with view_finance see the memos of cost items on the finance screen. If either the name or the memo setting is true, each period shows item rows (provider, category, and the amount of that period, plus the name and memo where enabled). People with manage_finance see everything regardless
finance_viewer_income totals / plans totals Whether users with view_finance see only the income totals (totals) or also the number of subscribers per plan (plans). The amount per plan and who paid are never shown. If income_visibility is plans, the published counts are shown whatever this value is. Income is read on the finance screen of the web client (/finance) and in GET /api/v1/finance/income_totals
income_visibility private / totals / plans private How much of the supporter income (the amount after the payment provider’s fees) to publish. It is chosen separately from finance_visibility. private: nothing is published (GET /api/v1/instance/income_totals is 404). totals: only the income total per period and currency. plans: also the current number of subscribers per plan, shown to everyone. For a plan with few subscribers, the count can let people guess who subscribes. The balance (income minus costs) is shown only when neither this value nor finance_visibility is private; otherwise the balance would reveal the side you hid. At every level, individual payments, subscribers, the amount per plan, and gross amounts and fees stay private. Periods up to and including the one containing today (UTC) are published
funding_meter_visibility off / percent / amounts off What the funding meter publishes: how far this month’s income (after the payment provider’s fees) goes toward the monthly target, shown on the about page, on the supporter list (/about/supporters), and in GET /api/v1/instance (funding_meter). It is set with the target on /admin/finance/publication, which offers only the choices the current visibilities allow and says why. off: nothing. percent: only the percentage, rounded down to 1%, whether the month is covered, and whether estimated costs are in the target. It can be chosen only while finance_visibility and income_visibility are both private. amounts: also the income and the target. It can be chosen only while neither is private. While only one of them is published, the meter cannot be shown: the published amounts and the percentage would reveal the hidden side. Changing either visibility so that the chosen value is no longer allowed turns the meter off, and that change is recorded and audited like any other. The month is the calendar month containing today (UTC), and only income in the target’s currency counts
funding_meter_target_amount decimal above zero, or empty empty The monthly target of the funding meter, in the main unit of funding_meter_target_currency (1650 yen, 12.50 dollars), with no more decimal digits than the currency has. Empty: the target is this month’s costs, which needs them in one currency; in a month whose costs are in several currencies, or are zero, the meter is not shown
funding_meter_target_currency ISO 4217 code, or empty empty The currency of funding_meter_target_amount, such as JPY. Empty: the currency of this month’s costs
funding_meter_rail true / false false Whether the web client also shows the funding meter in the right column of the wide layout, besides the about page, while funding_meter_visibility is not off
supporter_list_visibility off / signed_in / everyone off Who can see the list of supporters (GET /api/v1/instance/supporters and /about/supporters). off: nobody (the API answers 404 and /about has no link). signed_in: only people signed in to this server (the API answers 401 otherwise). everyone: everyone. The list shows only the accounts and plans of active subscribers who chose to be listed; amounts, monthly or yearly billing, dates, and counts are never shown. The list page and the API response are always noindex, noarchive, whatever search_indexing is
user_app_registration true / false true Whether signed-in users can register their own OAuth apps (public or confidential) with the client API (POST /api/v1/oauth_apps). When false, registering answers 403. Listing, changing, and deleting registered apps, reissuing secrets, issuing a token to yourself, and authorization by other users keep working
voice_room_starters everyone / permitted permitted Who can open voice chat rooms, while the configuration voice is not off (configuration). everyone: every signed-in local user who is not suspended or limited. permitted: only the holders of the permission start_voice_rooms, which only the built-in admin role has by default and which a role of a supporter plan may have
voice_public_summary true / false false Whether the page of a voice chat room whose visibility is local shows its name, description, host, and whether it is still open to visitors who are not signed in to this server and to remote users, and in its link preview. The participants are never shown. When false, those visitors see only that the room is for the local users of this server
event_creators everyone / permitted everyone Who can create events (events). everyone: every signed-in local user who is not suspended or limited. permitted: only the holders of the permission create_events, which only the built-in admin role has by default and which a role of a supporter plan may have
public_counts true / false true Whether the landing page (/, signed out) and GET /api/v1/instance/overview show how many members the server has, how many public posts its users made on each of the last 7 days, and when the server started. Only public posts of this server’s users count; the numbers are refreshed every few minutes. When false, the API leaves them out
landing_fediverse_explanation true / false true Whether the landing page (/, signed out) explains how the fediverse works: that an account here follows and is followed by people on other servers
landing_features true / false true Whether the landing page shows what the software does on this server, with a sample of each feature that is on (voice rooms, events, articles, search, translation, supporters)
featured_accounts usernames of up to 20 local accounts, separated by spaces or commas (empty = none) empty The accounts that the suggestions of people to follow show first, in this order, before the people of this server who posted recently. An account whose owner turned off “Suggest my account and find it by part of its name” is not suggested. See suggestions
login_providers_only true / false false Whether registration and sign-in are limited to the login providers while at least one is enabled: passwords and passkeys no longer sign in, and users without a linked provider cannot sign in again once their sessions end. With no enabled provider it does not apply. my instance set prints how many active users have no link to an enabled provider. See limit sign-in to login providers.
invite_creators everyone / permitted permitted Who can create invites of their own besides the staff with manage_invites (member invites). everyone: every signed-in local user who is not suspended or limited. permitted: only the holders of the permission create_invites, which only the built-in admin role has by default and which a role of a supporter plan may have. In approval mode, a usable invite approves the new user at once, so everyone lets every user skip the review
member_invite_max_active integer 0-100 5 How many usable invites (not revoked, expired, or used up) one member may hold at once; 0 lets members create none. Staff invites do not count
member_invite_max_uses integer 1-1000 10 How many people may sign up with one invite that a member creates
member_invite_max_lifetime_seconds integer 3600-31536000 (seconds) 2592000 (30 days) How long one invite that a member creates may work at most. Lowering it does not shorten existing invites
translation_providers comma-separated provider IDs empty The server-side translation providers that are enabled, the first tried first. When it is empty nothing is sent to any provider. An ID this server has no provider for does nothing. The built-in translation providers have the IDs libretranslate, deepl, google, and aws, and a translator plugin the ID plugin
translation_provider_visibilities comma-separated provider=visibility|visibility pairs empty What each provider may receive. A provider not named receives public, local, and unlisted posts; provider= with nothing after it receives none. private and direct go only to a provider named with them, so allowing one provider does not allow the next
translation_browser boolean false Whether readers may use the translation built into their browser, which sends nothing to this server or to a provider. With a server-side provider enabled too, the provider comes first, and the browser translates what the server refuses: a post or a language that no provider takes, a monthly limit, or a provider that fails
translation_user_monthly_characters integer 0-1000000000000 50000 How many characters one user’s requests may send to translation providers in a UTC month. At 0 nothing is sent. There is no unlimited value: set a large number
translation_server_monthly_characters integer 0-1000000000000 500000 How many characters the whole server may send to translation providers in a UTC month. At 0 nothing is sent. There is no unlimited value: set a large number
translation_retention_days integer 1-3650 (days) 30 How many days a translation is kept after it was made. Reading it does not extend this, and it goes with the post
translation_reports_to_server boolean false Whether moderators may send the text of a report, the reported posts and the reporter’s comment, to the server-side providers. Each provider still receives only the visibilities that translation_provider_visibilities allows it, whoever asks: a reported direct post goes only to a provider allowed direct, and the comment counts as private. The comment’s translation is never kept, nor is that of a deleted post, and the characters count against translation_server_monthly_characters only. When false, nothing of a report reaches a provider
event_records_retention_days integer 30-3650 (days) 90 How many days after an event ended or was cancelled to keep who answered it, who was approved, who was invited, who voted on its candidate dates, and the posts on its board. An event whose date was never fixed ends with its last candidate date. The event itself (its settings, places, date and candidate dates, and cancellation) is kept. The records of a reported event are kept as long as the report, and holds apply as to the other records (record retention)
voice_participants_retention_days integer 30-3650 (days) 90 How many days after a voice chat room ended to keep the records of who took part in it: the participations, the speakers and listeners, the raised hands, the invitations, and the removals. The room itself (its name, description, hosts, and how it ended) is kept. The records of a reported room are kept as long as the report, and holds apply as to the other records
hook_inbound_status_mode, hook_inbound_follow_mode, hook_signup_check_mode, hook_media_check_mode, hook_local_status_mode, hook_inbound_actor_mode, hook_local_profile_mode off, observe, enforce observe How far each decision hook acts while it has a plugin. off goes to enforce only through observe.
hook_inbound_status_on_failure, hook_inbound_follow_on_failure, hook_media_check_on_failure, hook_inbound_actor_on_failure pass, retry pass What the hook does when it enforces and its plugin fails (details).
hook_inbound_status_unfollowed_direct boolean false Whether inbound.status also sends the direct posts of authors no local account follows (details). The information page (/about) states it while the hook is in use.
hook_signup_check_on_failure pass, require_approval pass What signup.check does when it enforces and its plugin fails.
hook_signup_check_reject boolean false Whether a reject of signup.check refuses the sign-up while it enforces. When off, the answer is only recorded, as in observe.
hook_local_status_account_age_days integer 0-3650 (days) 7 local.status reviews the posts and their edits of accounts younger than this; 0 reviews every account. The information page (/about) states it while the hook is in use.
hook_local_profile_account_age_days integer 0-3650 (days) 7 local.profile reviews the profile changes of accounts younger than this; 0 reviews every account. The information page (/about) states it while the hook is in use.
hook_decisions_retention_days integer 30-3650 (days) 90 How many days to keep the decisions of the hooks.
single_user boolean false Whether the server is a one-person server. It can be turned on only while the server has exactly one local account, and turned off at any time
max_drafts integer 1-10000 100 How many drafts that are not scheduled one user may keep on the server. Lowering it deletes no draft: a user above it saves no new one
max_scheduled_posts integer 1-10000 300 How many scheduled posts of one user may wait. Lowering it cancels no schedule
max_scheduled_posts_per_day integer 1-10000 25 How many scheduled posts of one user may wait for one UTC day
scheduled_post_min_lead_minutes integer 1-1440 (minutes) 5 How many minutes ahead, at least, a post may be scheduled
scheduled_post_max_lead_days integer 1-3660 (days) 366 How many days ahead, at most, a post may be scheduled
article_authoring everyone / permission everyone Who may write new articles: every local user, or only the users whose roles have the permission create_articles
max_article_bytes integer 1000-100000 (bytes) 100000 The most bytes of the HTML that the body of an article makes
max_article_images integer 0-100 20 The most images of the author’s own uploads in the body of an article, besides its cover
  • Values are normalized before they are stored (TRUE becomes true, 0750 becomes 750, ja_jp becomes ja-JP, media IDs are lowercased). An invalid value is rejected and nothing is written.
  • preview_image and thumbnail accept only the media of an image that exists (including one still being processed). Until processing finishes, and in place of an image whose processing failed, preview_image falls back to the default image. Once a media has been set in any revision, the cleanup of unattached uploads does not delete it.
  • contact_account accepts only the username of a local user who is not deleted (stored in lowercase). contact_email accepts only an address of the form alice@example.com.
  • featured_accounts accepts only the usernames of local users who are not deleted; a leading @ is dropped, the names are lowercased, a repeated name is kept once, and they are stored separated by single spaces.

Signed-in users see suggestions of people to follow (on the empty home timeline after sign-up, and with GET /api/v1/accounts/suggestions). The suggestions are the accounts of featured_accounts in their order, then the accounts of this server that published a public or local post in the last 30 days, the one that posted last first. The user’s own account, the accounts the user follows, blocks, mutes, or is blocked by, and accounts that are suspended or deactivated are left out.

New accounts are suggested and can be found by part of their name in the account search. A user who turns off “Suggest my account and find it by part of its name” in the profile settings leaves both: the search then finds the account only by its whole username, or for the people who follow it.

Users can have their own posts deleted automatically some days after they publish them (Settings, “Delete old posts”). Each user’s policy is their own: whether it is on, after how many days, and which posts it keeps (pinned, bookmarked, and favourited posts, posts with media or a poll, articles, posts of chosen visibilities, and posts with at least some boosts or favourites). Deleting a post this way is the same as its author deleting it: the servers it went to receive a Delete. Only the posts of local accounts are deleted this way, never boosts.

The auto_delete_default_* keys are the policy that each new local account starts with, whichever way it is created (the sign-up form, an external login provider, an invite, or my admin). The account receives it when it is created and then owns it: changing the keys later changes neither the accounts that exist nor those that received an earlier value. The settings screen shows the values as the user’s own. With the keys unset, a new account starts with the automatic deletion off, after 30 days, keeping pinned, bookmarked, and favourited posts, articles, and direct posts. The default is not shown to people outside the instance. When a maximum is set, a new account receives the default cut to the maximum, as described below, so it starts within it.

With auto_delete_max_age_days above 0, no local post is kept longer than that many days after its publication. For every local account without the permission keep_posts_longer:

  • The automatic deletion is always on: a user cannot turn it off, and cannot choose more days than the maximum (fewer is fine). The settings screen and PUT /api/v1/preferences/auto_delete refuse both.
  • Only the exceptions that the auto_delete_max_allow_* keys allow keep posts. By default only pinned posts do, all of them; with auto_delete_max_kept_pins below 5, only that many of the most recent pins keep their posts.
  • Users who turned the automatic deletion off, or never set it, are held to the maximum too.

Turning the maximum on, lowering it, or changing the exceptions does not rewrite anyone’s settings. Instead, each hour the job content.auto_delete_statuses finds the accounts whose own settings keep posts that the maximum does not (because the maximum was turned on or lowered, or the account lost keep_posts_longer). It tells each of them once, with a notification and an email that are on by default, and from when the maximum applies: auto_delete_grace_days after the notice. Until then the account’s own settings stay in effect; from then on its posts go by the maximum. An account that comes within the maximum again (its user changes the settings, it gets keep_posts_longer, or the maximum goes or rises) is no longer held, and a later change tells it again with a new grace period.

Turning the maximum on tells every account that it holds within the hour. Deletions keep their pace: at most 100 posts of an account per hour, each sent to the servers the post went to as a Delete, so an account with many old posts takes hours or days to empty. A user who changes their settings in the meantime stops the rest.

keep_posts_longer is a member permission: give it to a role to let its holders keep their posts as long as they choose and turn the automatic deletion off. The built-in admin role has it. A supporter plan can carry it, so keeping posts longer can be a benefit of the plan; when the subscription ends, the maximum applies again after the grace period.

The maximum is public: GET /api/v1/instance returns it in auto_delete_limit, and the about page shows it, so people know it before they sign up. Changes of these keys need manage_settings and are recorded in the audit log like any other setting. In the web client they are on the “Post deletion” page of “Server settings”, which asks before it saves a maximum that is turned on or made stricter.

Users save drafts of posts on the server, go on writing them on another device, and publish them at once or at a chosen time. Only their author reads a draft; drafts are never federated, are not in the export of an account’s data, and go with the account when it is erased. The five max_drafts and scheduled_post_* settings above bound them; a save or a schedule past a limit is refused with a message that names it.

  • A scheduled post is published by the job content.publish_scheduled_draft at its time or soon after, also when the time is further ahead than the delay limit of the queue service: the job comes back and waits again. Set them with my instance set, for example my instance set max_scheduled_posts 100.
  • The post is checked when it is published, not only when it is scheduled: a user whom a moderation action bars from posting by then, or whose post replies to or quotes a post that is gone, gets no post. The draft stays, and the user gets a notification that says why (scheduled_status_failed, which users may turn off in their notification settings, and which is never emailed). The automated review of local posts, while it is in use, reviews the post when it is published.
  • A post is stamped with the time it is published, and the automatic deletion of old posts counts from then.
  • The media files a draft attaches are kept while the draft is; deleting the draft makes them unattached, and they go with the cleanup of unattached uploads. The cover of an article’s draft and the uploads its body shows are kept the same way.
  • Drafts and scheduled posts include articles, which are scheduled and counted like posts. An article’s draft may lack its title while its author writes; it is checked as a new article when it is published, and a user who may no longer write new articles by then gets no article.

An article is a long post with a title, a summary, and a cover image, whose body its author writes in Markdown. Articles are posts in every other way: they have a visibility, can be edited with their history kept, boosted, favourited, quoted, replied to, reported, and deleted, and moderation acts on them as on posts. The server renders the body once, when it is written: raw HTML in it is not rendered, and only the images of the author’s own uploads show as images; any other image becomes a link, so that readers never load images from other sites. Timelines, notifications, and search show the title, the summary, and the cover; the body shows where the article is opened.

  • By default every local user may write articles. With article_authoring set to permission, only the users whose roles have the permission create_articles may write new ones; the articles already written stay, and their authors may still edit them. A moderation action that bars an account from posting bars it from writing and editing articles too. A supporter plan may give create_articles as a benefit.
  • max_article_bytes bounds the HTML of a body, not the Markdown: the servers that receive articles count the HTML, and 100,000 bytes, the most it may be, is what they keep in full. A body in Japanese of about 30,000 characters fits. max_article_images bounds the images in a body. The editor shows both before the article is published.
  • An article is never a direct post, and has no poll, no attachments other than its images, and no content warning: a sensitive article shows its title and summary and folds the body and the cover.
  • The automatic deletion of old posts keeps articles unless the user turns that off (auto_delete_default_keep_articles for new accounts, auto_delete_max_allow_articles under a maximum).
  • GET /api/v1/instance returns the limits in limits.articles and the authoring setting in article_authoring. Set them with my instance set, for example my instance set article_authoring permission.

Local users plan events with a date, a time zone, and up to three places: a voice chat room of this server, a place to meet in person, and a link. Instead of a date, an organizer can offer up to 20 candidate dates: the users who see the event answer each one yes, maybe, or no, and the organizer or a co-organizer then confirms one, which fixes the date. Until then, nobody answers whether they will come. Events are for the users of this server only: they are never federated, and remote users and visitors who are not signed in see none of them.

  • Who may create one is event_creators. An organizer must also be able to open voice chat rooms (voice_room_starters and the configuration voice) to hold an event in one.
  • The voice chat room of an event opens at its start, hosted by the organizer, and waits up to 30 minutes for the first participant. It takes the event’s title, and the event’s visibility (every local user, followers, the people the organizer follows, mutual follows, or the invited). The co-organizers, those who answered going or maybe, and the invited who have not answered are invited to the room, so they keep seeing it when a co-host takes it over. The room makes no start post, and the start notification of the event is its only notification.
  • A room that cannot open (the voice chat is off, the organizer may no longer open rooms or is hosting another, or as many rooms are open as the configuration voice_max_open_rooms allows) leaves the event as it is: the organizer is notified, and the event page says that the room could not open. The server checks this when the date is set or changed and one day before the start too, and notifies the organizer of what would keep the room shut. The organizer is also notified when nobody came to the room. Cancelling the event, or removing its voice chat room, ends the room and keeps the event.
  • The organizer chooses who sees the event: every local user, the organizer’s followers, the people the organizer follows, mutual follows, or only the invited. The invited and those who answered it or its candidate dates always see it, and a block between a user and the organizer or a co-organizer hides it from that user.
  • The address and the link of an event are shown only to the attendees that the organizer or a co-organizer approved, unless the organizer shows them to everyone who sees the event. Links must be http or https, and the server never opens them.
  • A user who sees an event can save it as an iCalendar (.ics) file to add to their own calendar. The file names only the places that user sees, so an address kept for the approved attendees never appears in it. There is no calendar subscription address.
  • A user creates at most 10 events an hour, and an event sends at most 100 invitations an hour.
  • Users can report an event, and moderators can cancel one; suspending or deleting an organizer cancels the organizer’s events that have not started (moderation). Who answered and who was invited is kept for event_records_retention_days after the event, and so are the votes on its candidate dates and the posts on its board.
Key Limit Description
name 100 characters, one line (whitespace alone is not allowed) The instance name (display name). See name and domain
short_description 500 characters A short description
description 20000 characters The description
terms 100000 characters The terms of service (Markdown)
privacy_policy 100000 characters The privacy policy (Markdown)
commerce_disclosure 100000 characters The seller’s disclosure for paid plans, such as the notice that Japanese law requires (Markdown; supporters)
preview_image_alt 1500 characters The alt text of the preview_image image (og:image:alt). When unset, “Image of {instance name}” is used
thumbnail_alt 1500 characters The alt text of the thumbnail image
  • Each text has one value. An administrator writes it once in whatever language they like, and readers of every locale see the same value; readers of other languages rely on machine translation or the like. The labels and descriptions of the admin fields are translated into the viewer’s language like any other screen text; only the value an administrator writes is not.
  • The server does not know the language of a text, so the web client and the screens rendered by the server output texts with dir="auto" and lang="" (the HTML value for an unknown language) instead of inheriting the language of the screen.
  • Setting an empty text deletes it.
  • Besides the CLI, texts can be changed on the admin screens of the web client (name, short description, and description on the General page of “Server settings”, /admin/settings/general; the terms on /admin/documents/terms, the privacy policy on /admin/documents/privacy-policy, and the commerce disclosure on /admin/documents/commerce-disclosure, each a page of “Terms and policies”, /admin/documents) and with the client API (GET /api/v1/admin/instance_texts, PUT /api/v1/admin/instance_texts/{key}). Both need the role permission manage_settings, and changes are recorded in the audit log (text_changed).
  • Write terms, privacy_policy, and commerce_disclosure in Markdown (CommonMark plus the GitHub Flavored Markdown tables, strikethrough, and autolinks). A line break inside a paragraph stays a line break, and # headings start one level below the page title (h2).
  • The server converts them to HTML and sanitizes it (anonymous GET /api/v1/instance/documents/{kind}), and the web client pages /about/terms, /about/privacy, and /about/commerce show them. Raw HTML, images, and links other than http, https, and mailto are removed. The pages need no sign-in (they are web client pages, so they need JavaScript). /about/commerce is the URL to give to the payment provider.
  • A document you write is linked from the registration screen, the footer of every screen the server renders, and the web client (the third column, the menu, the settings, and the sign-in screen). A document that is not written is not linked, and its API answers 404.
  • While the terms of service or the privacy policy is written, the registration screen lists them before the create button with a required checkbox, “I have read and agree to the documents above”. The server refuses a registration without it, also one through a login provider. Without either document, the screen asks for no agreement.

An instance has a domain and a name, separately.

  • The domain is the configuration host (and account_domain, the domain of handles). It cannot be changed while the instance is running. Handles (@alice@example.com), URLs, ActivityPub IDs, and domain in GET /api/v1/instance stay the domain even when there is a name.
  • The name is the text name. It appears wherever the instance is named to people: the sidebar and “About this server” of the web client, the browser tab title, the sign-in, registration, email confirmation, account status, and authorization consent screens rendered by the server, emails (email address confirmation and moderator notifications), og:site_name of link previews, name / short_name of the Web App Manifest, metadata.nodeName of NodeInfo, and name in GET /api/v1/instance.
  • The name is the same in every locale. When there is no name, the domain (host) is shown instead.
  • A change takes effect from the next request, without a restart. The tab title and sidebar of an open web client update when you save on the admin screen.

The contact for the operators (contact_account, contact_email) and the image that represents the instance (thumbnail and the text thumbnail_alt) appear in the places below. Whatever is unset does not appear.

  • “About this server” of the web client (/about). The thumbnail and the contact account also appear on the first screen (/) for people who are not signed in.
  • contact (account and email) and thumbnail (url, width, height, alt) in GET /api/v1/instance.
  • metadata in NodeInfo: maintainer by the Misskey convention (name is the display name of the contact account, or its username when it has none; email is contact_email), staffAccounts by the Pleroma and Akkoma convention (the actor ID of the contact account), thumbnail (url and alt), and nodeDescription from the short description short_description.

When the contact account is suspended or deleted, the account is not shown and only the email address is. Change them on the General page of the admin screen of the web client (“Server settings”, /admin/settings/general), or with the CLI or the client API.

A server of its operator alone, the operator’s own home in the fediverse, is a one-person server: turn on single_user. In the web client, an administrator turns it on and off with One-person server on the Registration page of Server settings, which says why the server refused when it has more than one local account.

Terminal window
my instance set single_user true
my instance set single_user false # back to a community server
  • It can be turned on only while exactly one local account counts. Every local account that is not deleted counts, those pending approval, deactivated, scheduled for deletion, suspended, or limited included, since each could come back as a second person. An account whose registration was rejected does not count. With any other number, my instance set fails with the count, and the admin API answers 422 with the type /api/v1/problems/single-user-requires-one-account. The instance actor of the server is not an account and never counts.
  • It can be turned off at any time. Turning it on or off deletes nothing and changes the stored value of no other setting: what it holds back applies again as it was once it is off. Like every setting, the change goes to the audit log.

While it is on:

  • Registration is closed. registration_mode reads as closed whatever it stores, so the sign-up page, sign-up through a login provider, and my admin create create no account. Signing in with a login provider still works.
  • Only the home timeline. local_timeline_visibility and federated_timeline_visibility read as off. Hashtag and list timelines stay.
  • What a community needs is hidden. The local and federated timelines and their streams, the suggestions of accounts, the invites of users and of administrators, the review of registrations, and the sign-up blocks answer 404 with the type /api/v1/problems/single-user-mode.
  • No new local posts. On a server of one person, a post for “Neighbors” reaches nobody but the followers, so a new post cannot be local: the client API answers 422 and leaves it out of what an account may post. A default visibility of “Neighbors” reads as “Followers only” and cannot be saved, and a voice chat room for the people of this server announces itself in a post for the followers. Posts that are already local stay local.
  • The server says what it is. single_user in GET /api/v1/instance is true, with the effective registration mode and timelines and the operator’s account as single_user_account, and NodeInfo answers openRegistrations: false with metadata.singleUser: true.
  • The front page is the operator’s profile. People who are not signed in and open the server’s address see the profile of its one account, with the way to sign in and links to the about page, the terms of service, and the privacy policy that the server publishes. The web client hides what the server does not offer, from its navigation, menus, and administration screens: the local and federated timelines, signing up, suggested accounts, invites, the review of registrations, the sign-up blocks, the visibility “Neighbors”, and the settings of registration, invites, the public timelines, the landing page, and suggested accounts.

Federation, moderation, the full-text search, the supporter program, the documents, and the admin screens work as on any server.

Terminal window
my instance list # all settings (and whether each is the default) and texts
my instance get registration_mode
my instance set registration_mode open
my instance set name "Example Social" # the same name in every locale
my instance set description - < description.txt # the value "-" reads standard input
my instance get name
my instance set name "" # delete the name
my instance history registration_mode # revision history (newest first, -limit sets the count)
my instance history description
my instance set -owner admin preview_image ./preview.png # upload the image as media of admin and use it as the preview image
my instance set preview_image 0192f3a4-7b1c-7d2e-9f00-1a2b3c4d5e6f # give the ID of media that is already uploaded
my instance set preview_image_alt "A blue bird mascot"
my instance set preview_image "" # back to the bundled default image
my instance set contact_account admin # the contact account
my instance set contact_email admin@example.com
my instance set -owner admin thumbnail ./thumbnail.png # the thumbnail
my instance set thumbnail_alt "A town by the sea"
  • Write flags before the key and value.
  • With -owner <username>, the value of preview_image or thumbnail is read as the path of an image file and uploaded as media of that local account. The worker processes the image before it is used. A landscape image of 1200x630 is recommended.
  • A change records a revision (instance_*_revisions) and updates the current value (instance_settings / instance_texts) in one transaction. A change from the CLI is recorded without an actor (BY is cli in the history).
  • Setting the same value again still adds a revision.
  • Exit codes: 0 for success, 1 for a rejected value or a database error (nothing changes), 2 for wrong arguments.
  • Narrowing it keeps follow relationships, imported posts, and delivery records, and sends no Undo or Reject. The flow just stops, and returning to both (or another mode) resumes it as it was.
  • Posts and reactions made while narrowed are not delivered retroactively after you widen it again.
  • On the remote side, local users’ followers receive nothing while the mode is inbound, and local users’ follows are not updated while it is outbound or off.
  • Deletions (of posts or accounts) made while the mode is off are not sent out. In inbound and outbound, the retraction of what was already sent out (Delete and the like) goes to the original recipients and the followers at that time.
  • Changes are recorded in instance_setting_revisions and the audit log (target_kind = setting).

To cut the relationships too, use the CLI my admin federation sever.

Terminal window
my admin federation sever -direction in # end follows of local users by remote accounts
my admin federation sever -direction out # end follows of remote accounts by local users
my admin federation sever -direction both
  • It ends the pending and active follows between local and remote accounts as terminations by moderation (follow_terminations, reason = moderation). A change of mode never calls it automatically.
  • Reject (in) or Undo (out) is sent to the remote side only when the current mode sends that direction. In a mode that does not (such as off), the follow ends on the local side only and the remote side is not told.
  • It is safe to run repeatedly. It prints the number of follows it ended to standard output.

Every setting the CLI can change can also be changed on the admin screens of the web client and with the client API. Both need the role permission manage_settings (only the built-in admin role has it). As with the CLI, a change is kept as a revision and recorded per key in the audit log (setting_changed, the target is the setting and the actor is that user). Look at the audit log on the moderation screen (“Audit log”, /moderation/audit-log).

  • Web client (“Server settings”, /admin/settings): the screen lists one page per topic, in groups. Each page has one form and one save button, and saving sends only what you changed on that page; settings on the other pages stay as they are. A choice whose options each change much says what each one does under it, before you save, and a number says its bounds when it is refused.

    Page Sections and settings
    General (/admin/settings/general) Name and descriptions (name, short_description, description); Language (default_locale, chosen from the languages the app has); Contact (contact_account, contact_email); Images (thumbnail and the text thumbnail_alt, preview_image and the text preview_image_alt)
    Icon and logo (/admin/settings/branding) The icon, the logo, and the logo for dark backgrounds (Logo and icon)
    Registration (/admin/settings/registration) Who can sign up (registration_mode, each mode with what it does); One-person server (single_user); Member invites (invite_creators, member_invite_max_active, member_invite_max_uses, member_invite_max_lifetime_seconds in hours); Login providers only (login_providers_only, which asks first, with how many active users could no longer sign in and whether you are one of them); Apps (user_app_registration, dynamic_client_registration, oauth_metadata_document_clients, oauth_client_rate_limits). On a one-person server, the sections of signing up and of member invites say that nobody else signs up
    Posts and features (/admin/settings/content) Posts (max_status_length, require_media_description); Timelines (local_timeline_visibility, federated_timeline_visibility); Link cards (link_cards, link_cards_ignore_robots_txt); Drafts and scheduled posts (max_drafts, max_scheduled_posts, max_scheduled_posts_per_day, scheduled_post_min_lead_minutes, scheduled_post_max_lead_days); Articles (article_authoring, max_article_bytes, max_article_images); Events (event_creators, event_records_retention_days); Front page and suggestions (public_counts, landing_fediverse_explanation, landing_features, featured_accounts)
    Voice chat (/admin/settings/voice) Who can open rooms (voice_room_starters); Rooms (voice_public_summary, voice_participants_retention_days)
    Post deletion (/admin/settings/auto-delete) Default for new accounts (the auto_delete_default_* settings); Maximum for everyone (auto_delete_max_age_days, auto_delete_grace_days, the auto_delete_max_allow_* settings, auto_delete_max_kept_pins). Saving a maximum that is turned on or made shorter asks first (A maximum for keeping posts)
    Federation (/admin/settings/federation) Direction (federation_mode); Servers (federation_scope: saving allowlist first shows the follows the switch would end and asks, see federating only with allowed servers); Signed fetches (authorized_fetch); Media from other servers (remote_media_policy, remote_media_cache_ttl_seconds in minutes, remote_media_cache_max_bytes in MiB); Posts from other servers (remote_status_retention_days, remote_status_max_retention_days, relay_status_retention_days); Moderated servers (domain_actions_visibility, domain_actions_rationale_visibility)
    Search and crawlers (/admin/settings/discovery) Search engines (search_indexing, indexable_default); Security contact (security_contact); AI (ai_usage); Full-text search (search_visibilities)
    External review (/admin/settings/hooks) A section for each decision hook: its mode (enforce is offered only once it is not off), what it does when its plugin fails, and its other settings; Records of decisions (hook_decisions_retention_days). See Decision hooks
    Appeals and records (/admin/settings/records) Appeals (appeal_window_days); Keeping records (session_origins_retention_days, registration_origins_retention_days, reports_retention_days, moderation_actions_retention_days, audit_log_retention_days)

    On the General page, an image is uploaded when you save, and becomes the thumbnail or the link preview image then. Who may see the running costs, the income, and the supporter list is set on the “Costs and income” and “Supporters” screens. The settings of translation have a screen of their own, below.

  • Web client (“Translation”, /admin/translation): the providers this server has, their order and what each may receive, the browser’s translation, the monthly limits, and how long translations are kept, with the characters sent this month and the cache hit rate. Each server process adds its count of cache hits to the rate at most once a minute, so the latest requests can take a minute to show, and a process that stops can leave its last minute uncounted. Update your privacy policy (template) before you enable a server-side provider: text sent to a provider cannot be recalled. API keys of providers and the address of a translator plugin live in the deployment configuration; no setting and no answer of the client API holds them.

  • Translation limits. What counts is the characters sent, in code points: the markers that stand in for mentions, links, and the like do not count, and neither do a translation the server already keeps, a post already in the reader’s language, or the browser’s translation. Each call to a provider counts, also one that fails, since the provider may have received the text, so the number can differ from what a provider bills. Over a limit the request is refused with a 429 and no provider is called; the web client then uses the reader’s browser translation, when you allow it and the browser can translate the post. Months are in UTC.

  • Client API: GET /api/v1/admin/settings returns every setting with its current value, its default, whether it is set, and its type and accepted values (choices or range). PATCH /api/v1/admin/settings changes settings together with {"values": {"<key>": "<value>", ...}}. All values are strings, normalized and stored as with the CLI. If a single key is unknown or a value is invalid, the answer is a 422 that names the key and nothing changes. The changed keys are recorded as revisions and in the audit log in the same transaction.

  • Invitations, which work in the open, approval, and invite modes, are created on the moderation screen (“Invites”, /moderation/invites, permission manage_invites; see invite codes), and by members as invite_creators allows (member invites).

The rules of the instance appear in rules of GET /api/v1/instance, and reports cite them by ID.

  • A rule has a one-line sentence (up to 300 characters) and an optional supplement (up to 1,000 characters). As with texts, the administrator writes them in whatever language they like and every locale sees the same value (dir="auto" and lang=""). There can be at most 100 active rules.
  • Every change (a revised sentence, a reordering) is kept as a revision (instance_rule_revisions), and the ID of a rule does not change.
  • A retired rule disappears from the list of active rules. It cannot be brought back, but reports can still refer to it.
Terminal window
my instance rule create -hint "No harassment" "Be kind" # add at the end of the active rules
my instance rule edit <rule> "Always be kind" # change the sentence; the supplement changes only with -hint
my instance rule move <rule> 1 # move to position 1 and renumber the active rules 1, 2, ...
my instance rule retire <rule> # retire it
my instance rule list # active rules (-all includes retired ones)
  • The admin API is /api/v1/admin/rules (list, add, get, revise, move, retire) and needs the role permission manage_rules.
  • On the admin screen of the web client (“Rules”, /admin/rules, manage_rules), the list shows the rules in effect in order, and “Move up” and “Move down” reorder them; the filter above the list shows the retired rules instead. “Add a rule” opens a page with a sentence and a supplement. Choose a rule’s sentence to open its page, where you edit it and retire it (after a confirmation dialog). Every change is recorded in the audit log (rule_added, rule_revised, rule_moved, rule_retired).
  • The exit codes are the same as for settings (0 for success, 1 for a rejected value or a database error, 2 for wrong arguments).

The link cards of posts (link_cards) come from a crawler: the server fetches the linked page and its image. A rule stops that crawler on one domain and its subdomains, and leaves everything else about the domain alone. It has one of two modes. A rule is the operator’s choice, and it applies besides what the linked sites themselves refuse (link previews).

Mode What it fetches Cards it already has
Stop fetching (no_fetch) Nothing from the domain, neither pages nor images, also when a redirect leads there Hidden
Stop images only (no_images) Pages, but no images from the domain Shown without their image
  • A rule bears only on link cards. The domain stays federated, and the media of its posts are fetched as usual: to cut a server off, use a domain action, which also stops its link cards. A rule is not listed with the domain actions or exported with them.
  • A rule covers the domain and its subdomains, and an image is checked against the hosts of the page and of the image. Every rule that covers a host applies, so a rule on a subdomain does not loosen the rule on its parent. A domain is written and normalized as for a domain action: a host name without a scheme or a port, in any spelling of an internationalized domain.
  • A change takes effect at once, also on the cards the server already has, and the proxied images of those cards stop being served while images are stopped.
  • Removing a rule brings the cards the server already has back as they were. A link that was skipped gets its card the next time a post needs it; nothing is fetched again in bulk. A card fetched again while images were stopped stays without an image until its next refetch.
  • On the admin screen of the web client (“Link card domains”, /admin/link-card-domains, manage_settings), “Add a rule” sets a rule with its mode and a note, and refuses a domain that has a rule already, with a link to that rule. The list shows the rules by domain, 40 at a time with “Show more”; choosing a domain opens its rule’s page, where you change its mode and note, and remove it (after a confirmation dialog).
  • The admin API is /api/v1/admin/link_card_domains (list, set; a DELETE with the domain removes it) and needs the role permission manage_settings. A server keeps at most 1,000 rules, each with a note of up to 5,000 characters.
  • Every change is recorded in the audit log (link_card_domain_fetch_stopped, link_card_domain_images_stopped, link_card_domain_rule_removed).

The server-wide theme is one set of overrides of the web client’s design tokens, with a light and a dark value for each color. It applies to the web client of every viewer and to the screens the server renders (sign-in, registration, terms, and so on). There is no custom CSS.

  • You can override these design tokens; the spacing, the sizes of the components, the weights of the type, the shadows, and the colors of the data charts stay fixed:

    Tokens Kind Override
    color-surface, color-surface-raised, color-surface-raised-hover, color-surface-raised-pressed, color-surface-hover, color-surface-pressed, color-text, color-muted-text, color-accent, color-on-accent, color-accent-text, color-quote-bar color #rrggbb for light and for dark
    font-sans-override, font-mono-override font family Family names, comma-separated (at most 30), with no generic family such as sans-serif; quote a name with a word that starts with a digit, such as "M PLUS 1p"
    text-tagline, text-headline, text-heading, text-title, text-reading, text-body, text-caption length 0 or rem / px, 0.625rem to 3rem
    text-*--line-height of the same seven number 1 to 2.5
    radius-control, radius-overlay length 0 to 2rem
    duration-spin duration ms / s, 0 to 1000ms
  • The web client draws text with its own fonts: Noto Color Emoji for emoji, Noto Sans for Latin, Greek and Cyrillic, and Noto Sans CJK in the glyphs of the text’s language for the rest. The fonts of font-sans-override (text) and font-mono-override (code) come right after the emoji font, and the web client’s fonts draw the characters yours lack. A theme cannot replace these fonts.

  • You save a set as a draft, preview it, and then publish it; the theme in effect does not change until you publish. Each save replaces the whole draft, and each publication is a new revision. Restoring publishes again the set that was in effect before the current one, and leaves the draft as it is.

  • In the web client, Administration > Theme shows the draft and the theme in effect. Edit the draft shows each color for light and dark with the contrast of every pair it makes, and does not save a pair below its minimum. Preview shows the draft on every screen of your browser tab until you press it again; nobody else sees it. Publish and Restore the previous theme are on the same screen. The icon and the logo are on Server settings > Icon and logo.

  • When you save and when you publish, the server checks the shape and range of the values and the contrast of every pair of color tokens (tokens you do not override use their defaults; WCAG 2.2 AA in both light and dark). If any check fails, nothing is saved or published.

  • An override of a token that a new version renames or retires, or whose value no longer fits the token, never fails an upgrade. It stays in the saved set but no longer applies: the admin API lists it under stale_tokens, my instance theme get names it, and the next save of the draft drops it.

  • The stylesheet of the published revision is served at /theme/{revision ID}.css (immutable, cached for a long time). The HTML shell has a shared cache (60 seconds plus 300 seconds of revalidation), so it takes a few minutes after you publish for everyone to get it. A page that is already open keeps the old look until it is reloaded.

  • <meta name="theme-color"> (light and dark) in the shell and theme_color / background_color (light) of the Web App Manifest take the value of the theme’s color-surface. The HTML version of every email the server sends from then on uses the published theme’s colors, light and dark; a draft never reaches email.

  • Publishing a set with no tokens resets the theme to the default, and the stylesheet is no longer loaded.

  • You can change it with the client API and with the CLI. The client API needs the role permission manage_settings: GET /api/v1/admin/theme reads the draft and the set in effect, PUT /api/v1/admin/theme/draft saves the draft, GET /api/v1/admin/theme/draft/stylesheet returns the draft’s stylesheet to preview, and POST /api/v1/admin/theme/publish and POST /api/v1/admin/theme/restore publish. Publications are recorded in the audit log (setting_changed, target theme).

Terminal window
my instance theme get > theme.json # print the draft as the same JSON as the admin API (-published: the set in effect)
my instance theme set < theme.json # save the whole draft (if a check fails, it prints why and changes nothing)
my instance theme publish # publish the draft
my instance theme restore # publish again the set in effect before the current one
echo '{"tokens":[]}' | my instance theme set && my instance theme publish # back to the default
{
"tokens": [
{ "token": "color-accent", "light": "#ff8a80", "dark": "#ff8a80" },
{ "token": "radius-control", "value": "0.25rem" }
]
}

Besides the thumbnail and the preview image, the instance can have its own icon, logo, and dark logo, each uploaded as one SVG. Until one is set, the built-in mycroblog images are used, and clearing one brings the built-in image back.

Image Shape Where it appears
icon Square (within 1%) The favicon, the home screen icon of iOS (apple-touch-icon), the icons of the installed app (Web App Manifest), the server’s card on the landing page and beside its name in the web client’s side panel, and wherever a client shows the server as a square picture
logo 1 to 8 times as wide as it is high The header of the web client and the top of the sign-in, registration, and consent pages instead of the built-in wordmark and the server name (the logo should contain the name, which is its alt text), the HTML version of every email, and the link preview image when preview_image is not set
logo_dark As logo Dark backgrounds; without it, logo is used there too
  • The server sanitizes the SVG. It reads it as XML and writes a new document from the allowed elements (shapes, groups, defs, symbol, use, gradients, clipPath, mask, pattern, style, title, desc) and attributes (geometry, transforms, presentation attributes, id, class, style) only. Scripts, foreignObject, embedded images, links, animations, filters (shadows and blurs), event handlers, references to anything outside the file, and data: URLs are removed, and the answer lists what was removed. Only the sanitized SVG is stored.
  • An SVG is refused (nothing is saved) when it is not well-formed XML in UTF-8, has a DOCTYPE or entity declarations, has no viewBox, is over 256 KiB (128 KiB after sanitizing), has over 5,000 elements, nests over 32 deep, has over 200 use elements, has the wrong shape for its kind, contains text (convert text to outlines in your editor first), or has CSS that could load something (@import, @font-face, url() other than url(#id), escapes). @media (prefers-color-scheme: dark) in a <style> is allowed, so an icon can change in dark mode.
  • Some places take no SVG (the iOS home screen, older Safari favicons, link previews, email). For them the client that uploads the SVG also draws PNG versions from the sanitized SVG and sends them with it: 32, 48, 180, 192, and 512 px and a 512 px maskable icon for icon; a 96 px high email logo and a 1200 × 630 link preview image for logo; a 96 px high email logo for logo_dark. The server checks that each is a PNG of the right size (at most 1 MiB; the 180 px icon, the maskable icon, and the link preview must be opaque) and writes it again without metadata. If any file is wrong, nothing is saved. The icon’s opaque versions are drawn on a background color, #rrggbb, which defaults to the theme’s light color-surface. The server does not check that the PNG versions show the same picture as the SVG.
  • The files are stored in the blob store under instance/brand/<revision>/ and served at https://<host>/brand/<revision>/<version>.svg|.png with Cache-Control: public, max-age=31536000, immutable, since the content of a revision never changes. An SVG is served with Content-Security-Policy: default-src 'none'; style-src 'unsafe-inline'; sandbox and X-Content-Type-Options: nosniff, so even opened on its own it runs nothing and loads nothing. The files of earlier revisions stay, so emails already sent keep their logo.
  • With an icon set, the HTML shell links its PNG favicons, its SVG, and its 180 px apple-touch-icon, the Web App Manifest lists its 512 px, 192 px, maskable, and SVG icons in that order (other fediverse servers take the first one as this server’s icon), and /apple-touch-icon.png returns the 180 px version. The shell’s ETag changes with the images, and the shell’s shared cache lasts a few minutes as with the theme. An installed app picks up a new icon on Android when Chrome next checks the manifest; on desktops the app keeps its old icon until it is installed again.
  • GET /api/v1/instance returns icon, logo, and logo_dark with the URL of the SVG, the URL and size of each PNG version, and the revision; each is left out while the built-in image is in use.
  • Set them in the web client under Server settings > Icon and logo (/admin/settings/branding, role permission manage_settings). Choose an SVG file for the icon, the logo, or the logo for dark backgrounds: the server checks it at once, and the form shows it as the server would keep it, with the list of what the server removed. If the server refuses the file, the reason shows under it with how to fix it. For the icon, set the background color of its opaque versions there too. Save draws the PNG versions in the browser and sends each image chosen with them; Use the built-in image brings an image back to the built-in one when you save. The web client keeps the images it has shown for offline use.
  • The client API does the same, with the role permission manage_settings: POST /api/v1/admin/instance/brand/sanitize checks an SVG and returns the sanitized SVG with the PNG versions to draw (it saves nothing), PUT /api/v1/admin/instance/brand/{icon|logo|logo_dark} saves the SVG with every PNG version (multipart/form-data, one part per version), DELETE on the same path clears one, and GET /api/v1/admin/instance/brand returns the current images with the icon’s background color. Every change is kept as a revision (instance_brand_revisions) and recorded in the audit log (setting_changed, target brand_icon, brand_logo, or brand_logo_dark).
  • The CLI cannot set them, since the PNG versions are drawn by the client, but it can show them and clear a broken one:
Terminal window
my instance brand show # each image with its revision, when and by whom it was set, and the URL of its SVG
my instance brand clear icon # back to the built-in icon (also logo, logo_dark)

Local custom emoji are shown as images when someone writes :shortcode: in the body or content warning of a post, or in the display name, bio, or profile fields. They also reach Mastodon, Misskey, GoToSocial, and Akkoma through the Emoji tag of the Notes and actors you send.

  • A shortcode is 2-30 letters, digits, or _. It is case-sensitive and cannot be changed after the emoji is registered. Aliases (up to 10) and a category (up to 64 characters) are used for searching and grouping in the emoji picker.
  • The image is PNG, GIF, or WebP, at most custom_emoji_max_bytes (default 256 KiB) and at most 1,024 px on each side. The server makes derivatives that fit boxes of 64, 128, and 256 px and does not keep the original. An APNG becomes a still image of its first frame. GoToSocial by default does not fetch emoji larger than 100 KiB, so small images are recommended.
  • A disabled emoji appears nowhere (posts, profiles, federation, the picker), and :shortcode: is shown as text again. An emoji set to be hidden from the picker is only missing from the picker and can still be used by writing it. An emoji that came from another server can only be disabled or copied as an emoji of this server.
  • Copying fetches the image of another server’s emoji under the same limits as the media proxy (images from domains with reject_media are not fetched), runs the same checks as above, and registers it as a new local emoji. The shortcode is the original’s or the one you give. The image shrinks to the 256 px box, and an image that cannot be fetched or fails the checks leaves nothing behind.
  • Deletion cannot be undone. Emoji in past posts turn back into text too, and registering the same shortcode again makes a different emoji. Images that federated servers copied cannot be deleted.
  • The admin screen (“Custom emoji”, /admin/custom-emojis), the client API (/api/v1/admin/custom_emojis), and the CLI do the same things. On the screen, “Register an emoji” opens the registration form (/admin/custom-emojis/new), which warns about an image over 100 KiB, and choosing an emoji in the list opens its page (/admin/custom-emojis/{id}), where you enable or disable it, replace its image, change its category, aliases and picker visibility, delete it after typing its shortcode, or copy one of another server. The admin screen and the client API need the role permission manage_custom_emojis (only the built-in admin has it). Registering, copying, replacing the image, changing settings and aliases, enabling and disabling, and deleting are recorded in the audit log (target custom_emoji) whichever way they are done (an operation from the CLI is recorded as a CLI operation).
Terminal window
my admin emoji create -shortcode blobcat -category Cats -alias neko blobcat.png # register one
my admin emoji list -local # list local emoji, newest first
my admin emoji update -category Animals -alias cat -alias neko <emoji id> # change the category and aliases (aliases are replaced; -no-aliases removes them)
my admin emoji update -hidden <emoji id> # hide it from the picker (-hidden=false restores it)
my admin emoji replace-image <emoji id> blobcat2.png # replace the image
my admin emoji disable <emoji id> # disable it (remote emoji too)
my admin emoji enable <emoji id> # enable it again
my admin emoji list -remote -domain mastodon.example # list emoji of another server
my admin emoji copy [-shortcode <name>] <emoji id> # copy a remote emoji to local
my admin emoji delete <emoji id> # delete it
my admin emoji requests list [-state pending|approved|rejected|withdrawn|lapsed|all] # list creation requests (pending by default)
my admin emoji requests approve <request id> # approve a request
my admin emoji requests reject [-reason <text>] <request id> # reject a request (the requester sees the reason)
  • A user with the role permission create_custom_emojis (a user feature) can request the creation of an emoji from “Custom emoji” in the settings (/settings/custom-emojis), change the aliases, category, and picker visibility of emoji they created, and delete them; the page shows how many requests they have left this month. Replacing an image is also a request, made with the client API (POST /api/v1/custom_emoji_requests, kind image); the settings page does not offer it. A request appears nowhere (picker, posts, reactions, federation) until someone with manage_custom_emojis approves it. Approve or reject it on the “Requests” page of “Custom emoji” on the admin screen (/admin/custom-emojis/requests), with the client API (/api/v1/admin/custom_emoji_requests), or with the CLI above. People with manage_custom_emojis are notified of a request (admin_custom_emoji_request), and the requester is notified of the approval or rejection. Requesting, withdrawing, approving, and rejecting are recorded in the audit log (target custom_emoji_request).
  • A pending creation request reserves its shortcode. A request or a registration with the same shortcode is not possible until the pending one is rejected or withdrawn. The image of an approved emoji is copied as an upload of the instance actor, so it stays even if the requester’s account is deleted.
  • A creator can change their emoji only while they hold create_custom_emojis. The emoji stay if the role is removed. Administrators can change and delete every emoji regardless of the creator.
  • When the role comes from a supporter plan, the number of emoji a user can create each month is limited by the plan’s monthly emoji limit. It counts the creation requests the user submitted in the current calendar month (UTC) that are approved or pending; rejected and withdrawn requests do not count, and deleting an emoji does not free a place. A request counts in the month it was submitted, even if it is approved in the next one. The count resets at 00:00 UTC on the first day of each month, and the settings page shows the user when, in their own time zone. Replacing the image of an emoji, and emoji that administrators register, do not count. A role an administrator assigned by hand, and a server where supporters are disabled, have no limit.

For LLMs and coding agents:this page as Markdown, llms.txt,llms-full.txt, llms-small.txt

Analytics on this site