Settings → System → Advanced Settings

Use Advanced Settings to configure application-wide behavior. Search by the exact key shown below, edit its value, then save that row. Settings are predefined; you can change or reset them, but cannot add or remove them.

This reference covers every setting in the tab. Tables show shipped defaults, not necessarily your current values: guided setup and administrators may have changed them. Empty means no value is configured; Generated automatically means MisterShell supplies the value. Limits use the units described in each row. Secret values are masked.

Find the right settings

• Deployment identity and HTTPS
• Email delivery
• Accounts, passwords, and sign-in
• External identity providers
• Login lifetime and API protection
• Interactive session capacity
• Native SSH access
• Sharing sessions and transferring files
• Resource checks and collection
• Workers and background tasks
• AI usage
• Notes editing
• Syslog collection and intrusion detection
• History and retention
• Database backup destination
• Performance and monitoring
• Logging and troubleshooting
• Maps
• Setup and automatically managed values

Change or reset a value

1. Open Settings → System → Advanced Settings and search for the key or a prefix, such as smtp_ or sshgw_.
2. Edit Value. Correct any validation error before saving; the accepted ranges and choices are listed below.
3. Click the row’s green Save icon. Each row is saved independently.
4. To restore the shipped default, click Reset to Default and confirm. Resetting a secret or identity key can affect access; read its guidance first.

For secrets, leaving the input untouched keeps the current value; entering a new value replaces it. Local MFA must be changed through Auth Providers, even though its setting appears here.

Most settings are picked up at runtime, but application caches and component update intervals can delay the effect. Follow any explicit restart or new-session requirement below. Infrastructure connection strings and other environment variables belong in your deployment configuration; see Deployment.

Deployment identity and HTTPS

Start here when making MisterShell available to users. The public address must match the URL people browse to. For installation and reverse-proxy examples, see Deployment.

Setting	Default	Allowed values	What it controls
app_base_url	http://localhost:9000	1–500 characters	Public web URL used in password-reset, verification, report, and sign-in links. Set your real HTTPS address before enabling OpenID Connect or SAML.
licensing_email	Empty	0–320 characters	Email address used to purchase this installation’s licenses. It must match the license. Empty leaves paid licenses inactive; the Free edition remains available.
enable_x_forwarded_for_header	false	true / false	Use the client address supplied by another reverse proxy in front of MisterShell. Enable only when that proxy overwrites the forwarded-address header; the built-in proxy already reports the real client address.
nginx_tls_certificate_pem	Empty	PEM text	Web-server certificate in PEM format. Configure with its matching private key. Empty does not install a custom certificate; resetting does not automatically replace the currently served certificate.
nginx_tls_private_key_pem	Empty	PEM text	Secret. Matching PEM private key for the web certificate. Coordinate certificate changes with any load balancer that terminates HTTPS.

Certificate handling depends on the deployment topology. Follow the TLS guidance before replacing a certificate.

Email delivery

Configure and test email before relying on email verification, password recovery, email MFA, or notifications. The global switch applies to outgoing application mail. See Auth Providers for the email-MFA activation test.

Setting	Default	Allowed values	What it controls
enable_email_notifications	false	true / false	Enable outgoing application email. Configure the SMTP connection before turning this on.
smtp_host	localhost	1–255 characters	SMTP server hostname.
smtp_port	587	1–65,535	SMTP server port. MisterShell upgrades a plain SMTP connection with STARTTLS when TLS is enabled; this is not implicit TLS on connection.
smtp_username	Empty	0–255 characters	SMTP authentication username. Leave empty only if the mail server allows sending without authentication.
smtp_password	Empty	0–255 characters	Secret. SMTP authentication password; used together with the username.
smtp_from_email	noreply@example.com	3–255 characters	Sender address shown on MisterShell emails. Use an address your mail server permits.
smtp_use_tls	true	true / false	Request STARTTLS encryption for the SMTP connection.
smtp_tls_verify	false	true / false	Validate the mail server’s TLS certificate against system and configured CA certificates. Enable for a trusted mail endpoint; add a private CA under CA Certificates if needed.

