Files
sencho/docs/features/pilot-agent.mdx
T
Anso 08caa914ce docs: v1 docs refresh (batch 2) (#988)
* docs(atomic-deployments): refresh page around current UI and behavior

Rewrites the page to match the v1 docs refresh template. Corrects
several factual errors against the current code, fills in missing
detail, and adds a screenshot of the rollback overflow menu.

Notable corrections:
- Scheduled tasks do not run atomically; only stack editor Deploy and
  Update, App Store installs, webhook triggers, and image auto-updates
  pass the atomic flag through to ComposeService.
- Rollback lives in the stack editor's More actions overflow menu, not
  on the action bar directly. The backup timestamp renders as a
  sub-line of the menu item.
- Health probe is a 3-second window with an exit-code check on every
  container labelled with the compose project name; describe this
  exactly rather than as 'waits briefly'.
- Document where backups live (DATA_DIR/backups/<stack>/), why they
  are kept outside the compose folder, and that the slot is one per
  stack with overwrite semantics.
- Document the four streamed log markers users see in the deploy
  progress modal during the atomic flow.
- Add a troubleshooting accordion group covering missing menu entry,
  late crashes outside the probe window, manual-intervention message,
  and the single-slot retention edge case.

* docs(deploy-enforcement): refresh page for v1 and align with current enforcement paths

Update the page to match the current pre-flight gate behavior, the v1 modal chrome on the
block dialog, and the AccordionGroup troubleshooting pattern used across the v1 docs.

Drift items corrected:
- Replace the broken vulnerability-scanning/deploy-blocked-dialog.png reference with three
  fresh captures under docs/images/deploy-enforcement/ (policy list, policy editor, block
  dialog).
- Drop "Recreate from the stack actions menu" and the git-source apply pre-flight claim;
  neither path runs the gate.
- Add bulk label deploy and the auto-update scheduler to the enforced code paths, with a
  dedicated subsection for the auto-update interaction (alert-and-skip, not 409).
- Drop the false claim that severity chips in the block dialog are clickable; the dialog
  is informational.
- Document the compose-parse-fails-closed branch with its synthetic violation label.
- Refresh dialog copy to reflect the v1 ModalDestructiveHeader (kicker, title, button
  variants).
- Convert the troubleshooting Q&A into AccordionGroup blocks and add accordions for the
  compose-parse-error case and the auto-update-skipped case.
- Quote the verbatim audit-log summary format.

* docs(blueprints): refresh against v1 UI and add federation/state-review coverage

* docs(git-sources): refresh page against v1 UI and current behavior

Rewrites the page against the v1 docs refresh template (Note tier-gate,
sectioned anatomy, AccordionGroup troubleshooting), aligning prose with
the live UI labels and the current code paths.

Corrections:
- Authentication toggle reads "Public (no auth)" / "Personal Access
  Token" (not "None"), and apply mode "Auto-write files" (not
  "Auto-write").
- Diff dialog kicker is GIT . PULL PREVIEW; local-edits state opens an
  Overwrite local edits? confirmation modal whose primary button is
  Overwrite and apply.
- Sidebar pending indicator is a small GitBranch icon, not a brand-color
  dot, and the image-update dot takes priority over it on the same row.
- Pending update banner appears in the panel; Review re-fetches the
  commit and opens the diff (no client-side payload caching).

Adds coverage for:
- Anatomy of the panel (pending banner, form, last-applied stat strip,
  footer actions).
- 10-second webhook debounce window.
- Pending compose/env content is encrypted at rest in the database, not
  just the token.
- Auth/host failures map to HTTP 400, never 401, so they do not sign
  the user out.
- Per-stack lock serializes pull, apply, and create-from-git so a
  webhook firing during a manual apply waits rather than racing.
- Compose validation has a 10-second budget; clone fetches have a
  30-second timeout.
- New troubleshooting accordion for Pending commit has changed since
  this pull was fetched.

Recaptures all five screenshots from the v0.74.x production node,
signed in as admin: panel, create-from-git tab, pull-preview diff
dialog, sidebar GitBranch pending icon, webhook Action select with
Git source sync highlighted.

* docs(stack-labels): refresh page for v1 sidebar grouping and fleet-action surface

- Lead with the v1 behavior the previous page did not cover: the sidebar
  groups stacks under collapsible label headers (PINNED first, label
  buckets sorted by stack count desc then name asc, UNLABELED last)
  with a count chip per group. Trailing colored dots on each row
  (max 3 + N overflow, paid-only) supplement the headers.
- Drop the stale claim that a label-pill filter bar lives between
  search and the stack list; that UI no longer exists.
- Drop the right-click-on-pill bulk actions table (Deploy all / Stop
  all / Restart all). The legacy per-node action endpoint stays in
  the backend but no longer has a UI binding, so the page documents
  only what users can click today.
- Document the two Skipper+ Fleet Action cards: Stop fleet by label
  (name match across nodes, autocomplete, per-node breakdown,
  HTTP 429 on per-node concurrency) and Bulk label assign (per-node,
  replace semantics, clear on empty selection).
- Document the inline 'New label' form inside the stack right-click /
  three-dot Labels submenu, the Settings - Advanced - Labels masthead
  N/50 stat, the LABELS - NEW / EDIT modal kickers, and the
  LABELS - DELETE - IRREVERSIBLE confirmation copy verbatim.
- Document the Fleet Overview Tags multi-select filter (filters by
  stack labels aggregated across nodes), with cross-link to fleet-view.
- Capture every screenshot fresh from production signed in as admin:
  sidebar-grouping, context-menu-labels, inline-create-form,
  settings-labels, create-label-dialog, fleet-tags-filter,
  fleet-actions. Drop the now-stale sidebar-with-labels,
  sidebar-filtered, and bulk-actions-menu captures.

* docs(dashboard): refresh page for v1 layout (status masthead, gauges, fleet heartbeat, restart map)

Aligns docs/features/dashboard.mdx with the redesigned Home tab. Replaces the obsolete
Recent Activity feed coverage with the actual DashboardActivityCard split (Fleet Heartbeat
when remote nodes are registered, Stack Restarts (7d) otherwise) and recaptures every
screenshot from the v0.74.x production node.

* docs(global-search): refresh page for v1 palette

- Note tier and role gating on the Pages list (Auto-Update, Console,
  Schedules, Audit) so the prose matches what the top bar exposes.
- Document the ACTIVE chip on the currently active node row.
- Document the 50-result cap counter and the Searching... loading state.
- Mention the ~250 ms debounce and clarify that filename matching
  includes the file extension.
- Replace stack screenshot with a redesigned capture and add empty-state
  Pages and Nodes captures showing the ACTIVE chip.

* docs(global-observability): refresh page for v1 layout (masthead, signal rail, filter strip, paused-resume chip)

Full rewrite against the current Logs tab and the v1 docs refresh template
(hero Frame, sectioned anatomy, AccordionGroup troubleshooting, refresh-cadence table).

Replaces the single overview screenshot with seven captures under
docs/images/global-observability/ (overview, masthead, signal-rail,
filter-strip, feed-bands, paused-resume-chip, error-only-filter), all from
the v0.75.x production node signed in as admin with PII scrubbed
(profile chip patched to AD, in-feed LAN IPs and third-party hostnames
substituted via DOM injection while the stream was paused).

Aligns prose with the actual UI labels and code:

- Masthead kicker reads LIVE LOGS · NODE · <NAME> with LOCAL for the
  local node; state word toggles Streaming / Idle / Offline; SESSION
  uses uppercase letter suffixes (1H 43M / 0M 12S) per formatUptime.
- Signal rail tile counts are scoped to the 2000-entry buffer and reset
  with Clear; CONTAINERS is buffer-bound, not a monotonic accumulator.
- Filter strip controls quoted verbatim (Stacks · All / Stacks · n,
  segmented controls All / Out / Err and All / Info / Warn / Error).
- Feed row anatomy: severity dot, timestamp, brand-cyan container name
  with stack/container tooltip, message tinted by source. Row tint
  follows detected level, which is regex-based, so an STDOUT line
  containing ERROR: still classifies as ERROR.
- Day bands: NOW, Nm AGO, Nh AGO, calendar date.
- Empty states: two-tier kicker over caption (Awaiting events / No matches).
- Pause keeps the SSE buffer filling up to the 2000-entry cap; resume pill
  reads <n> NEW · RESUME and counts the queue, not total arrivals during
  the pause.
- Download filename and row format quoted: sencho-logs-<ISO8601>.txt and
  [<ISO>] [<stack>/<container>] <LEVEL>: <message>.

Documents behavior the previous page never covered:

- Active-node scoping; node switch resets the stream and the buffer.
- SSE primary transport with 30-second server heartbeat and a 5-second
  polling fallback against /api/logs/global (server-capped at 500 lines
  per snapshot).
- Initial replay of the last 500 lines per container when the SSE
  connection opens, so the feed has context immediately.
- Display limits (2000 client buffer, 300 rendered rows, Showing last
  300 of N overflow notice).
- Refresh cadence table covering UI tick, flush cadence, polling
  cadence, SSE heartbeat, sparkline window, and the Idle threshold.

Adds a seven-accordion troubleshooting block (Offline state, gray Idle
dot, ERROR-without-tint, growing Resume pill, Clear-cutoff lag,
node-switch buffer drop, fleet-wide aggregation expectations).

Tightens the closing Note so it makes clear that Notification Log
Retention does not govern this live container stream.

* docs(alerts-notifications): refresh page for v1 and absorb notification-routing

Full v1 template rewrite of /features/alerts-notifications. Bundles in
the entire Notification Routing page so a reader sees channels, routing,
per-stack rules, and retention in one place; deletes the standalone
notification-routing.mdx and points all five cross-link sites at the new
in-page anchor.

* docs(alerts-notifications): drop "What's not in scope" section

The page should describe what Sencho does, not enumerate what it does
not ship. Users find missing integrations through the Webhook section
and the routing matcher reference; the explicit disclaimer added noise
without adding guidance.

* docs(audit-log): refresh page for v1 layout, expanded action list, troubleshooting accordion

- Clarify that the search/method/date filter strip lives in Table view only.
  Stream view always shows the unfiltered chronological feed.
