---
title: Settings Reference
description: Complete reference for every option in the Sencho Settings Hub.
---

Open the Settings Hub by clicking the **Profile** icon in the top bar and selecting **Settings**. The sidebar groups every section into themed groups so related settings live together.

<Frame>
  <img src="/images/settings/settings-hub-grouped.png" alt="Settings Hub with the grouped sidebar" />
</Frame>

### Sidebar groups

| Group | What it covers |
|-------|----------------|
| **Personal** | Account, Appearance |
| **Access** | License, Users, SSO, API Tokens |
| **Infrastructure** | Nodes, Fleet Mesh, Registries, Cloud Backup, App Store |
| **Monitoring** | Host Alerts, Docker & Storage |
| **Notifications** | Channels, Notification Routing |
| **Automation** | Webhooks |
| **Organization** | Labels |
| **Security** | Vulnerability Scanning |
| **Operations** | Data Retention, Developer Diagnostics, Recovery |
| **Help** | Support, About |

Sections that require a higher license tier stay hidden until the operator has the matching license. Admin-only sections (Users, SSO, API Tokens, Fleet Mesh, Registries, Cloud Backup, Notification Routing, Vulnerability Scanning) stay hidden for non-admin operators.

### Page chrome

Every section renders inside the same masthead-and-sidebar layout. The masthead breadcrumb on the left tells you exactly where you are. Metadata pills on the right tell you what's loaded.

| Pill | Meaning |
|------|---------|
| **SCOPE** `operator` / `global` | Setting applies to your account or this browser (Personal sections) or to the whole instance (every other non-node group) |
| **NODE** `<node name>` | Setting is per-node and is currently being edited against this node |
| **EDITED** `<count>` pending / `saved` | The current section has unsaved changes |
| Section-specific stats | Each section can publish its own pills: `2FA on`/`off` and `BACKUP <n> left` (Account); `PLAN`, `TRIAL <n>d left`, `RENEWS`, `STATUS` (License); `OPERATORS` (Users); `CHANNELS` (Channels); `ROUTES` (Notification Routing); `WEBHOOKS` and `ENABLED` (Webhooks); `LABELS` (Labels); `TRIVY managed`/`host`/`missing` and `POLICIES` (Vulnerability Scanning); `PROVIDER`, `USED`, `SNAPSHOTS` (Cloud Backup); `DEV MODE` (Developer Diagnostics) |

### Quick search

Click **Filter** at the top of the sidebar, or press `Ctrl+K` / `⌘K` while the hub is open, to open the command palette. Type any section name, keyword, or synonym (for example, `saml` finds SSO and `trivy` finds Security) and press Enter to jump to it.

<Frame>
  <img src="/images/settings/settings-search.png" alt="Settings command palette filtered to a webhook query" />
</Frame>

### Node scope

For node-scoped sections the masthead replaces the **SCOPE** pill with a **NODE** pill showing the active node name. Switch the active node from the top bar's **Switch node** button to edit a different node's per-node settings.

<Frame>
  <img src="/images/settings/settings-node-scope.png" alt="Host Alerts section showing the NODE pill in the masthead" />
</Frame>

---

## Account

**Scope:** Operator (applies to the signed-in account)

The Account section manages password and two-factor authentication for the operator currently signed in. The masthead publishes a **2FA** pill so you can see at a glance whether the second factor is enabled.

<Frame>
  <img src="/images/settings/settings-account-2fa.png" alt="Account section showing the Password form and the Two-factor authentication card" />
</Frame>

### Password

| Field | Description |
|-------|-------------|
| **Current password** | Your existing password. Required to change any auth setting. |
| **New password** | Minimum 8 characters. 12 or more is recommended. |
| **Confirm new password** | Must match New password. |

Click **Update password** to apply. Existing sessions remain valid.

### Two-factor authentication

When 2FA is off, a **Set up 2FA** button opens the enrolment dialog. The dialog walks through scanning the QR code in an authenticator app (Authy, 1Password, Aegis, etc.) and verifying a code.