Accounts, passwords, and sign-in

MisterShell login names are email addresses. Local password rules apply when users set or change a local password. External providers manage their own credentials. Set MFA through Users & Roles → Auth Providers, where the activation and verification steps are available.

Setting	Default	Allowed values	What it controls
enable_self_registration	false	true / false	Allow people to create their own local accounts. Keep off when administrators provision accounts.
require_email_verification	false	true / false	Require local accounts to verify their email before activation. Working email delivery is required.
email_verification_token_expire_hours	24	1–168	How long an email-verification link remains usable, in hours.
local_mfa	None	Manage in Auth Providers	Managed through Auth Providers. Choose None, Email, or Authenticator app there. Direct editing and resetting on Advanced Settings are refused.
password_min_length	8	4–128	Minimum local password length.
password_min_uppercase	0	0–10	Minimum uppercase letters in a local password.
password_min_lowercase	0	0–10	Minimum lowercase letters in a local password.
password_min_digit	0	0–10	Minimum digits in a local password.
password_min_special	0	0–10	Minimum special characters in a local password.
max_failed_login_attempts	5	1–100	Failed sign-in attempts allowed before the account is temporarily locked.
lockout_duration_minutes	15	1–1,440	Duration of a temporary account lockout, in minutes.
password_reset_token_expire_minutes	30	5–1,440	How long a password-reset link remains usable, in minutes.

Password complexity counts are minimums; choose a total length that can accommodate them. A value of 0 removes that character-count requirement.

External identity providers

These settings apply to LDAP, OpenID Connect, and SAML sign-ins. Configure provider connections and group-to-role mappings under Auth Providers.

Setting	Default	Allowed values	What it controls
external_auth_auto_provision	true	true / false	Create a MisterShell account on the first successful external sign-in. Turn off when accounts must be prepared in advance.
external_auth_sync_attributes	true	true / false	Refresh account name and email from the external provider during sign-in.
external_auth_override_roles	true	true / false	When enabled, mapped external roles replace local assignments; sign-in is refused if no group maps to a role. When disabled, mapped roles are added while existing assignments are preserved.
oidc_state_timeout_minutes	10	1–60	Time allowed to complete an OpenID Connect or SAML sign-in round trip, in minutes.

Login lifetime and API protection

Login lifetime controls how long a user stays signed in. It is separate from the idle timeout of a connection to a resource. API limits protect the service from excessive request rates.

Setting	Default	Allowed values	What it controls
auth_session_max_duration_minutes	720	0–2,147,483,647 minutes	Absolute human sign-in lifetime. 0 disables this limit. Takes effect at the next full sign-in; activity and refresh never restart it.
jwt_access_token_expire_minutes	30	5–1,440	Lifetime of a short-lived sign-in token, in minutes. Changing this affects newly issued tokens.
jwt_refresh_token_expire_days	7	1–30	Lifetime of the credential used to renew a sign-in, in days. Changing this affects newly issued credentials.
jwt_secret_key	Generated automatically	At least 32 characters	Secret. Automatically generated at initial setup. Changing it invalidates existing login tokens. Do not use Reset to rotate it: Reset clears the key instead of generating a replacement. Plan any replacement as an authentication change.
jwt_algorithm	HS256	HS256, HS384, HS512	Login-token signing algorithm. Leave at its default unless planning a coordinated authentication change; changing it invalidates tokens using the previous algorithm.
rate_limiting_enabled	true	true / false	Enable API request-rate protection. Keep enabled for normal operation.
api_rate_limit_per_minute	600	10–10,000	Authenticated API requests allowed per user per minute. Includes requests made by the web UI.
public_api_rate_limit_per_minute	120	1–1,000	Unauthenticated API requests allowed per source IP address per minute. Consider shared office addresses when choosing this value.