- Fold the total-entries readout into the card subtitle wording where it
  actually renders, instead of describing it as a separate header element.
- Sharpen the Peak hour off-hours window to the literal 08:00 to 17:59
  working window the tile keys off, plus the 5% / 20% failure-rate tints.
- Note that the Actors tile names a sample actor alongside the new-IP count.
- Expand the example actions list to cover surfaces that have shipped since
  the last edit: per-service stack lifecycle, node cordon/uncordon, fleet
  replica role changes, Sencho Cloud Backup operations, Fleet Secrets, and
  blueprint federation pin updates.
- Correct the Settings path: Settings · Developer · Data retention card,
  Audit log input, Save settings button.
- Add a Troubleshooting AccordionGroup matching the rest of the v1-refresh
  pages: missing tab, filter scope, anomaly thresholds, export cap, and
  retention pruning.
- Replace all four screenshots with fresh captures of the current UI.

* docs(multi-node): refresh page for v1 layout, pilot agent mode, refreshed table columns

Rewrites docs/features/multi-node.mdx against the current product. The previous page predated the v1 Settings hub redesign and the Pilot Agent enrollment model, so it documented only the Distributed API Proxy add-node flow and missed the new Mode, Endpoint, and Labels columns on the Nodes table.

Restructures the page into 13 sections: intro, How it works, the local node, Choose a remote mode (decision table comparing Pilot Agent vs Distributed API Proxy), Add a remote node: Pilot Agent (three steps plus re-enrollment), Add a remote node: Distributed API Proxy (three steps), Switching between nodes, the Nodes table (full column reference), What Settings apply per node (verified against settings/registry.ts), License enforcement across nodes, Editing and deleting nodes, Security (token security, transport encryption, why no application-layer TLS), and Troubleshooting (AccordionGroup matching the v1 template used on audit-log, atomic-deployments, and deploy-progress pages).

Refreshes seven screenshots against the production node signed in as admin, scrubbing IPs and usernames before capture: full Nodes panel overview, Generate Node Token card with a placeholder token, Add node modal in Pilot Agent mode, Add node modal in Distributed API Proxy mode (with the inline plain-HTTP warning visible), Edit modal showing the Regenerate enrollment token card for a pilot agent, Pilot enrollment modal with the docker run command, refreshed node switcher popover, and a close-up of the table columns. Drops the obsolete add-node-form.png, http-warning.png, and per-node-scheduling/ folder.

* docs(fleet-view): refresh page for v1 layout, expanded tabs, cordon, sheet-based updates

- Aligns the Overview, Status, and Node Updates content with today's UI:
  the masthead's `The fleet` headline plus CPU / MEM / CONTAINERS stat tiles,
  the eight-tab strip (Overview, Snapshots, Status, Deployments, Traffic,
  Federation, Fleet Actions, Secrets) with per-tier visibility, and the
  Check Updates surface that is now a system sheet rather than a modal.
- Documents the toolbar (search, sort, filter popover with Status / Type /
  Severity / Tags sections) and the Grid / Topology segmented control
  including the topology graph's status pill (Online / Critical / Offline),
  connector colouring, ReactFlow controls and minimap.
- Documents the per-card surfaces that were missing from the prior page:
  Cordoned badge with cross-reference to Fleet Federation, fleet stack
  label dots in the drill-down, container drill-down rows (state dot,
  badge, image, status, open-in-editor hover button), and the Admiral
  three-dot Node actions menu for cordon / uncordon.
- Documents the Node Updates sheet anatomy (Recheck and Update all (n)
  header actions, four summary cards, node table columns, Update flow,
  reconnecting overlay timing, admin enforcement) and the GitHub Releases
  with Docker Hub fallback resolution path with its 30-minute cache.
- Replaces every stale screenshot with a fresh capture (overview,
  topology, drill-down, status tab, node updates sheet) and removes the
  obsolete files plus the empty docs/images/fleet/ folder.
- Reformats troubleshooting as an AccordionGroup matching dashboard,
  multi-node, and audit-log refreshes.

* docs(fleet-backups): refresh page for redesigned fleet and settings UI

Replace all six screenshots with current production captures. Update
content to reflect the new fleet header card, eight-tab layout, full-
page Cloud Backup settings with header stats, and corrected navigation
paths. Add cloud backup rows to the access control table.

* docs(fleet-backups): convert troubleshooting to AccordionGroup pattern

Match the foldable-accordion pattern used across the v1 docs refresh
batch. Merges the standalone Cloud Backup troubleshooting subsection
into a single Troubleshooting section at the bottom of the page with
seven accordions covering skipped nodes, two restore failure modes,
three cloud-upload failure modes, and a diagnostic logging entry.

* docs(remote-updates): refresh page for v1 sheet, accordion troubleshooting, factual fixes

Rewrites the page against the v1 docs refresh template (Note tier gate,
sectioned mechanism deep-dive, Frame screenshots with detailed alt text,
inline AccordionGroup troubleshooting), bringing it in line with the
recently-refreshed fleet-view, fleet-backups, dashboard, and audit-log
pages.

The page is repositioned as the mechanism deep-dive (prerequisites, what
runs on a node during an update, completion and failure detection,
recovery actions). The full UI tour for the Node updates sheet remains in
fleet-view so the two pages stop overlapping; remote-updates now links
into fleet-view#node-updates instead of restating the table anatomy.

Captures three screenshots from the production node, signed in as admin:
fleet-node-updates.png shows the Node updates sheet with eight nodes and
seven remote updates available; local-update-confirm.png shows the
LOCAL · UPDATE alert dialog with the Cancel and Update & restart buttons;
node-card-update-available.png shows the Opsix card with the Update
available pill and the Update to v0.76.7 outline button.

Corrects several factual claims that no longer matched the current code:

- The remote early-fail threshold is about 3 minutes, matching
  EARLY_FAIL_MS in backend/src/routes/fleet.ts, not 90 seconds.
- The Recheck button sits in the sheet header, not the footer.
- The component is a SystemSheet, so the page now consistently calls it
  the Node updates sheet instead of a dialog, with lowercase "Node
  updates" and lowercase "Update all (n)" matching the live UI.
- Reconnecting overlay polls /api/health every 3 seconds, not "every few
  seconds".
- The local Failed badge surfaces as soon as the helper writes its error
  file, by the 3-minute mark at the latest.

Documents the LocalUpdateConfirmDialog kicker, title, body, and CTA
verbatim, the Triggering... loading state on the Update buttons, the
four completion signals the gateway accepts (version change, process
startedAt change, offline-then-online transition, version at or above
the comparison target after 15 seconds), and the 60-second auto-clear
of the Updated badge.

Drops references to two screenshots that never existed
(fleet-node-updating.png, fleet-node-failed.png); the in-flight and
failed states are described in prose instead, the same way fleet-view
handles them.

* docs(scheduled-operations): refresh page for v1 timeline, fleet-wide update action, sheet-based run history

Rewrites the Scheduled Operations page against the v1 template
(Note tier gate, sectioned anatomy, Frame screenshots, AccordionGroup
troubleshooting) applied to sibling pages in this batch. Captures
seven fresh screenshots against the production node signed in as
admin (timeline, all-tasks, action-picker, create-restart,
create-prune, create-scan, run-history) and removes every legacy
PNG.

Documents the new "Auto-update All Stacks" action that was absent
from the page, extends the Skipper allow-list to all four Skipper
actions (Auto-update Stack, Auto-update All Stacks, Fleet Snapshot,
Vulnerability Scan) and clarifies that the action picker hides
operations the active tier cannot run.

Corrects several factual claims that no longer matched the code:

- Scheduled scan completion is `info`/`scan_finding` on a clean run
  and `warning`/`scan_finding` when findings are present (not
  `info`/`system` as previously stated). Cross-link now points at
  `alerts-notifications#vulnerability-scanning`.
- Lifecycle actions (auto_backup, auto_stop, auto_down, auto_start)
  execute against the local Sencho instance only; only Auto-update
  Stack / All Stacks have a remote-proxy code path. The page
  reinstates the guidance to schedule remote lifecycle operations
  from that node's own UI.
- Run history lives in a right-side sheet with a "Schedules ›
  <task> › Runs" breadcrumb and a Download CSV secondary action.
- Timeline masthead is described in terms of the v1 visual
  (`NEXT 24 HOURS` kicker, italic display heading, monospace date
  range, right-anchored Next pill with countdown, glowing cyan now
  rail, six-tick bottom axis).

* docs(rbac): refresh RBAC & user management page against v1 template

Bring /features/rbac onto the v1 docs refresh template (Note tier gate,
sectioned anatomy, Frame screenshots, AccordionGroup troubleshooting).
Recapture five screenshots from the production node signed in as admin
and remove the three stale captures under docs/images/rbac/.

Corrections vs. the prior page:
- Deployer no longer claims node:read in the permission matrix; the
  backend grants only stack:read and stack:deploy.
- Add the system:registries row (container registry management).
- Document the form as inline below the Add user button (not a modal).
- Note the (you) marker on the signed-in admin's row and the disabled
  delete icon on that row.

Additions:
- Settings nav location and hub-only visibility.
- 2FA reset row action with verbatim modal kicker, title, and body.
- Five-failure / 15-minute MFA lockout behavior and admin reset recovery.
- Token-version session-security table covering deletion, role change,
  password change, and admin 2FA reset.
- SSO password-fields-hidden line quoted verbatim and the per-provider
  Require MFA toggle.
- Audit-log emissions list for every user-management mutation.
- API tokens cross-link explaining the user-vs-machine boundary.
- Scoped permissions section retightened: scoped role picker is
  Deployer / Node Admin / Admin only; resource type is Stack or Node.

AccordionGroup with eight troubleshooting entries covering missing nav,
greyed role options, seat-limit errors, unexpected sign-outs, scoped
deployer mismatches, missing shield icon, re-locking MFA accounts, and
SSO role drift at provisioning.

* docs(2fa): refresh two-factor authentication and admin guide against v1 template

Bring /features/two-factor-authentication and /operations/two-factor-admin
onto the v1 docs refresh template (Note tier gate, sectioned anatomy, Frame
screenshots with descriptive alt text, AccordionGroup troubleshooting,
verbatim modal copy with kicker callouts). Recapture every screenshot under
docs/images/two-factor-auth/ from a fresh session and add six new captures
for surfaces the prior page did not document.