Once enrolled, the card shows:

| Element | Description |
|---------|-------------|
| **Authenticator app** | Confirms the enrolment is active. |
| **Backup codes** | Shows how many single-use recovery codes remain. **Regenerate** issues a fresh set; the count resets to ten. |
| **Require 2FA on SSO sign-in** | Visible only when an SSO provider is configured. When on, SSO logins must also pass the second factor; when off, SSO logins skip it. |
| **Disable 2FA** | Removes the second factor after a confirmation prompt. |

See [Two-Factor Authentication](/features/two-factor-authentication) for the enrolment walkthrough and recovery options. If you lose access to your authenticator and have no backup codes left, an admin can clear your second factor from the [Users](#users) section.

---

## Appearance

**Scope:** This browser (preferences are saved to local storage)

Control how dense and how interactive the workspace feels. Each browser remembers its own choices so a compact laptop setup does not force the same rhythm on a larger desktop.

<Frame>
  <img src="/images/settings/appearance-density.png" alt="Appearance settings showing the Density selector, Deploy progress modal, and Diff preview toggles" />
</Frame>

### Density

| Value | When to pick it |
|-------|-----------------|
| **Comfortable** | Default spacing. Roomier rows and tiles for review and orientation. |
| **Compact** | Tighter rows and tiles. Fits more stacks, tasks, and audit entries on screen at once. |

Density affects the dashboard stack table, the resource gauge strip, the Settings Hub sidebar, the Schedules and Audit Log tables, and every other data table in Sencho. Typography, color, and layout structure stay the same; only vertical padding compresses.

### Deploy progress modal

When enabled, Sencho streams live output in a modal whenever you deploy, restart, update, install, or run a Git operation. The modal closes automatically on success or stays open on failure so you can read the error output.

| Value | Behavior |
|-------|----------|
| **Enabled** | A progress modal opens for every long-running operation |
| **Disabled** (default) | Operations run silently; results surface via toast notifications only |

### Diff preview before save

When enabled, clicking **Save & Deploy** or **Save Only** in the compose or env editor opens a side-by-side diff modal before writing anything to disk. The left pane shows the current on-disk content; the right pane shows your unsaved edits, with additions highlighted green and removals highlighted red.

| Value | Behavior |
|-------|----------|
| **Enabled** | Diff modal opens on every save that has unsaved changes |
| **Disabled** (default) | File is saved directly without a review step |

If there are no unsaved changes the modal is skipped and the save proceeds immediately. See [Diff preview before save](/features/editor#diff-preview-before-save) in the Editor guide for the full workflow.

---

## License

**Scope:** Operator-facing, but reflects the instance license

Activate, view, or deactivate the license for this Sencho control plane. The masthead publishes a **PLAN** pill showing the current tier, a **TRIAL** pill with days remaining if a trial is active, a **RENEWS** pill with the next renewal date, and a **STATUS** pill if the license is in an unusual state (expired, error).

<Frame>
  <img src="/images/settings/settings-license.png" alt="License section showing the Plan, Customer, Product, License key, and Deactivate action" />
</Frame>

| Element | Description |
|---------|-------------|
| **Plan** | The active tier (Sencho Community, Sencho Admiral, or Sencho Admiral (Trial)) with a tier badge. |
| **Customer** | The customer name on file with Lemon Squeezy (paid plans only). |
| **Product** | The product (paid plans only). |
| **License key** | The active key, masked to the last four characters. |
| **Trial countdown** | Days remaining. Visible only while a trial is active. |
| **Manage subscription** | Opens the Lemon Squeezy customer portal to update payment, view invoices, or cancel. |
| **Deactivate** | Releases the key from this instance and reverts to Community features. |
| **See pricing** | Direct link to the pricing page; visible on Community or when an existing license has expired. |

See [Licensing & Billing](/features/licensing) for the full walkthrough including trial activation.

---

## Users

<Note>
  User management requires an admin role. Community supports unlimited accounts with the Admin and Viewer roles.
</Note>

**Scope:** Global

Create and manage user accounts with role-based access. The masthead publishes an **OPERATORS** pill with the total user count.

| Action | Description |
|--------|-------------|
| **Create user** | Add a new account with username, password, and role. |
| **Edit user** | Change an existing user's password or role. |
| **Delete user** | Remove a user account (you cannot delete your own account). |
| **Reset MFA** | Clears the second factor for a user who has lost access to their authenticator. |

**Available roles:**

| Role | Tier | Description |
|------|------|-------------|
| **Admin** | Community | Full access to all features |
| **Viewer** | Community | Read-only access to stacks and nodes |
| **Deployer** | Admiral | Can view stacks and trigger deployments |
| **Node Admin** | Admiral | Full stack and node management, no system settings |
| **Auditor** | Admiral | Read-only plus audit log access |

See [RBAC & User Management](/features/rbac) for details on what each role can access.

---

## SSO

<Note>
  Custom OIDC and the preset providers (Google, GitHub, Okta) are available on Community; LDAP / Active Directory requires Admiral.
</Note>

**Scope:** Global, admin-only

Configure Single Sign-On providers for centralized authentication. Each provider type has its own configuration card with connection fields, a test button, and an active toggle.

See [SSO](/features/sso) for the full configuration walkthrough.

---

## API Tokens

<Note>
  API Tokens are available on every tier. Creation, listing, and revocation require an admin role.
</Note>

**Scope:** Global, admin-only

Create and manage long-lived API tokens for external integrations and automation. Tokens can be scoped to specific permissions.

See [API Tokens](/features/api-tokens) for the full walkthrough.

---

## Host Alerts

**Scope:** Per-node (applies to the currently selected node)

Configure the host resource thresholds that trigger warnings, the suppression cadence for repeated alerts, and whether unexpected container exits raise a crash alert. These are alerting thresholds, not enforcement: Sencho warns when a metric crosses a line, it never throttles or kills containers. The masthead **NODE** pill names which node you are configuring; the **EDITED** pill counts unsaved changes.

<Frame>
  <img src="/images/settings/settings-host-alerts.png" alt="Host Alerts section showing the Host thresholds and Crash capture subsections" />
</Frame>

### Host thresholds

| Setting | Default | Description |
|---------|---------|-------------|
| **CPU limit** | 90% | Alerts fire when host CPU utilization exceeds this percentage. The input warns at values above 95%. |
| **RAM limit** | 90% | Set this below the point at which the host starts paging to swap. |
| **Disk limit** | 90% | Low free space slows image pulls and backups. |
| **Alert suppression** | 60 min | How long to wait before resending a host alert while the metric stays over threshold. The follow-up message includes a count of suppressed cycles. Range 1 to 1,440 minutes. |

### Crash capture

| Setting | Default | Description |
|---------|---------|-------------|
| **Global crash capture** | On | Watch every managed container for unexpected exits. When on, Sencho sends a notification whenever a container exits with a non-zero status outside a planned stop. |

Click **Save alerts** to apply.

---

## Docker & Storage

**Scope:** Per-node (applies to the currently selected node)

Configure the reclaimable-space alert, the reclaimable-space banner, and automatic image cleanup after updates.

### Storage alerts

| Setting | Default | Description |
|---------|---------|-------------|
| **Janitor threshold** | 5 GiB | Alert when reclaimable Docker data (images, volumes, build cache that `docker prune` could free) exceeds this size. Set to `0` to disable the alert. |
| **Show reclaimable-space banner** | On | Show the reclaimable-space banner at the top of the Resource Hub when this node has unused images, stopped containers, or dangling volumes to clear. |

### Image cleanup

| Setting | Default | Description |
|---------|---------|-------------|
| **Prune dangling images after updates** | On | When a stack update or a Sencho self-update finishes, remove the node's dangling (untagged) image layers, including the one the update just orphaned. Only untagged layers are touched: tagged images, your volumes, and your data are never removed. Turn it off to keep every old layer. |

Click **Save settings** to apply.

---

## Fleet Mesh

<Note>
  Fleet Mesh is admin-only.
</Note>

**Scope:** Per-node (applies to the currently selected node)

Control the cross-node service mesh data plane for the selected node.

| Setting | Default | Description |
|---------|---------|-------------|
| **Auto-recreate mesh network** | Off | If `sencho_mesh` is removed at runtime, rebuild it at the same subnet on the next 10-second tick. Off by default; leave it off and restart Sencho manually for the safest path. See [Sencho Mesh](/features/sencho-mesh) for the reconciler behavior. |

Click **Save settings** to apply.

---

## Registries

<Note>
  Docker Hub, GHCR, and custom registry credentials are available on every tier. AWS ECR requires a Sencho Admiral license.
</Note>

**Scope:** Global, admin-only

Configure private Docker registries so Sencho can pull images that require authentication.

See [Private Registries](/features/private-registries) for the full walkthrough.

---

## Cloud Backup

<Note>
  Custom S3-compatible storage is available on every tier. Sencho Cloud Backup is an Admiral feature.
</Note>

**Scope:** Global, admin-only

Mirror fleet snapshots to Sencho Cloud Backup or any S3-compatible storage so a control-plane loss does not take the recovery history with it. The masthead publishes a **PROVIDER** pill (`sencho` / `s3` / `disabled`), a **USED** pill showing storage consumption, and a **SNAPSHOTS** pill with the cloud object count.

<Frame>
  <img src="/images/settings/settings-cloud-backup.png" alt="Cloud Backup section with Sencho Cloud Backup mode selected" />
</Frame>

### Storage modes

| Mode | When to pick it |
|------|-----------------|
| **Disabled** | Snapshots stay on the control plane's local disk only. Default for fresh installs. |
| **Sencho Cloud Backup (included)** | Replicate snapshots to managed storage that ships with the Admiral subscription. On first selection, click **Activate** to provision the 500 MB allowance (backed by Cloudflare R2, scoped to this Admiral license). Auto-upload is always on for this mode. The **Test** and **Reprovision** buttons appear on the activated card if you need to verify connectivity or replace the credentials. |
| **Custom S3 (BYOB)** | Point Sencho at your own S3-compatible bucket (AWS S3, Cloudflare R2, MinIO, Backblaze B2). Required fields: **Endpoint URL**, **Region**, **Bucket**, **Path Prefix** (default `sencho/`), **Access Key ID**, **Secret Access Key**. The secret access key is masked after save. Use **Test connection** to verify credentials, then toggle **Auto-upload** to start replicating snapshots. |

The **Cloud Snapshots** list at the bottom of the section is an inventory of objects currently in the configured destination. Each row exposes a **Download** icon and a **Delete** icon.

See [Fleet Snapshots & Backups](/features/fleet-backups) for restore workflows.

---

## Nodes

**Scope:** Global

Manage connections to local and remote Sencho instances. This is the same interface as the [Multi-Node](/features/multi-node) feature; see that page for the full walkthrough.

Quick reference:

| Action | How |
|--------|-----|
| Add a remote node | Click **+ Add Node** |
| Generate a token for this instance | Click **Generate Token** |
| Test an existing node's connectivity | Click the wifi icon on any row |
| Edit a node | Click the pencil icon |
| Delete a node | Click the trash icon (remote nodes only) |

---

## Channels

**Scope:** Per-node (each node has its own notification agents; remote nodes dispatch alerts through their own channels)

Configure external destinations for alert notifications. Three agent types are available on separate tabs: **Discord**, **Slack**, and **Webhook**. The masthead publishes a **CHANNELS** pill showing how many agents are enabled (for example, `2/3`).

For each agent:

| Field | Description |
|-------|-------------|
| **Enabled** toggle | Activates or deactivates this agent. Disabled agents receive no messages even if a URL is saved. |
| **Webhook URL** | The endpoint Sencho will POST to when an alert fires. |

Click **Save** to persist changes. Click **Test** to send a test payload immediately and verify delivery.

At least one agent must be enabled for stack alerts to deliver notifications. See [Alerts & Notifications](/features/alerts-notifications) for how to create alert rules.

---

## Notification Routing

<Note>
  Creating, editing, and deleting routes is admin-only.
</Note>

**Scope:** Global, admin-only

Create routing rules that direct specific alert types to specific notification channels. Rules let you send critical alerts to one channel and informational alerts to another. The masthead publishes a **ROUTES** pill with the active rule count.

| Field | Description |
|-------|-------------|
| **Name** | Operator-facing label for the rule. |
| **Node** | Specific node, or all nodes if left empty. |
| **Stack patterns** | Glob patterns to match stack names (multi-select). |
| **Labels** | Apply this rule to stacks that carry any of the selected labels. |
| **Categories** | Event categories that trigger the rule (crash, deploy, vulnerability, etc.). |
| **Channel type** | `discord`, `slack`, or `webhook`. |
| **Channel URL** | The destination endpoint for this rule. |
| **Priority** | Order in which rules are evaluated; the first match wins. |
| **Enabled** toggle | Mute a rule without deleting it. |

Each rule keeps an execution history (collapsible per row) showing which alerts triggered it, when, and whether the delivery succeeded.

See [Notification Routing](/features/alerts-notifications#notification-routing) for the full walkthrough.

---

## Webhooks

<Note>
  Managing webhooks is admin-only.
</Note>

**Scope:** Global

Create and manage HTTP webhooks that external systems (CI/CD pipelines, automation tools) can call to trigger stack actions. The masthead publishes **WEBHOOKS** and **ENABLED** counts.

| Field | Description |
|-------|-------------|
| **Name** | Operator-facing label. |
| **Stack** | Target stack for this webhook. |
| **Action** | `deploy`, `restart`, `update`, etc. |
| **Secret** | Auto-generated on create. Shown once in a confirmation dialog so you can copy it into your CI secret store; recoverable later via **Copy secret** on the row. |
| **Enabled** toggle | Mute a webhook without deleting it. |

Each row exposes an execution history with timestamp, trigger source, duration, and any error returned to the caller.

See [Webhooks](/features/webhooks) for the full walkthrough including authentication and CI examples.

---

## Labels

<Note>
  Label organization (create, edit, assign, remove) and bulk label actions (apply or remove a label across multiple stacks in one operation) are available on every tier.
</Note>

**Scope:** Per-node

Create, edit, and delete labels used to organize and filter stacks across your fleet. Each label has a name and one of ten available colors. Up to 100 labels per node. The masthead publishes a **LABELS** pill with the current and maximum counts.

See [Stack Labels](/features/stack-labels) for the full walkthrough.

---

## Vulnerability Scanning

<Note>
  Vulnerability Scanning is admin-only. The Trivy installer, the **Auto-update Trivy** toggle (which also requires a managed Trivy binary), and CVE/misconfig suppressions are available on all tiers; scan policies require an Admiral license.
</Note>

**Scope:** Per-node

Manage the Trivy scanner, scan policies, suppressions, and acknowledgements that power [vulnerability scanning](/features/vulnerability-scanning) across the fleet. The masthead publishes a **TRIVY** pill (`managed` / `host` / `missing`) and a **POLICIES** pill with the active rule count.

<Frame>
  <img src="/images/settings/settings-security.png" alt="Security section showing the Trivy installer card and the empty scan-policy state" />
</Frame>

### Trivy scanner

| Element | Description |
|---------|-------------|
| **Status** | `Installed (managed)` when Sencho manages the binary, `Installed (host)` when an existing host binary is being reused, or empty when nothing is detected. |
| **Version** | The current Trivy version, when installed. |
| **Install / Update / Uninstall** | Lifecycle actions for the managed binary. Uninstall asks for confirmation. |
| **Auto-update Trivy** toggle | When on, Sencho checks daily and installs newer Trivy releases automatically. Requires a managed Trivy binary. |

### Scan policies

A scan policy enforces a severity threshold on a set of stacks. Each policy carries a severity level (`CRITICAL`, `HIGH`, `MEDIUM`, `LOW`), a stack pattern (regex), a **Block on deploy** toggle, and an **Enabled** toggle. Use **Add policy** to create one.

### CVE Suppressions and Misconfig Acknowledgements

- **CVE Suppressions** are fleet-wide accepted CVEs. They apply at read time across every instance and never modify stored scan data. See [CVE Suppressions](/features/cve-suppressions).
- **Misconfig Acknowledgements** are fleet-wide accepted misconfigurations, with the same read-time semantics.

### Fleet role

Sencho instances on the Admiral tier can act as a security control plane for the fleet or as a replica. When this instance is a replica, the section shows a **Managed by control node** banner and a **Demote to control** button that converts the replica back into a standalone control.

---

## Data Retention

**Scope:** Per-node

How long Sencho keeps historical data on this node before pruning it.

| Setting | Default | Max | Description |
|---------|---------|-----|-------------|
| **Container metrics** | 24 hrs | 8,760 (1 year) | How long to keep per-container CPU, RAM, and network history for dashboard charts. |
| **Notification log** | 30 days | 365 | How long to keep alert and notification history. |
| **Scan history per image** | 50 scans | 1,000 | How many vulnerability scans to keep per image. Older scans beyond the cap are pruned. |
| **Audit log** | 90 days | 365 | How long to keep audit trail entries. Requires Admiral. |

Click **Save settings** to apply.

---

## Developer Diagnostics

**Scope:** Per-node

Debug diagnostics for this node. Most operators can leave this off. The masthead publishes a **DEV MODE** pill (`on` / `off`).

| Setting | Default | Description |
|---------|---------|-------------|
| **Developer mode** | Off | Enables real-time metrics streams and verbose debug diagnostics in the UI. Does not affect [Global Observability](/features/global-observability) streaming, which is always on. |

Click **Save settings** to apply.

---

## App Store

**Scope:** Per-node

Configure the template source used by the App Store.

| Element | Description |
|---------|-------------|
| **Default registry** | `api.linuxserver.io/api/v1/images` (read-only; used when no custom URL is set). |
| **Custom registry URL** | A URL pointing to a Portainer v2 compatible template JSON file. Overrides the default registry. Leave empty to use the default. |
| **Reset to default** | Clears the custom URL and reverts to the default registry. |
| **Save & refresh** | Saves the URL and immediately refreshes the cached template list. |

See [App Store](/features/app-store#custom-template-registry) for more on custom registries.

---

## Support

**Scope:** Global

Links to help resources, with an additional channel for Admiral operators.

### Resources (all tiers)

| Resource | Description |
|----------|-------------|
| **Documentation** | Opens docs.sencho.io. |
| **GitHub Issues** | Report bugs and request features on GitHub. |

### Admiral support

| Channel | Tier | Description |
|---------|------|-------------|
| **Priority Email Support** | Admiral | Direct email support with responses within 24 hours. |

Community operators see an upgrade callout with a link to the pricing page in place of the support channels.

---

## About

**Scope:** Global

Displays instance information at a glance.

| Field | Description |
|-------|-------------|
| **Version** | Current Sencho version. |
| **Tier** | Community or Admiral badge. |
| **License Status** | active, trial, expired, or community. |
| **Instance ID** | First eight characters of the unique identifier for this Sencho control plane (used by the license server to identify it). |

The **Links** section contains a link to the full changelog on GitHub.