Five minutes before the sign-in deadline, MisterShell shows a warning. After Got it, a seconds countdown appears in the top navigation, orange below two minutes and red below one minute. Finish and save your work, then sign in again and reconnect at expiry. This does not introduce an inactivity logout. Unlimited still respects ordinary token expiration and revocation.

Interactive session capacity

These limits apply when users connect to resources. Browser and native SSH shells share the same per-user/resource quota. A worker’s session limit covers all users and connection types assigned to it.

Setting	Default	Allowed values	What it controls
max_shell_sessions_per_resource	3	1–20	Maximum live shells for one user on one resource, shared across shell modes and browser/native SSH clients.
worker_max_concurrent_sessions	3	1–20	Total sessions on each worker across SSH, cloud, Kubernetes, database, RDP, VNC, Web, and Files.
session_inactivity_timeout_minutes	15	1–240	Close a resource session after this many minutes without user activity.
enable_session_resume	true	true / false	Preserve browser sessions after an accidental disconnect, within their timeout. Applies to shell, graphical, and file sessions. Reopen an existing connection pin to reattach; changing the setting is picked up when session configuration is loaded.

Graphical sessions have a fixed limit of one per user/resource. File browsing does not consume the shell quota. Reducing a capacity limit leaves existing sessions running and restricts new connections until capacity is available; sessions awaiting reconnection or still closing continue to count.

Explicitly choosing Disconnect or confirming closure of a connection pin ends that session even when resume is enabled. Native SSH connections end their sessions when disconnected.

Native SSH access

These settings govern the SSH gateway and Text UI. Users sign in with their MisterShell account email address. Expose the configured port on the host or load balancer using the same port number.

Setting	Default	Allowed values	What it controls
sshgw_enabled	true	true / false	Accept native SSH and SFTP connections.
sshgw_port	2222	1–65,535	SSH listening and client connection port. A change restarts the listener within about 30 seconds; update the host mapping and client settings together.
sshgw_max_connections	200	1–10,000	Maximum concurrent SSH connections per Core. Each Core enforces its own limit.
sshgw_unauth_connections_per_ip	5	1–1,000	Concurrent connections still signing in from one source IP address.
sshgw_auth_attempts_per_ip_per_10min	20	1–10,000	Sign-in attempts allowed from one source IP address in ten minutes.
sshgw_max_tabs	8	1–32	Maximum open session tabs in one Text UI connection, across all resources. Applies to newly opened Text UI connections after the setting is picked up, within about 30 seconds.
sshgw_host_key	Generated automatically	PEM text	Secret. Automatically generated server identity key. Reset rotates the key: clients must verify and accept the new fingerprint before trusting the server.
sshgw_internal_token	Generated automatically	Text	Secret. Automatically managed gateway credential. Leave unchanged. If reset is necessary, restart every Core to restore native SSH sign-ins.

The Text UI tab limit is separate from the shared shell-session quota. For example, an eight-tab limit does not allow eight shells on one resource when the resource quota is three.

The server fingerprint appears in Summary → SSH bookmark on supported shell resources with a Summary tab. For resources without that menu, obtain the fingerprint from your administrator through a trusted channel.

Allow personal SSH keys for native SSH automation is a per-resource option, not an Advanced Setting. Enable it in the resource’s edit form only when needed for direct connections. The user’s registered SSH key then signs in on its own, in place of their account password and verification code; resource credentials, permissions, policy, and recording still apply. The sign-in is restricted to that resource. See direct SSH connections.

Sharing sessions and transferring files

Internal session sharing follows the user’s sharing permission. External guests additionally require the Session Proxy feature and a configured proxy. See session sharing and Files.

Setting	Default	Allowed values	What it controls
enable_external_session_participants	false	true / false	Allow guests without MisterShell accounts to join through one-time session invitation links.
proxy_base_url	Empty	0–500 characters	Public HTTPS address used to build guest invitation links. Guests must be able to reach this proxy.
session_invite_ttl_hours	24	1–720	Time a one-time invitation link remains redeemable, in hours. This is the invitation’s expiry, not the session duration.
files_max_upload_bytes	5368709120	1,048,576–1,099,511,627,776	Maximum size of one catalog or resource file upload. Enter bytes; the default is 5 GiB (5,368,709,120 bytes).