Corrections vs the prior pages:

- Panel rename: Settings -> Account & Security is now Settings -> Account,
  under the Identity group of the settings sidebar. Replaced every
  occurrence on both pages.
- Enrol dialog titles match the current modal: Pair your authenticator,
  Confirm the pairing, Save your recovery codes (was: Set up 2FA, Confirm,
  Save your backup codes). Step rail 01 PAIR / 02 CONFIRM / 03 ARCHIVE
  documented.
- Manual-entry affordance is the always-visible Secret manual entry row
  with a copy icon, not the toggleable Can't scan Show secret key link.
- Confirm step auto-submits on the sixth digit; no submit button. Verified
  in MfaChallenge.tsx and MfaEnrollDialog.tsx and called out explicitly.
- Authenticator-app list trimmed to match in-app copy (1Password, Bitwarden,
  Google Authenticator, or any TOTP app). Authy and Microsoft Authenticator
  dropped because the dialog does not mention them.
- Disable dialog: kicker SECURITY MFA DISABLE, title Turn off two-factor,
  destructive header, Disable button. Replaces the prior Disable 2FA
  paragraph that did not describe the dialog chrome.
- Regenerate dialog: two-step flow with kicker SECURITY BACKUP CODES, Confirm
  identity then New recovery codes, with the verbatim PREVIOUS CODES HAVE
  BEEN INVALIDATED warn rail on the show step. Documented that the dialog
  only accepts a TOTP, not a backup code.
- Per-user SSO toggle label corrected: Require 2FA on SSO sign-in (was:
  Require 2FA even when signing in via SSO). Added the per-provider vs
  per-user distinction on both pages (admins can also enable Require MFA
  on the SSO provider config, which is independent of the per-user toggle).
- Admin reset modal: verbatim USERS RESET 2FA kicker, Reset 2FA for
  <username> title, full-body copy reproduced. Documented that the reset
  bumps the target's token version and invalidates active sessions.

Additions:

- Sign-in throttle: five failed verifications lock the account for 15
  minutes, server returns 423 with Retry-After, UI shows the Retry in MM:SS
  countdown plus Rate limited label. Lockout recovery section explains
  that the counter only clears on a successful sign-in, so retries after
  the window expires re-lock immediately.
- Account panel anatomy section enumerates the three rows (Authenticator
  app, Backup codes, Require 2FA on SSO sign-in) plus the destructive
  Disable 2FA link, and the masthead 2FA on / BACKUP N left chips.
- Recovery codes section now covers all three count states (3 plus, 1 to 2,
  0) with verbatim helper text, tone, and the standalone No backup codes
  left callout that renders at zero. New screenshots for the 2-remaining
  and 0-remaining states.
- Cross-references to the admin operations page (CLI fallback, token version
  rotation, what a reset changes in the DB), the SSO page, and the RBAC
  page (per-provider Require MFA toggle, SSO auto-provisioning).

Troubleshooting on the feature page rewritten as an AccordionGroup with
nine entries: clock drift, wrong account selected, QR will not scan, lost
phone with no codes, lost codes with authenticator, ran out of codes,
unexpected SSO prompt (with both toggle causes), repeated lockout after
the window expires, missing shield icon on Users panel.

The admin operations page also gains the SSO + 2FA two-toggles table so
administrators can answer the per-user vs per-provider question without
context-switching between pages.

Six new images added; six existing images replaced. Total 14 captures.

* docs(rbac,host-console): drop enforcement-boundary detail from tier-gate notes

Operator-facing docs should state tier or role requirements once, in plain
customer-facing language, and leave the enforcement chain to the source.
Two surfaces on the v1-refreshed pages over-specified the gate:

- `features/rbac.mdx::Scoped permissions`: the Note enumerated both the UI
  hide on Skipper and the `/api/users/:id/roles` write rejection. The first
  half ("Scoped permissions require Admiral.") is the operator-relevant
  fact; the rest reads as a fence specification, which is awkward for an
  open-core product where the gate is readable in source anyway. Trimmed
  to just the tier claim.

- `features/host-console.mdx::Availability`: the paragraph already says
  who can use the console and that the Console tab is hidden on Community
  or Skipper. The trailing "Attempting to access the console endpoint
  directly without the correct license or role is rejected" is the same
  bypass-prevention coda. Dropped.

No functional behavior change; the gates themselves are untouched.

* docs(sso): refresh SSO & LDAP authentication page against v1 template

Rewrites docs/features/sso.mdx against the v1 docs refresh template (intro
+ tier callout, sectioned Configuration anatomy, Frame screenshots,
AccordionGroup troubleshooting), bringing it in line with the previously
refreshed two-factor-authentication and rbac pages on this branch.

Recaptures all four screenshots from the production node signed in as
admin: sso-settings (overview with the five collapsible provider cards),
sso-settings-ldap (LDAP form expanded), sso-settings-oidc (Google form
expanded), sso-settings-custom-oidc (Custom OIDC form expanded with all
eleven fields).

Refreshes the Settings UI section to match the redesigned panel: each
provider is a collapsible card with an Active badge on the header, an
enable / disable toggle pill, and a footer with Save, Test Connection
(green check or red X next to the button), and Remove (only after a
config has been saved). Documents the static callback-URL helper that
sits below all five cards.

Clarifies that the per-OIDC claim mapping environment variables
(SSO_OIDC_*_ID_CLAIM, *_USERNAME_CLAIM, *_EMAIL_CLAIM) are accepted for
Google, GitHub, and Okta, not just Custom OIDC. The Settings UI hides
those fields on the presets because the defaults match.

Converts the troubleshooting section to an AccordionGroup with five
entries (Test Connection discovery failure, issuer validation error,
wrong username or missing email after sign-in, invalid redirect URI,
SSO buttons missing on the login page). Cross-links the operations
troubleshooting page for setup-time errors.

Tightens the LDAP TLS env var note to spell out the literal string
'false' requirement. Syncs the Combining SSO with 2FA section to use
the live toggle label 'Require 2FA on SSO sign-in'.

* docs(sso): drop the Community-tier Custom OIDC workaround tip

The Tip walked through how a Community-tier operator could integrate
Google, GitHub, or Okta by pointing Custom OIDC at the provider's
discovery URL, bypassing the Skipper preset gate. Operator docs should
state the tier rule once and stop; they should not describe how to
circumvent it.

The tier matrix above the removed block already names which providers
are paid; the Custom OIDC row already lists "any spec-compliant OIDC
provider" as its scope. That is enough.

* docs(vulnerability-scanning): refresh page for v1 UI and corrected tier mapping

The page was last revised before the v1 visual redesign and before the
tier-mapping changes shipped in v0.81.2 (open Community access to
secret scanning, compose misconfig scanning, scan history, and scan
comparison). This refresh:

- Rewrites the tier matrix to match the shipped Community / Skipper /
  Admiral split. Secret detection, compose misconfig scanning, scan
  history, scan comparison, and misconfig acknowledgements are now
  correctly marked as Community. Scheduled fleet scans, scan policies
  with block_on_deploy, SBOM, SARIF, and Trivy auto-update stay paid.
- Drops two stale Notes that said secret detection and compose
  misconfig scanning required Skipper or Admiral. The page now states
  each tier requirement once, in plain language.
- Refreshes all six existing screenshots from the production node:
  resources-badges, scan-details-sheet, scan-history-sheet,
  scan-compare-sheet, security-settings, app-store-toggle.
- Adds a new scan-config-button screenshot showing the stack-page
  overflow menu where Scan config now lives.
- Describes the scan drawer header accurately: Re-scan + Compare + CSV
  + SARIF as top-level buttons, with SBOM as a separate button below
  the summary.
- Updates the compose misconfig flow to point at the stack overflow
  menu (not the Deploy controls).
- Converts the troubleshooting section to a single AccordionGroup per
  the v1 template, and audits each entry for legacy phrasing and the
  removed tier claims.
- Adds a TRIVY_BIN reference to the How it works section so operators
  know about the host-binary override.

* docs(cve-suppressions): refresh page for v1 UI and corrected suppression specifics

- Recapture all three screenshots from the production node signed in
  as admin under `docs/images/cve-suppressions/` (`settings-panel`,
  `create-dialog`, `suppressed-row`). The previous file referenced
  three image paths that did not exist in the repo.
- Align prose with the actual UI labels:
  - Dialog kicker `SUPPRESSIONS . NEW`, title `New suppression`.
  - Field labels match the form: `CVE or advisory ID`, `Package
    (optional)`, `Image pattern (optional)`, `Reason`, `Expires in
    (days, optional)`.
  - Remove confirmation reads `Remove suppression` with kicker
    `SUPPRESSIONS . REMOVE . IRREVERSIBLE`.
- Factual corrections:
  - Fleet sync truncation cap is 5,000 rows (not 10,000).
  - State the admin-role requirement once in the lead Note.
  - Drop references to a `Fleet . Sync status` page and a `Reanchor`
    button; neither exists in the UI. The reanchor flow is an admin
    API call and is documented in /features/fleet-sync.
  - Sharpen the specificity scoring section (package + image scores
    3, package only 2, image only 1, neither 0) so the order matches
    the read-time filter logic.
  - Note that the image-pattern glob is case-sensitive.
- New coverage:
  - Suppressing directly from a scan result, including which fields
    are read-only in that inline flow and when to fall back to
    Settings to broaden scope.
  - The `replicated` and `expired` row badges in the panel.
  - Hovering the package column on a suppressed row to surface the
    Reason.
  - Two distinct read-only modes: viewing a remote node from the hub
    (panel hidden, banner shown) versus signing into a replica
    instance (panel visible, read-only).
  - SARIF export carries suppressions through as
    `kind: external, status: accepted`, cross-linked to the
    Vulnerability Scanning page.
- Convert troubleshooting to AccordionGroup with six entries; update
  the truncation entry to reflect the 5,000-row cap.

* docs(private-registries): refresh page for v1 UI and fleet-wide credential model

Rewrites the page against the v1 docs template (Note tier gate, opening Frame,
sectioned anatomy, AccordionGroup troubleshooting) and replaces every
screenshot with a fresh capture taken against the current product.

Corrects several factual claims that no longer matched the current code:

- Registries are stored once on the control instance and applied fleet-wide,
  not configured per node. The old Multi-node behavior section and the
  matching troubleshooting entry described a per-node model that the product
  no longer has.
- The Registries section is hidden on remote nodes (global scope) and on
  Sencho versions that do not surface the feature. New troubleshooting
  entries explain both visibility states.
- The feature is admin-only on Admiral. Non-admin operators do not see the
  section even on Admiral; previous copy implied any Admiral license user
  could manage credentials.
- Registry endpoints are not reachable from API tokens; only an admin
  browser session can manage credentials. The Security section now states
  this without naming internal route paths.

Documents UI behavior the previous page omitted: the inline form (not modal),
the four type-specific form variants, the Docker Hub read-only URL field, the
destructive delete confirmation with its stack-pull warning, the masthead
REGISTRIES count, and the empty-state callout copy.

Screenshots replaced:
- registries-overview.png: section with one configured GHCR card and the
  masthead stat at one.
- registries-empty.png: empty state with the Add registry button and callout.
- registries-add-form.png: inline form with the Docker Hub default and the
  read-only URL field.
- registries-ecr-form.png: form switched to ECR, showing the AWS Region
  field and the relabelled AWS credential inputs.
- registries-card-detail.png: card close-up with the three action icons and
  the metadata row.
- registries-delete-confirm.png: destructive ConfirmModal with the kicker,
  title, and stack-pull warning body.
- registries-with-entry.png removed (superseded by registries-overview.png
  and registries-card-detail.png).

* docs(auto-update): refresh readiness page for v1 redesign

Bring the Auto-Update Readiness doc in line with the shipped UI:

- Replace the hero screenshot with a fresh capture of the redesigned
  board (italic-display hero, brand-cyan accent, per-node groups with
  local/remote pills, dashed-border changelog separator).
- Rewrite the card-anatomy list. Drop the rollback-target bullet (the
  field exists in the backend payload but is not rendered). Add the
  "Rebuild available" inline label and the primary-image / multi-service
  count line.
- Rewrite the risk-tags table as a risk-badges table using the actual
  badge labels and colors emitted by the UI (Safe / Review / Blocked
  with the corresponding icons; Digest rebuild for non-semver tags).
- Add an Empty state section and document the per-node group header.
- Tighten the hero subtitle paragraph to match the actual UI string
  (only major-bump count is surfaced separately; preview failures are
  not).
- Fix workflow step 4: major-bump apply path is the stack lifecycle
  Update action, not the Schedules editor (a scheduled task hits the
  same block).
- Add the 2-minute manual-refresh cooldown to the Recheck workflow.
- Remove the broken cross-link to the non-existent
  /features/image-update-detection page and inline the 6-hour cadence
  fact from ImageUpdateService.INTERVAL_MS.
- Convert troubleshooting to AccordionGroup format per the troubleshoot
  ing convention used on /features/deploy-progress.
- Sync the Auto-Update entry in /features/overview.mdx to the new
  badge labels and the corrected hero-counter description.

* docs(auto-update): fix Auto-Update entry point in Workflow step 1

Workflow step 1 said "Open the Auto-Update view from the sidebar." The
Auto-Update view is opened from the top nav strip (alongside Home,
Fleet, Resources, App Store, Logs, Schedules, Console, Audit). The
sidebar carries the stack list and the per-stack right-click / kebab
context menu that toggles auto-updates on or off; it does not house
the Auto-Update top-level view.

* docs(auto-update): trim enforcement detail from per-stack control note

State the tier requirement once and stop, per Directive 27. The
"The toggle does not appear on Community" sentence enumerates the
enforcement effect of the gate, which the source already reflects;
operator docs do not need to narrate it.

* docs(auto-heal): refresh page for v1 UI and policy hardening

Rewrite Auto-Heal Policies docs against the current Stack Monitor
sheet: corrects the Max restarts / hr field label, documents the
per-policy enable toggle, the consecutive-failures pill, the full
Recent activity action set (including Docker unavailable), the 30s
evaluation cadence, multi-node behavior, notification dispatches,
and the dashboard Configuration status counter.

Replaces the broken /images/auto-heal-policies/policy-sheet.png
reference with three fresh screenshots captured against a live
node: the sheet on the Auto-heal tab, a single policy row, and
the expanded Recent activity panel.

* docs(webhooks): refresh page for v1 UI, correct tier and add Git source sync

- Fix tier note: gate is Skipper or Admiral, management is admin-only.
- Update Settings path to Settings -> Alerts -> Webhooks; document the
  read-only Node field and the green secret-reveal callout.
- Add the missing Git source sync action and the git-pull override value.
- Refresh the configured-webhooks card description: action/stack/node
  badges, On/Off toggle, copy URL, and the Recent executions disclosure.
- Tighten the trigger section with a constant-time signature check note
  and a status/body/meaning response table.
- Add an Accordion troubleshooting block covering common signature
  failures, the 404 case, no-op actions on 202, and git-pull prereqs.
- Re-capture all three screenshots from the v1 UI.

* docs(webhooks): wrap troubleshooting accordions in AccordionGroup

* docs(sidebar): refresh page for v1 redesign with filter chips, bulk mode, row anatomy, and troubleshooting

Rewrites the Stack Sidebar page against the live v1 sidebar and the v1
docs refresh template (Frame screenshots, Note tier callouts,
AccordionGroup troubleshooting). Recaptures all four existing
screenshots and adds three new captures: filter chips, row anatomy,
and bulk mode.

Adds coverage for features the previous page omitted entirely: the
ALL / UP / DOWN / UPDATES filter chips with their counts cap and
collapse toggle; bulk mode (B key, sticky toolbar with Start / Stop /
Restart, and Update gated on Skipper or Admiral); stack-row anatomy
(status pill, label dots with +N overflow, image-update dot vs Git
source icon priority, hover kebab); the Auto-update toggle, Schedule
task, and Open App entries in the context menu; the B shortcut for
bulk mode.

Corrects three claims that no longer matched the code or UI:
Auto-Heal is gated on Skipper or Admiral, not universal; the global
Ctrl+K opens the command palette, not the sidebar search box; the
activity footer kicker reads LIVE / IDLE with the verbatim copy from
SidebarActivityTicker. Documents the in-menu ↗ and L › glyphs as
visual hints rather than global keybindings to match
useStackKeyboardShortcuts.ts.

* docs(sidebar): trim enforcement-effect sentence from context-menu tier note

State the Skipper / Admiral requirement once and stop, per Directive 27.
The "They do not appear in the menu on Community" clause described the
enforcement effect alongside the gate, which the directive bans in
operator-facing docs.

* docs(host-console): refresh page for v1 UI and clarify shell metadata

Rewrite the Host Console page to match the current Cockpit layout
(masthead + terminal well + chip strip), replace the legacy PowerShell
screenshot with a fresh bash capture, and document the masthead tone
states, kicker, metadata pills, and session/heartbeat behavior. Trim
the security section to state the tier and role rule once.

* docs(licensing): refresh page for v1 UI, corrected pricing, and trial flow

Rewrites the Licensing & Billing page to match the redesigned v1
Settings layout. The previous draft still described the legacy
Settings Hub: in-app "Upgrade your plan" Skipper/Admiral cards,
"Start monthly trial" / "Start annual trial" buttons, the
"Have a license key?" field, "Manage Subscription" with a capital S,
"Deactivate License" as the button label, and the license-active.png
asset rendering the literal "Sencho Pro" string in the card title.
None of that exists in the current product.

- Refreshes the Plans table to the live pricing on sencho.io/pricing
  and adds an Enterprise mention with the floor price ($3,500/year).
  Skipper now $11.99 annual / $14.99 monthly / $449 lifetime, Admiral
  now $69.99 annual / $89.99 monthly / $2,499 lifetime.
- Rebuilds the Feature breakdown from a code-level audit of every
  requirePaid, requireAdmiral, requireScheduledTaskTier, and
  requireTierForSsoProvider call site in backend/src/routes, not
  from the marketing page. Notable code-grounded items: CVE
  suppressions on Community (no requirePaid guard), manual fleet
  snapshots on Community (scheduled snapshots on Skipper),
  Sencho Mesh under Admiral (entire mesh.ts router is requireAdmiral),
  and scheduled-task tiering names update/scan/snapshot as the
  Skipper subset with everything else under Admiral.
- Rewrites the Free trial flow end to end. The previous steps told
  operators to click in-app "Start monthly trial" or "Start annual
  trial" buttons; no such buttons exist. The new flow starts on
  sencho.io/pricing, switches to the Annual or Monthly tab, clicks
  "Start 14-day trial" on the Admiral card, completes the Lemon
  Squeezy checkout (card-required, no charge before day 14), and
  pastes the issued key into Settings -> License -> License key.
- Adds a new "The Plan section" anatomy block describing the masthead
  SCOPE / PLAN / DURATION (or RENEWS, TRIAL, STATUS) stat pills and
  the Plan card fields (Customer, Product, masked License key, status
  helper).
- Adds a new "License states" reference table covering
  Community / Trial / Active subscription / Active lifetime /
  Expired / Disabled, what each surface renders, and which of the
  Plan / Activate / Pricing sections is visible in each state.