Resource checks and collection

Use these settings to control collection load and connection waits. Per-resource SSH timeout values override the global SSH defaults. Collection content is selected under Manage → Configuration, and recurring collection intervals are set under Scheduled Tasks.

Setting	Default	Allowed values	What it controls
facts_enabled	false	true / false	Enable the Facts feature and collection. Fact configuration, permissions, and licensed capabilities still determine what can be collected or displayed.
data_collection_concurrency	2	1–100	Maximum number of concurrent resource collections. Higher values increase collection load; stay within worker capacity.
dns_resolution_timeout_seconds	5	1–30	Maximum wait for hostname resolution, in seconds.
ssh_conn_timeout_seconds	30	1–300	Default wait to establish an SSH network connection, in seconds.
ssh_auth_timeout_seconds	30	1–300	Default wait for SSH authentication, in seconds.
ssh_banner_timeout_seconds	15	1–300	Default wait for the SSH server’s greeting, in seconds.
onboarding_discovery_proof_ttl_seconds	14400	600–86,400	Maximum server-side lifetime of a resource verification result, in seconds; 14,400 is four hours. The browser’s Verify → Save countdown is separately limited to 60 seconds and is not extended by this setting.

Workers and background tasks

Worker task capacity covers collection, diagnostics, and long-running session tasks. Session-specific limits apply in addition to task capacity. Increase concurrency only when the worker has enough CPU and memory; more parallel work can overload both the worker and its targets.

Setting	Default	Allowed values	What it controls
worker_max_concurrent_tasks	10	1–100	Maximum concurrent worker tasks, including long-running session tasks. New work is refused when the worker reaches this total.
local_max_concurrent_tasks	4	1–32	Maximum background tasks running locally per Core API process, such as application-side automation actions. Requires a Core restart to apply.
worker_task_max_execution_time_minutes	5	1–60	Age limit for unstarted tasks whose worker is missing or offline, and unstarted cancellation requests. Running tasks use their own execution deadlines; this does not extend snapshot or session duration.
scheduler_check_interval_seconds	60	10–3,600	Interval between checks for due scheduled tasks, in seconds. Requires a Core restart to apply. Each scheduled task also has its own configured interval.
worker_heartbeat_interval	30	5–300	Status-report interval, in seconds. Currently changes sensor and proxy cadence; worker reports remain every 30 seconds. Keep the offline-detection timeout above the effective report interval.
gateway_heartbeat_timeout	60	30–300	Seconds without a worker, sensor, or proxy status report before it is considered stale or offline.
gateway_ack_task_timeout_seconds	5	1–60	Seconds to wait for a worker to acknowledge a dispatched task.
worker_reconnect_interval	5	1–60	Worker retry interval in seconds. Changing it currently does not change the reconnect cadence; leave at the default.
gateway_max_result_size	1048576	1,024–20,971,520	Maximum task-result size in bytes; the default is 1 MiB. Oversized results are truncated and snapshots are marked failed. This does not control file-upload size.

AI usage

Control how much AI a user may consume. Models, agents, and their permissions are configured separately under AI Settings; this setting does not enable AI by itself.

Setting	Default	Allowed values	What it controls
ai_daily_token_limit_per_user	0	0–100,000,000	Daily total AI-token budget per user. 0 means unlimited. A token budget limits usage, not a fixed currency amount; cost depends on the selected model.

Notes editing

Notes use an editing reservation to prevent simultaneous changes. These limits release an abandoned editor or bound how long one editor can hold the reservation. See Notes.

Setting	Default	Allowed values	What it controls
notes_edit_lock_ttl_seconds	120	30–600	Seconds an editing reservation remains valid without renewal from the editor.
notes_edit_lock_max_seconds	600	60–3,600	Maximum duration of one editing reservation, in seconds, even while the editor keeps renewing it. Save before it expires.

Syslog collection and intrusion detection