- Corrects every UI label that drifted: section heading is Activate,
  field label is License key (not "Have a license key?"), buttons are
  Manage subscription (lowercase s) and Deactivate (not "Deactivate
  License"), and the action-row hint reads "Lemon Squeezy manages
  billing".
- Documents the redesigned profile dropdown: identity header with
  initials chip, role badge, and tier badge, then Settings,
  conditional Billing, Documentation, Feedback, an Appearance
  segmented control, and Log Out. Billing only appears when the
  license is an active non-lifetime subscription.
- Replaces all four screenshots under docs/images/licensing/:
  license-admiral-active.png (production Admiral lifetime view),
  profile-menu.png (redesigned popover), and two new captures for
  the Community-tier surfaces (license-activate-section.png,
  license-community.png). Removes the stale license-active.png
  (legacy "Sencho Pro" card) and profile-billing.png (legacy
  dropdown).

* docs(settings-reference): refresh page for v1 UI with new sections and masthead

Rewrites docs/reference/settings.mdx against the current Settings Hub so a reader
encounters an accurate map of every section. Adds the previously missing **Cloud
Backup** and **Security** sections, restructures **System Limits** into Host
thresholds and Docker hygiene subsections (GiB units, "Global crash capture"
toggle), fixes the Account password minimum to 8 chars and documents the
two-factor subsection, refreshes License/Routing/Webhooks/App Store with the
field labels actually rendered today, and documents the masthead pills
(SCOPE/NODE, EDITED, plus the per-section stats like 2FA, PLAN, CHANNELS, ROUTES,
WEBHOOKS, LABELS, TRIVY, POLICIES, PROVIDER, USED, SNAPSHOTS, DEV MODE).

Replaces five existing screenshots that predated the v1 redesign and adds five
new captures: Account with the 2FA card, License panel, System Limits with both
subsections, Security with the Trivy installer, and Cloud Backup with Sencho
Cloud Backup provisioned. All shots taken against the production node.

* docs(licensing): drop billing-provider name from operator-facing copy

The previous draft named the third-party billing provider in nine
places (checkout, receipt email, error toast verbatim, Customer /
Product field descriptions, the action-row hint, the billing portal,
and the validation API). Operator docs don't need to advertise which
vendor sits behind the checkout, billing portal, and validation
calls. Rewrite each instance to describe what the operator sees and
does without naming the upstream service.

* docs(node-compatibility): refresh page for v1 UI with lock card visuals and current capability list

- Replaces the legacy "dim + blur + pill overlay" description with the
  current CapabilityGate behavior: a centered lock card with an Unplug
  icon, title "<feature> is not available on this node", and a body line
  that names the node and its running version.
- Corrects the tier-interaction section: on the wrong tier the entry
  point is hidden entirely, so the lock card only appears for users who
  already cleared the license gate.
- Documents the public /api/meta endpoint, the 5-minute success cache,
  the 30-second failure cache, and the lazy-fetch behavior visible in
  the switcher (the version pill appears once a node has been visited).
- Refreshes the capability table against the current CapabilityRegistry
  list, adding container-exec and vulnerability-scanning, with a note
  that vulnerability-scanning is only advertised when Trivy is installed.
- Adds three production screenshots captured on the live fleet:
  switcher popover with mixed-version pills (one node on v0.76.9, rest
  on v0.81.11), a real lock card on an older pilot agent, and the
  Connection Details panel from Settings · Nodes.

* docs(security): refresh security architecture page for v1 UI

Add Fleet Secrets and Webhook signatures cards plus tier-matrix rows for
shipped-but-undocumented features. Rename SSO presets from "one-click" to
"preset providers" (presets still require OAuth-app provisioning on the
upstream IdP). Update settings paths to the v1 middle-dot convention:
Settings · Users, Settings · Account, Settings · Developer · Data retention.

Extend the encryption-at-rest list with registry credentials and Fleet
Secrets bundle payloads (both sealed with the same AES-256-GCM data key)
and clarify the password section with bcrypt cost factor 10.

Add a Webhook signature authentication subsection covering the per-webhook
HMAC-SHA256 secret, one-shot display, masked preview thereafter, and
constant-time comparison on inbound triggers.

Replace the API Tokens screenshot with a fresh capture against the v1
Settings · Identity · API Tokens panel.

* docs(security-advisories): retire reference page

The reference/security-advisories page does not survive the v1 docs
refresh:

- Misuses the term "Security Advisories", which industry-wide refers to
  published notices for confirmed product CVEs (ID, severity, affected
  versions, fix version, remediation). The retired page was a narrative
  changelog of internal hardening work between v0.19 and v0.25.2.
- The narrative is also frozen at v0.25.2 (April 2026) while current
  release is v0.81.11. Refreshing it would require backfilling ~56
  release entries' worth of hardening copy.
- The framing is uniformly "improved from prior behavior" (minimum 8
  characters up from 6, 1-year token expiry previously without expiry,
  CORS previously allowed all origins, users should upgrade promptly).
  Sencho has not shipped publicly; there are no users to address as
  upgraders.

All operationally relevant content already lives elsewhere: the
security architecture page covers the current posture, verifying-images
covers the supply-chain attestations, cve-suppressions covers operator
acknowledgment, vulnerability-scanning covers the in-app scanner, and
contact + the security architecture page both surface the disclosure
path. Published Sencho-product advisories, when any exist, will appear
on the GitHub Security tab, which is already linked from those pages.

Inbound-link audit returned a single hit on the nav entry itself; no
other doc, README, or operator artifact deep-links the slug.

* docs: rewrite Pilot Agent page with deep architecture and operations reference

Reframes docs/features/pilot-agent.mdx as the architecture-and-operations
companion to the operator walkthrough in Multi-Node Management. Adds a
mental model section, an explicit security and trust model, a full agent
env-var reference, an honest limitations list, and a 5-item FAQ. Verifies
every constant and label against the current backend source. Refreshes
four production screenshots (admin login, scrubbed) and resolves the
previously-broken /images/pilot-agent/enrollment-dialog.png reference.

Adjacent edits keep the cross-linking coherent:
- multi-node.mdx adds a one-line forward link to the rewritten page
- security.mdx adds a Pilot Agent tunnel credentials subsection

* docs(fleet-federation): deep rewrite with production screenshots

Rewrites the Fleet Federation page against the v1 docs refresh template
following the recent fleet-view, pilot-agent, and multi-node refreshes.
Doubles the page length (92 to 204 lines) while keeping the cut-line v1
MVP scope: operator-driven placement controls (cordon + pin) for
Blueprints, no expansion into mesh/sync/pilot territory.

What changed:

- Adds four production-captured screenshots under docs/images/fleet-federation/:
  the Federation tab with a cordoned node populated, the node-card kebab
  menu showing the Cordon node entry, the cordon confirmation dialog
  with a reason filled in, and a node card displaying the Cordoned pill.
- Expands the page to eleven sections: opening summary, philosophy
  (kept), key capabilities, prerequisites, step-by-step usage with
  embedded screenshots, behaviour and lifecycle table, security and
  audit, limitations and non-goals (expanded), practical workflows (new:
  OS patching, host-to-host migration, gateway pinning), troubleshooting
  (eight accordions, up from five), and a Where Federation fits
  cross-link table.
- Documents the exact production UI strings observed: the cordon
  dialog description, the uncordon confirmation copy, the reason field
  cap (256 chars), and the audit log action names (node.cordon,
  node.uncordon, blueprint.pin).
- Documents the audit visibility surface so operators know how to
  filter the Audit view for cordon and pin history.
- Adds eight cross-links to sibling pages (Fleet View, Multi-Node,
  Pilot Agent, Mesh, Fleet Actions, Fleet Sync, Blueprints, Licensing)
  with one-line scope contrasts so newcomers can place Federation in
  the broader fleet picture.
- Tightens lifecycle table to operator-relevant terms (no DB column
  names) and audit section to operator-facing wording (no middleware
  names), keeping the page operator-focused rather than
  implementation-focused.

Validation:

- Captured screenshots against the production node logged in as admin,
  using Playwright MCP. Cordoned and pinned actions reverted; audit log
  confirmed the matched cordon/uncordon pair.
- Verified every cross-link target exists in the v1-refresh worktree
  (/features/fleet-view, /features/multi-node, /features/pilot-agent,
  /features/sencho-mesh, /features/fleet-actions, /features/fleet-sync,
  /features/blueprint-model, /features/licensing).
- Compliance: no em dashes, no PII, no "previously"/"used to" framing,
  no fence-spec language, tier rule stated once in plain language.

* docs(fleet-federation): drop fence-spec phrasing in the open-core context

Sencho is open-core: anyone can clone the repo and read the tier gate.
Operator docs that name exactly where the UI gate sits ("hidden at the
Community and Skipper tiers", "lower-tier users do not see the toggle",
"only the Federation tab is gated") work as a dig-target for a
tech-savvy reader and undercut the open-core posture. Directive 27
already bans enforcement-chain spelling; the open-core threat model
makes the same phrasings risky even when they describe UI surfaces
rather than route guards.

Removes three instances of the pattern on this page:

- Top Note callout: drops "The tab is hidden at the Community and
  Skipper tiers." Keeps the one-line requirement: "Federation is an
  Admiral feature. Cordon and pin actions require an admin user role."
- Security and audit section: drops the sentence enumerating which UI
  affordances are hidden from which tiers. Keeps the customer-visible
  behavior (the Cordoned pill stays visible at every tier as a
  read-only signal).
- Troubleshooting "Federation tab is not visible" accordion: rewrites
  to lead with the requirement and the role check, drops the
  "Federation is hidden by design" and "only the toggle and the
  Federation tab are gated" phrasings.

Other claims on the page unchanged; rule is still stated once in plain
language at the top of the page.

* docs(fleet-sync): deep rewrite with production screenshots

Replace fleet-sync.mdx with a verified end-to-end reference. The previous
page named two replicated resources but the code syncs three, described a
sync-status panel and a fleet-vs-node scope picker that do not exist in
the shipped UI, and was missing prerequisites and several edge cases.

Highlights of the rewrite:

- Names all three replicated resources (scan policies, CVE suppressions,
  misconfig acknowledgements) and treats them uniformly.
- Drops the sync-status-panel and node-scope-picker UI claims; both move
  to the Limitations section as honest caveats.
- Adds prerequisites covering the paid-tier requirement on the control,
  admin-role requirement, proxy-mode remotes, and reachability.
- Expands lifecycle coverage: per-node serialised pushes, add-node
  backfill, monotonic pushedAt, per-resource watermarks, identity-drift
  notifications, the 5000-row truncation cap, stale-target warnings,
  audit-log entries on the replica.
- New "Where Fleet Sync fits" closing table cross-linking to Fleet View,
  Multi-Node Management, Pilot Agent, Vulnerability Scanning, CVE
  Suppressions, Fleet Federation, Fleet Actions, and Licensing.
- Two fresh production screenshots: control Security panel and the
  "Scanner is per-node" callout shown when proxying to a remote.

* docs(fleet-actions): deep rewrite with production screenshots

Three cards are documented end to end: Stop fleet by label, Bulk label
assign, and Prune Docker resources fleet-wide. Adds the execution-path
distinction (control-orchestrated fan-out vs single-node proxy), per-card
behaviour and partial-failure semantics, prerequisites, limitations,
practical workflows, an Accordion troubleshooting section, and a Where
Fleet Actions fits comparison table linking the surrounding Fleet view
features.

Corrects the prior page's tab-neighborhood claim, confirm-dialog wording,
autocomplete-vs-request scope, and missing batch ceiling. Replaces the
ten-day-old single screenshot with five fresh production captures under
docs/images/fleet-actions/.

* docs(fleet-secrets): deep rewrite with production screenshots

Full rewrite of /features/fleet-secrets matching the fleet-actions
structure. Replaces the sparse v1 page (no Frames, inline Q&A) with a
gold-standard layout: opening Frame, single Note for the tier gate,
'What it covers' table, mental model, prerequisites, create + edit +
versions + push (Target / Preview / Results) sections each with a
production Frame, Import from stack section, behaviour and lifecycle
table, audit-trail mapping with the six exact audit strings,
limitations and non-goals, practical workflows, AccordionGroup
troubleshooting, and a Where-it-fits cross-link table.

Adds six fresh production screenshots under
docs/images/fleet-secrets/ : overview, create, versions, target,
preview, and results.

Documents the Import-from-stack flow (depends on the bundle editor's
new Import action) and uses the post-rename 'Send' wording on the
bundle-row action (depends on the aria-label fix).

Corrects three factual drifts vs the code: env-key regex described as
'letter or underscore, then letters/digits/underscores; case-
sensitive' to match ^[A-Za-z_][A-Za-z0-9_]*$ ; documents only the
'ok' and 'failed' status pills (the 'skipped' enum value is unused);
replaces the bogus 'stack not found' troubleshooting entry with the
real 'env file not declared' cause.

Drops the fence-spec phrasing 'The tab is hidden on Community.' per
Directive 31; the tier requirement is now stated once in plain
language.

* docs(sencho-mesh): deep rewrite with mental model, lifecycle, security, screenshots

Replace the feature-reference page with a deep product + technical guide.

Adds:
- Opening hook framing audience and problem (cross-node service-to-service
  without a separate VPN or service-mesh sidecar).
- Mental model: three moving parts (sencho_mesh bridge, alias registry,
  cross-node transport) with direction-of-flow described in prose.
- Key capabilities, prerequisites, step-by-step usage with inline screenshots.
- Full lifecycle section covering opt-in, opt-out, sticky stack-stopped state,
  peer reconnect, and the proxy-mode bridge with its real default (persistent,
  env-override for idle).
- Security and trust boundaries split into authentication, inbound exposure,
  encryption, audit, and app-layer caveats.
- Limitations and non-goals: one-alias-per-port, port 1852 reserved,
  central-relay for remote-to-remote, shared 1024-stream pool with the Pilot
  tunnel, no L7, host-network unsupported, in-memory activity log.
- Three concrete workflow examples and a complete troubleshooting accordion
  (every data-plane reason, every probe stage, every unreachable cause) plus
  a Common questions FAQ.
- Where Mesh fits CardGroup linking Pilot Agent, Multi-Node, Federation,
  Licensing.

Corrections vs prior text:
- Tab is labelled Traffic in the UI (not Routing); all navigation references
  updated.
- Proxy-mode bridge default is no idle close (env-overridable to opt into idle
  teardown); prior 5-minute-teardown claim removed.
- Audit trail scope tightened: only opt-in / opt-out write durable rows;
  tunnel-state and probe events live in the in-memory activity log.

Adds seven production screenshots under docs/images/sencho-mesh covering
Table view, opt-in sheet, graph (Tunnels and Aliases edge modes), Diagnostics,
activity log, and per-stack topology.

* docs(blueprints): add missing detail-state-review screenshot

Captures the Blueprint detail sheet with a deployment row in the
"Awaiting confirmation" status (stateful first-deploy gate), to fix the
broken image referenced at blueprint-model.mdx:132. mint broken-links
now reports zero broken references.

* docs(blueprints): deep rewrite with mental model, lifecycle, security, prerequisites

Restructures the Blueprints page against the v1-refresh template used by the
recently-refreshed mesh, secrets, and atomic-deployments pages. Adds a mental
model, prerequisites table, lifecycle and status-transition map, security and
trust boundaries section, practical workflows, common questions accordion,
and a Where Blueprints fits CardGroup. Removes the internal-style rollout
and watch-plan section. Replaces all nine production screenshots with fresh
captures against the production node signed in as admin, and adds two new
captures (federation pin policy table, stateless eviction dialog). Rewrites
the tier-gate Note to drop the fence-spec phrasing that violated Directive
31. Every retained claim is anchored to current backend or frontend code.

* docs(pilot-agent): recapture enrollment dialog with compose payload

Replaces the pre-0.84 docker-run capture with the current dialog (Compose
file, two-step instructions, "Copy compose file" button) and refines the
alt text to describe the captured content. URL and token redacted to
placeholder values during capture.
2026-05-20 08:43:18 -04:00

356 lines
28 KiB
Plaintext
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
title: Pilot Agent
description: Connect a remote Sencho node to your control instance through a single outbound WebSocket tunnel. No inbound ports, no TLS certificates, no public URL on the remote host.
---
Pilot Agent is one of Sencho's two remote-node modes. A small agent container runs on the remote host, dials your control instance over a single outbound WebSocket, and holds that connection open. Every request the control instance sends to that node rides through the same tunnel, whether it's HTTP, WebSocket, or Sencho Mesh TCP. The remote host never opens an inbound port and never needs a TLS certificate of its own.
This page is the architecture-and-operations reference for Pilot Agent. For the step-by-step UI walkthrough that adds a remote node, see [Multi-Node Management](/features/multi-node).
<Card title="Sencho Mesh" icon="link" href="/features/sencho-mesh">
Once a node is enrolled, you can wire stacks across nodes by hostname using Sencho Mesh. Mesh traffic rides on the same pilot tunnel.
</Card>
## How Pilot Agent fits Sencho
Sencho splits responsibilities between a **control instance** (the browser-facing Sencho your operators log into) and **nodes** (Docker hosts you manage from that control instance). The local node is always the control instance's own Docker socket. Remote nodes are other Sencho installations that the control instance manages on your behalf.
There are two remote modes, chosen per node when you register it:
<Frame>
<img src="/images/pilot-agent/01-add-node-pilot.png" alt="Add remote node modal with Type set to Remote and the Mode dropdown open, showing the Pilot Agent option above the Distributed API Proxy option." />
</Frame>
- **Pilot Agent** (this page). The remote dials the control instance. Outbound HTTPS from the remote is the only network requirement.
- **Distributed API Proxy** ([documented under Multi-Node Management](/features/multi-node)). The control instance dials the remote. The remote must expose a reachable URL.
Both modes are first-class. They can coexist on the same control instance, one per node. Pilot Agent is part of Sencho's Community-tier core surface; there is no license gate on using it.
## When to choose Pilot Agent
Pilot Agent is the right choice when the remote host:
- Sits behind NAT or a residential router with no port forwarding.
- Lives on a corporate network that blocks inbound connections.
- Has a rotating cloud IP, a CG-NAT'd mobile uplink, or roams between networks.
- Has only outbound internet access (a typical homelab or office workstation).
- Would otherwise need a reverse proxy, dynamic DNS, or a self-signed TLS certificate purely to be reachable.
Choose **Distributed API Proxy** instead when the remote already has a stable, reachable URL (a VPS with a public IP, a LAN server with a static address, or a Tailscale node you have already terminated TLS on). The [Multi-Node Management](/features/multi-node) page compares both modes side by side.
You do not have to pick one mode for the whole fleet. Mix and match per node.
## How it works
Conceptually, the agent reverses the usual client/server direction.
1. The agent container starts on the remote host with three environment variables: a mode flag, the control instance URL, and a short-lived enrollment token.
2. It dials `wss://<control-instance>/api/pilot/tunnel` and holds the WebSocket open for as long as the container runs.
3. For every request the control instance needs to make against that node (listing containers, deploying a stack, streaming logs, opening a console, forwarding mesh traffic), frames are multiplexed over that single connection.
4. On the agent side, those frames are demultiplexed and replayed locally against the host's Docker socket and filesystem.
Inside the control instance, the tunnel terminates at a **loopback bridge**: a tiny HTTP server on `127.0.0.1:<random-port>` per active tunnel. Every other Sencho feature (the existing HTTP proxy, WebSocket forwarder, mesh dialer, license-tier propagation) treats the bridge as just another remote URL. That is why a pilot-mode node behaves identically to a proxy-mode node from the operator's point of view. Once enrolled, it shows up in the same Nodes table, the same node switcher, the same dashboard.
<Frame>
<img src="/images/pilot-agent/03-nodes-table-tunnel.png" alt="Settings · System · Nodes table showing a Local row and a Pilot Agent row. The pilot row has Mode badge 'Pilot Agent', Endpoint 'tunnel (seen 45m ago)', and Status badge 'Online'." />
</Frame>
What rides through the tunnel:
- HTTP requests (every API call and stream).
- WebSockets (live logs, host console, container exec, notifications).
- Sencho Mesh TCP streams (cross-node service-to-service traffic).
What does NOT ride through the tunnel:
- Nothing inbound. The agent opens no listening port.
- The agent serves no UI of its own. Operators always work from the control instance.
- The agent's internal `/api/health` endpoint is reachable only from the tunnel's loopback bridge, not from outside the agent container.
## Prerequisites
| Requirement | Detail |
|---|---|
| **Remote host** | Docker installed and a user that can run containers. About 1 GB free on the volume that backs `/app/data` and whatever you point `/app/compose` at. |
| **Network from remote → control instance** | Outbound TCP to the control instance's HTTPS port (whatever your reverse proxy or Sencho exposes). Nothing inbound. |
| **Network at the control instance** | The path from the remote to the control instance must allow WebSocket upgrades end-to-end. If you terminate TLS at a reverse proxy in front of Sencho, that proxy needs `Upgrade: websocket` passthrough. |
| **Operator role** | Admin on the control instance. The Settings → Nodes panel is admin-only. |
| **License tier** | None. Pilot Agent is Community-tier core surface. |
### The control instance's public URL
When the enrollment dialog generates the agent's compose file, it bakes the control instance's URL into `SENCHO_PRIMARY_URL` by reading the Host header on the admin's request. That works on a LAN, but it breaks when the pilot lives on a different network (a public cloud VPS, for example) and the admin happened to open the dialog at `http://127.0.0.1:1852` or a LAN address: the baked-in URL is then unreachable from the pilot.
Set `SENCHO_PUBLIC_URL` on the control instance to lock in a publicly-routable URL the dialog should always use:
```bash
-e SENCHO_PUBLIC_URL=https://sencho.example.com
```
Any HTTPS hostname reachable from the pilot works: a Cloudflare Tunnel, a reverse proxy, a port-forwarded home network with DDNS. The control instance validates the value (must be `http(s)://`, no loopback) and falls back to the request Host when unset.
## Enrollment and lifecycle
The end-to-end UI walkthrough for adding a Pilot Agent node (click paths, screenshots of the Add Node form, the Verify-the-tunnel step) lives in [Multi-Node Management](/features/multi-node#add-a-remote-node-pilot-agent). This section covers the underlying credential lifecycle, what happens during the connection, and how reconnects behave.
### Enrollment
When you submit the Add Node form with Mode set to Pilot Agent, the control instance:
1. Inserts the node into its registry with status `unknown` and no endpoint.
2. Mints a one-time enrollment JWT scoped to that node. The token's hash is stored on the control instance so it cannot be replayed; the token itself is returned to the operator and embedded in a generated Docker Compose file.
3. Shows the compose file in an enrollment dialog with a 15-minute countdown.
<Frame>
<img src="/images/pilot-agent/02-enrollment-dialog.png" alt="Enroll the pilot agent modal with kicker 'NODES · PILOT ENROLLMENT'. Step 1 saves a Docker Compose file as 'compose.yaml' with the env block showing SENCHO_MODE: pilot, SENCHO_PRIMARY_URL: https://sencho.example.com, and SENCHO_ENROLL_TOKEN: <short-lived token>. Step 2 shows the 'docker compose -f compose.yaml up -d' command. Footer reads 'Expires 14m from now' alongside a 'Copy compose file' button." />
</Frame>
The enrollment token is one-time and short-lived by design. If a token is intercepted or leaked, the window of risk is small and the slot is consumed on first use.
The generated compose file looks like this, with the three pilot env vars already baked in:
```yaml
name: sencho-agent
services:
agent:
image: saelix/sencho:latest
container_name: sencho-agent
restart: unless-stopped
volumes:
- /var/run/docker.sock:/var/run/docker.sock
- sencho-agent-data:/app/data
- /opt/docker/sencho:/app/compose
environment:
SENCHO_MODE: pilot
SENCHO_PRIMARY_URL: https://sencho.example.com
SENCHO_ENROLL_TOKEN: <short-lived token>
volumes:
sencho-agent-data:
```
Save it as `compose.yaml` on the remote host and bring the agent up from the same directory:
```bash
docker compose -f compose.yaml up -d
```
Deploying through Compose also lets the control instance push over-the-air updates to the agent later from the Fleet view ([Remote Updates](/features/remote-updates)), without manual intervention on the remote host. Compose-managed containers carry the labels Sencho needs to recreate them in place.
### First connect
The agent boots, reads the three env vars, and dials `wss://<control-instance>/api/pilot/tunnel` carrying the enrollment token in an `Authorization: Bearer` header.
The control instance verifies the token, marks the enrollment slot consumed, and replies with a `hello` frame followed by a control frame that carries a **long-lived tunnel JWT** (365-day expiry). The agent writes that token to its data volume at `/app/data/pilot.jwt`. The original enrollment token is now useless: the agent does not need it again, and the control instance refuses to accept it a second time.
The tunnel is now active. The Endpoint column in the Nodes table flips from `tunnel (waiting)` to `tunnel (seen Xs ago)` and the node's status badge turns Online.
### Subsequent reconnects
On every later boot, restart, or transient network drop, the agent reads `pilot.jwt` from disk and dials with that. No new operator action is needed. The persisted token is good for a year from the original enrollment.
The reconnect loop uses exponential backoff from 1 second to 60 seconds with up to 500 ms of jitter. The backoff resets only after a successful `hello` round-trip, so an agent that always fails the handshake (wrong URL, revoked token, version mismatch) cannot tight-loop and burn resources.
The control instance pings every connected agent every 30 seconds. Any stream with no activity for 10 minutes is closed and reclaimed.
### Primary restart, agent restart
- **Control instance restarts**: every agent's tunnel drops cleanly. Each agent reconnects within seconds. In-flight HTTP requests fail and the browser retries; long-lived WebSockets (logs, console) reconnect.
- **Agent restarts**: the persisted token re-authenticates without operator intervention. Same reconnect-and-recover behavior.
- **Operator deletes the node on the control instance**: the agent's existing tunnel is closed. The agent will keep trying to reconnect with its persisted token, which the control instance no longer accepts; the agent stays in a reconnect-backoff loop. To stop it, tear the agent down on the remote with `docker compose -f compose.yaml down -v`.
### Re-enrollment
If the agent container is destroyed before its first successful connect, the enrollment token expires unused, the control instance is restored from a backup with a different JWT secret, or you simply want to rotate the credential, open the node's Edit dialog and click **Regenerate enrollment token**.
<Frame>
<img src="/images/pilot-agent/04-regenerate-token.png" alt="Edit node modal for a pilot-agent node showing a Re-enroll the agent helper text and a Regenerate enrollment token button." />
</Frame>
A fresh 15-minute token is issued and the previous tunnel (if any) is closed immediately so the new agent replaces it cleanly.
## Security and trust model
### Tokens
Two JWT scopes, both signed with the control instance's `auth_jwt_secret`:
| Token | Lifetime | Where it lives | Use |
|---|---|---|---|
| **Enrollment** | 15 min, one-time | Returned to the operator; SHA-256 hash stored on the control instance | Bootstraps the first connect |
| **Tunnel** | 365 days | Agent's container volume at `/app/data/pilot.jwt` | Every reconnect after the first |
Enrollment is rate-limited to 10 requests per minute per operator (per source IP if unauthenticated) so a runaway script cannot exhaust the database with pending tokens.
### TLS
The agent dials `wss://`. Certificate validation is on by default against the system trust store. There is no flag to disable verification; that would defeat the credential model. For internal CAs, mount your bundle into the agent container and set `SENCHO_PILOT_CA_FILE` to the in-container path. See [Self-signed control-instance TLS certificates](#self-signed-control-instance-tls-certificates) below for a worked example.
### Trust boundaries
- **The control instance trusts the agent.** A connected agent's frames are believed. A compromised remote can flood frames; the per-tunnel resource limits documented below bound the blast radius.
- **The agent trusts the control instance.** The control instance proves its identity by producing a valid JWT under the secret it shares with itself. A compromised control instance can ask the agent to do anything the agent could do directly on its host, and the agent holds the Docker socket, so that is effectively root on the remote.
- **Tier-trust headers (`x-sencho-tier`, `x-sencho-variant`) are only honored for bearer tokens with `node_proxy` or `pilot_tunnel` scope.** Browser session cookies cannot spoof them.
- **The agent exposes nothing inbound.** No port. No UI. No directly reachable health endpoint.
### What rotating the JWT secret does
The tunnel JWTs are signed with the control instance's `auth_jwt_secret`. If that secret rotates (because the control instance was rebuilt from scratch, restored into a different environment, or manually rotated), every existing tunnel JWT stops verifying. The agents will reconnect, fail authentication, and back off. Re-enroll each affected node (regenerate the enrollment token, then redeploy the agent on the remote with the refreshed compose file) to issue a new tunnel JWT signed by the current secret.
## Self-signed control-instance TLS certificates
If your control instance terminates TLS with an internal CA that the agent's system trust store does not recognise, mount the CA bundle into the agent container and point `SENCHO_PILOT_CA_FILE` at it:
```yaml
name: sencho-agent
services:
agent:
image: saelix/sencho:latest
container_name: sencho-agent
restart: unless-stopped
volumes:
- /var/run/docker.sock:/var/run/docker.sock
- sencho-agent-data:/app/data
- /opt/docker/sencho:/app/compose
- /etc/ssl/internal-ca.pem:/etc/ssl/internal-ca.pem:ro
environment:
SENCHO_MODE: pilot
SENCHO_PRIMARY_URL: https://sencho.internal.example.com
SENCHO_ENROLL_TOKEN: <short-lived token>
SENCHO_PILOT_CA_FILE: /etc/ssl/internal-ca.pem
volumes:
sencho-agent-data:
```
The agent uses the bundle as the only trust anchor for the tunnel WebSocket. TLS verification stays on.
## Resource limits
Each pilot tunnel has fixed protocol-level ceilings so one misbehaving agent cannot impact the control instance or its peers.
| Limit | Value | What it caps | Why it matters |
|---|---|---|---|
| **Frame size** | 8 MB | Individual WebSocket frame, including a single HTTP request or response body chunk | A request or response body larger than 8 MB is rejected and the tunnel reconnects. Stream HTTP responses are chunked, so normal traffic stays well under this. |
| **Concurrent streams per tunnel** | 1024 | HTTP, WebSocket, and Sencho Mesh TCP streams share the same pool | New streams above the cap are rejected with 503 from the bridge and a typed error frame from the agent. A runaway script or a long-poll session that leaks streams can exhaust this; reload the affected tab or throttle the caller. |
| **Stream idle timeout** | 10 minutes | Per-stream inactivity before teardown | Idle WebSockets and forgotten HTTP streams are reclaimed automatically. |
| **System-wide tunnels** | 256, soft-warn at 128 | Concurrent pilot tunnels on a single control instance | Past the soft warning the control instance logs WARN. Past the hard cap, new tunnels are refused with WebSocket close code 1013 ("Try Again Later"); the agent backs off rather than tight-looping. |
| **Tunnel write buffer pause** | 4 MB | High-water mark for the agent-bound write queue | When the control instance's queue is over the mark, inbound HTTP request bodies are paused and resumed on drain. Backpressure rather than memory growth. |
| **Enrollment rate** | 10 per minute | Operator-issued enrollment tokens | Protects the database against a script accidentally minting tokens in a loop. |
An admin-only diagnostic endpoint, `GET /api/system/pilot-tunnels`, returns counters and a per-node breakdown of active tunnels (open stream count and `bufferedAmount` for each). Useful for triaging a single sticky tunnel inside an otherwise healthy fleet.
## Environment variables
These environment variables are read by the **agent** container at boot.
| Variable | Required? | Default | Notes |
|---|---|---|---|
| `SENCHO_MODE` | Yes | none | Must be `pilot`. Putting any other value here causes the container to start as a normal Sencho instance, not as an agent. |
| `SENCHO_PRIMARY_URL` | Yes | none | The base URL of your control instance (e.g. `https://sencho.example.com`). The agent appends `/api/pilot/tunnel` and dials `wss://`. |
| `SENCHO_ENROLL_TOKEN` | First boot only | none | The 15-minute enrollment token issued by the control instance. Ignored on subsequent boots once `pilot.jwt` is on disk. |
| `SENCHO_PILOT_CA_FILE` | Optional | unset | Absolute path inside the container to a PEM bundle. Use when your control instance's TLS chain is rooted in a private CA. |
| `DATA_DIR` | Optional | `/app/data` | Where the persisted `pilot.jwt` is stored. Override only if you are mounting a different volume layout. |
| `COMPOSE_DIR` | Optional | `/app/compose` | Root directory on the agent host where compose stack folders live. The control instance reads and writes stacks under this path. |
One variable is read on the **control instance** side, not the agent:
| Variable | Required? | Default | Notes |
|---|---|---|---|
| `SENCHO_PUBLIC_URL` | Optional | request Host | Locks in the URL the enrollment dialog bakes into `SENCHO_PRIMARY_URL`. See [The control instance's public URL](#the-control-instances-public-url) above. Must be `http(s)://`, no loopback. |
The agent does not currently expose tunables for the ping interval (30 s), the reconnect backoff (160 s), or the per-stream idle timeout (10 min). These are deliberate fixed values; if your environment requires different ones, open an issue.
## Limitations and non-goals
These are the boundaries operators should know about before designing a fleet around Pilot Agent.
- **No mode conversion.** The Edit dialog shows a Mode field for an enrolled node, but switching a node between Pilot Agent and Distributed API Proxy after enrollment leaves the credentials and connection state inconsistent. To change modes, delete the node and re-create it in the desired mode.
- **No audit log entries for enrollment lifecycle.** Node creation, enrollment regeneration, and node deletion do not write to the audit log today. This is on the roadmap.
- **`pilot.jwt` is not cleaned up on node deletion.** When you delete a node from the control instance, the agent's persisted token stays on the remote's data volume. The agent will fail to reconnect on next restart, but the file persists. If you are repurposing the host, tear the agent down with `docker compose -f compose.yaml down -v` to remove the `sencho-agent-data` volume.
- **JWT-secret rotation invalidates every tunnel.** Rebuilding the control instance from scratch or rotating `auth_jwt_secret` requires re-enrolling every agent. There is no out-of-band re-issuance flow.
- **One tunnel per node.** Splitting a node's load across multiple control instances or running multiple agent containers against the same control instance for the same node is not supported.
- **Mesh and pilot share the per-tunnel stream pool.** A node that runs heavy Sencho Mesh traffic counts those streams against the same 1024-stream cap as HTTP and WebSocket traffic.
- **The agent has no UI of its own.** All operation flows through the control instance. The agent's container logs (`docker logs sencho-agent`) are the only direct visibility into agent-side behaviour.
## Sencho Mesh on Pilot Agent
Sencho Mesh works identically across both remote modes. On a Pilot Agent node, mesh traffic rides the existing long-lived tunnel instead of opening a separate connection. Stack opt-in to the mesh is per stack per node and is not affected by the transport choice. See [Sencho Mesh](/features/sencho-mesh) for the full mesh model.
## Troubleshooting
The generic node-connectivity issues (a node showing Offline, a pilot agent stuck on `tunnel (waiting)`, 401 Unauthorized on Test Connection) are covered in the [Multi-Node Management troubleshooting section](/features/multi-node#troubleshooting). The entries below cover failure modes that are specific to Pilot Agent.
<AccordionGroup>
<Accordion title="Tunnel keeps disconnecting every ~30 seconds">
The control instance pings the agent every 30 seconds; a reconnect that lines up with the ping interval almost always means an HTTP proxy or load balancer between the agent and the control instance is closing idle WebSockets faster than the ping cadence. Raise the proxy's WebSocket idle timeout above 30 seconds (a 90-second floor is safe). If you terminate TLS at a reverse proxy, also confirm that the proxy forwards the `Upgrade: websocket` header end-to-end.
</Accordion>
<Accordion title="Tunnel rejected with WebSocket close code 1013 (Try Again Later)">
The control instance has reached the system-wide hard cap of 256 concurrent pilot tunnels. A reconnect storm or a runaway enrollment is the usual cause. Inspect the control instance's logs for the `[Pilot] Active tunnel count at soft limit` warning that fires at 128 to spot the trend, and check `GET /api/system/pilot-tunnels` (admin-only) for the per-node breakdown to identify the flapping agent. The agent backs off and retries automatically once headroom returns.
</Accordion>
<Accordion title="Loopback bridge returns 503 'pilot tunnel: stream cap reached'">
A single tunnel has hit the per-tunnel 1024-stream cap. The most common trigger is a browser session that opened many long-poll streams without closing them, or a script firing parallel API calls without bound. Reload the affected tab so its WebSocket and SSE streams reset. If the cap is being hit by automation, throttle the caller. Sencho Mesh streams share the same pool, so a runaway mesh workload can also push the count up.
</Accordion>
<Accordion title="Tunnel closes with WebSocket close code 1002 (protocol error)">
The agent sent a frame larger than the 8 MB ceiling, or the wire decoder rejected a malformed frame. Run the control instance with developer mode enabled (Settings → Developer) to surface the diagnostic decode log, then check the logs for `[PilotBridge:diag] Malformed frame from agent`. The agent reconnects automatically; persistent failures usually mean a version mismatch between the control instance and the agent image.
</Accordion>
<Accordion title="I ran the enrollment command on the wrong host">
Tear the agent down on the wrong host (`docker compose -f compose.yaml down -v` from the directory you saved the compose file in), then regenerate the enrollment token on the control instance and deploy the new compose file on the correct host.
</Accordion>
<Accordion title="HTTP 429 'Too many enrollment requests'">
The enrollment endpoint is rate-limited to 10 requests per minute per operator (or per IP when unauthenticated). A script accidentally minting tokens in a loop trips this. Wait 60 seconds and retry. To bulk-enroll many nodes, space the requests out.
</Accordion>
<Accordion title="Control instance was restored from backup and the agent will not reconnect">
The persisted tunnel credential is signed with the control instance's `auth_jwt_secret`. If that secret was not part of the backup (or has been rotated for any other reason), existing tunnels stop verifying. Regenerate enrollment for each affected node from Settings → Nodes and restart the agent containers so they consume the fresh tokens. There is no global re-issuance command.
</Accordion>
<Accordion title="I deleted the node on the control instance but the agent keeps trying to reconnect">
Deleting the node removes the routing entry on the control instance but does not touch the remote. The agent still holds `/app/data/pilot.jwt` and will keep dialing. Tear the agent down on the remote (`docker compose -f compose.yaml down -v` from the directory holding the compose file) so the `sencho-agent-data` named volume that stores the persisted token is removed.
</Accordion>
<Accordion title="Stacks tab on a pilot node shows nothing or fails to list">
The agent's compose directory is missing or not writable. Verify the host path you mounted at `/app/compose` exists, is owned by a user the agent container can write as, and matches the Compose Directory configured for the node in Settings → Nodes. If the host path has moved, edit the node and update the Compose Directory field.
</Accordion>
<Accordion title="I changed the Mode on a pilot node in Edit and now it is broken">
The Edit dialog shows the Mode field, but switching from Pilot Agent to Distributed API Proxy (or back) after enrollment is not a clean flow; the persisted credentials and the new mode end up inconsistent. Delete the node, re-create it in the mode you want, and re-enroll or re-paste the API token.
</Accordion>
</AccordionGroup>
## Common questions
<AccordionGroup>
<Accordion title="Do I need port forwarding or a public IP on the remote?">
No. The agent dials outbound; the remote needs no inbound port, no public IP, no DNS entry, and no TLS certificate of its own.
</Accordion>
<Accordion title="Is Pilot Agent the same as a VPN or Tailscale?">
No. A VPN gives every host on the network a routable address for arbitrary peer-to-peer traffic. Pilot Agent is a single-purpose tunnel between one agent and one control instance, carrying only Sencho's own protocol. The two are complementary; you can run Sencho over a VPN (using Distributed API Proxy mode against the VPN address) if you prefer.
</Accordion>
<Accordion title="Does my data go through Sencho's servers?">
No. The tunnel is a direct WebSocket between your remote host and your control instance. There is no Sencho-operated relay.
</Accordion>
<Accordion title="Can I run multiple agents on the same host?">
Yes. Each agent needs its own container name and its own data volume so the persisted `pilot.jwt` files do not collide. Enroll each one against a distinct node entry on the control instance.
</Accordion>
<Accordion title="Does the control instance need a public domain?">
No. The agent only needs to reach the control instance over whatever path your network provides: LAN, VPC, VPN, public internet, or a private tunnel. Set `SENCHO_PRIMARY_URL` to whatever URL works from the agent's vantage point.
</Accordion>
</AccordionGroup>
## Related
- [Multi-Node Management](/features/multi-node): the operator walkthrough for adding remote nodes in either mode, the Nodes table reference, and the cross-mode comparison.
- [Sencho Mesh](/features/sencho-mesh): cross-node networking that rides on the pilot tunnel.
- [Fleet view](/features/fleet-view): fleet-wide aggregation and node health across both modes.
- [Security architecture](/security): credential model and trust posture across the rest of Sencho.