These settings tune licensed Collector and IDS features; changing a limit does not grant a license. Configure actual log collectors and sensors under Fabric.

Setting	Default	Allowed values	What it controls
collector_ingest_rate_per_second	2000	1–1,000,000	Sustained device-log ingestion allowance, in records per second.
collector_ingest_burst	60000	10,000–10,000,000	Extra ingestion capacity for short bursts, in records. The minimum permits a full log batch.
collector_bucket_interval	30	5–300	Seconds between collector log shipments. Shorter intervals improve freshness but increase request frequency.
sensor_ruleset_update_mode	manual	auto, manual	manual uses uploaded ruleset bundles; auto fetches them through the Sensor Ruleset Update scheduled task. Configure that task’s interval under Scheduled Tasks.
sensor_suricata_version	8.0.5	major.minor.patch	Suricata version used when preparing rulesets. Match the engine version on your sensors; changing this setting does not upgrade the sensors.

Retention for device logs and IDS alerts is listed in the next section.

History and retention

All values below are days. Shorter retention reduces storage use and removes older evidence during cleanup. Increasing it cannot recover deleted data. Plan retention for your investigation and audit needs.

Retention applies independently to each kind of data. Session recordings also follow their Recording Policy; changing session history retention is not a replacement for that policy.

Setting	Default	Allowed values	What it controls
data_collection_retention_days	30	1–365	Saved resource snapshots.
health_metric_retention_days	90	1–365	Per-metric health history, independent of snapshot retention.
fact_version_retention_days	90	1–3,650	Superseded fact versions. The current version is kept.
fact_policy_retention_days	90	1–3,650	Closed compliance evaluation versions.
changelog_retention_days	90	1–3,650	Closed configuration versions. The current configuration per resource is kept.
session_log_retention_days	90	1–3,650	Session history records across all connection types.
policy_log_retention_days	90	1–3,650	Session and file-transfer policy decisions.
automation_runs_retention_days	90	1–3,650	Automation run records.
ai_usage_retention_days	90	1–3,650	AI usage records.
ai_audit_retention_days	7	1–3,650	AI audit metadata and retained request/response content.
collector_retention_days	7	1–90	Searchable device syslog.
sensor_alert_retention_days	30	1–3,650	IDS alert records.
security_log_retention_days	90	1–3,650	Security audit events.
api_log_retention_days	90	1–3,650	API request logs.
app_log_retention_days	14	1–365	Persisted application and worker logs.
task_log_retention_days	30	1–365	Scheduled-task execution logs.
worker_task_retention_days	30	1–365	Completed worker-task records.
local_tasks_retention_days	90	1–3,650	Completed or failed application-side background-task records.

Database backup destination

Configure the SFTP destination, then enable and schedule Database Backup under Scheduled Tasks. These fields alone do not schedule backups. Database backups do not include every file or recording needed for a complete recovery; follow Backup and Restore.

Setting	Default	Allowed values	What it controls
backup_sftp_host	Empty	Text	SFTP server hostname receiving database archives.
backup_sftp_port	22	1–65,535	SFTP server port.
backup_sftp_username	Empty	Text	Account with permission to write archives to the destination.
backup_sftp_password	Empty	Text	Secret. Password for the backup SFTP account.
backup_sftp_remote_path	/backups	Text	Destination directory on the SFTP server.

Use a trusted SFTP endpoint and network path: the backup connection does not verify or pin the server’s SSH host key. Test backup and restore before relying on the schedule.

Performance and monitoring

These controls trade memory, freshness, and request load. Change one value at a time and check the effect in Fabric and Diagnostics.

Setting	Default	Allowed values	What it controls
core_cache_ttl_seconds	60	10–3,600	Seconds before cached configuration and access decisions expire. Longer values reduce repeated lookups but can delay permission revocation and token-rotation enforcement on another Core.
cache_max_memory_mb	256	64–16,384	Cache memory budget in MiB. Older cache entries are evicted when needed; this is not a limit on total application or database memory.
fabric_sample_interval_seconds	5	2–60	Seconds between Fabric statistics samples on each Core. Smaller values produce more frequent monitoring updates.

Logging and troubleshooting

Use normal logging for day-to-day operation. More verbose worker logging can increase log volume; reduce it after troubleshooting. See Diagnostics to read the logs.

Setting	Default	Allowed values	What it controls
fastapi_log_level	Empty	Empty, DEBUG, INFO, WARNING, ERROR, CRITICAL	Core API log level. Empty uses the deployment’s LOG_LEVEL environment setting. Requires a Core restart to apply.
worker_log_level	INFO	DEBUG, INFO, WARNING, ERROR, CRITICAL	Worker log level, applied through worker status updates.
enable_debug_mode	false	true / false	Development-only cookie mode: permits sign-in cookies over HTTP and relaxes cross-site cookie restrictions. Keep off in production. It does not increase logging verbosity; the DEBUG_MODE environment setting can also enable it.

Maps

Choose map backgrounds for dashboards, resource summaries, location editing, and search previews.

Setting	Default	Allowed values	What it controls
carto_api_key	Empty	0–4,096 characters	Secret in the settings table, but supplied to signed-in browsers to load map tiles. Empty uses OpenStreetMap; a CARTO Basemaps key enables light/dark backgrounds.

Configure map backgrounds

The optional carto_api_key setting selects the map backgrounds used throughout the application: the dashboard map, location editor, resource summary, and search location previews.

Setting	Light theme	Dark theme
Empty (default)	OpenStreetMap	OpenStreetMap, with a light background
CARTO Basemaps key configured	CARTO Positron	CARTO Dark Matter

To enable CARTO:

1. Request a dedicated CARTO Basemaps API key.
2. In CARTO’s key management, restrict the key to the website domains used to access your MisterShell deployment. Use a Basemaps key rather than a general CARTO account credential.
3. Open Settings → System → Advanced Settings and search for carto_api_key.
4. Enter the key in the Value cell and click Save. The setting is encrypted in storage and displayed in masked form.
5. Open a map and switch the application theme to check the light and dark backgrounds. Markers, map position, and zoom are preserved when the background changes.

The key is shared across the deployment. Authenticated users’ browsers receive it to request tiles directly from CARTO, even when those users cannot read Advanced Settings. Encryption and masking do not hide the key from browser users; the domain restrictions limit where it can be used.

To replace the key, edit and save the same row. To remove it, click the row’s Reset to Default action and confirm. Reset clears the stored key and restores OpenStreetMap. Leaving the secret input untouched keeps the existing key.

Saving or resetting refreshes maps in your current browser session without a server restart. Other sessions pick up the change when they reopen or reactivate a map after the one-minute configuration cache expires; reloading the page also fetches the current configuration.

If maps remain light, check that the key was saved, the application is in dark mode, and the browser can reach CARTO. Failed configuration loads or CARTO tile requests fall back to OpenStreetMap. If CARTO displays an API key required watermark, check the key and its domain restrictions, then reload the page to discard an older displayed map. Watermarked images may be delivered as successful requests, so they do not automatically trigger fallback.

Setup and automatically managed values

Use System → Config for guided setup and Fabric to manage components. These rows describe setup state or credentials maintained by MisterShell; they are not everyday tuning controls.

Setting	Default	Allowed values	What it controls
quickstart_completed	false	true / false	Whether the initial setup wizard has been completed. Resetting the flag does not undo configured values.
quickstart_size	small	small, medium, large	Deployment size selected in the setup wizard. Use the wizard to apply a size preset; changing this label alone does not resize the deployment.
default_worker_token	Generated automatically	Text	Secret. Automatically provisioned credential for the embedded worker. Leave it managed by MisterShell; do not use it to enroll remote workers.

Permissions

• Read Advanced Settings: app.settings.read.
• Edit or reset values: app.settings.write.
• MFA changes use the separate Auth Providers permissions and workflow. Feature-specific license requirements still apply, including IDS operation when changing its update mode.