feat(settings): add desktop server port controls

packages/server/src/config/schema.ts

@@ -26,6 +26,8 @@ const PreferencesSchema = z
   showUsageMetrics: z.boolean().default(true),
   autoCleanupBlankSessions: z.boolean().default(true),
   listeningMode: z.enum(["local", "all"]).default("local"),
+  httpPort: z.number().int().min(1).max(65535).optional(),
+  httpsPort: z.number().int().min(1).max(65535).optional(),
   logLevel: z.enum(["DEBUG", "INFO", "WARN", "ERROR"]).default("DEBUG"),
 
   // OS notifications

packages/server/src/settings/migrate.ts

@@ -107,6 +107,14 @@ function mapLegacyToOwnerDocs(legacyConfig: unknown, legacyState: unknown): { co
     if (typeof listeningMode === "string") {
       serverConfig.listeningMode = listeningMode
     }
+    const httpPort = preferences.httpPort
+    if (typeof httpPort === "number") {
+      serverConfig.httpPort = httpPort
+    }
+    const httpsPort = preferences.httpsPort
+    if (typeof httpsPort === "number") {
+      serverConfig.httpsPort = httpsPort
+    }
     const logLevel = preferences.logLevel
     if (typeof logLevel === "string") {
       serverConfig.logLevel = logLevel
@@ -139,6 +147,8 @@ function mapLegacyToOwnerDocs(legacyConfig: unknown, legacyState: unknown): { co
     const moved = new Set([
       "environmentVariables",
       "listeningMode",
+      "httpPort",
+      "httpsPort",
       "logLevel",
       "lastUsedBinary",
       "modelRecents",

packages/server/src/settings/service.ts

@@ -14,6 +14,19 @@ const CanonicalLogLevelSchema = z.preprocess(
   z.enum(["DEBUG", "INFO", "WARN", "ERROR"]),
 )
 
+const CanonicalPortSchema = z.preprocess(
+  (value) => {
+    if (typeof value === "string") {
+      const trimmed = value.trim()
+      if (!trimmed) return undefined
+      const parsed = Number(trimmed)
+      return Number.isFinite(parsed) ? parsed : value
+    }
+    return value
+  },
+  z.number().int().min(1).max(65535),
+)
+
 function isPlainObject(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value)
 }
@@ -33,6 +46,14 @@ function normalizeServerConfigOwner(value: SettingsDoc): SettingsDoc {
   }
 
   const next: SettingsDoc = { ...value }
+  for (const key of ["httpPort", "httpsPort"] as const) {
+    const parsedPort = CanonicalPortSchema.safeParse(next[key])
+    if (parsedPort.success) {
+      next[key] = parsedPort.data
+    } else if (next[key] !== undefined) {
+      delete next[key]
+    }
+  }
   const parsedLogLevel = CanonicalLogLevelSchema.safeParse(next.logLevel)
   if (parsedLogLevel.success) {
     next.logLevel = parsedLogLevel.data

packages/ui/src/components/settings/remote-access-settings-section.tsx

@@ -1,18 +1,37 @@
 import { Switch } from "@kobalte/core/switch"
-import { For, Show, createMemo, createSignal, type Component, onMount } from "solid-js"
+import { For, Show, createEffect, createMemo, createSignal, type Component, onMount } from "solid-js"
 import { toDataURL } from "qrcode"
 import { ChevronDown, ExternalLink, Link2, Loader2, RefreshCw, Shield, Wifi } from "lucide-solid"
 import type { NetworkAddress, ServerMeta } from "../../../../server/src/api-types"
 import { serverApi } from "../../lib/api-client"
 import { restartCli } from "../../lib/native/cli"
-import { serverSettings, setListeningMode } from "../../stores/preferences"
+import { serverSettings, setListeningMode, setServerPorts } from "../../stores/preferences"
 import { showConfirmDialog } from "../../stores/alerts"
 import { getLogger } from "../../lib/logger"
 import { useI18n } from "../../lib/i18n"
 import { splitRemoteAddresses, type RemoteAddressGroups } from "../../lib/remote-access-addresses"
 
 const log = getLogger("actions")
 
+function formatPortValue(port?: number): string {
+  return port === undefined ? "" : String(port)
+}
+
+function parsePortInput(input: string, invalidMessage: string, rangeMessage: string): { value: number | null; error: string | null } {
+  const trimmed = input.trim()
+  if (!trimmed) {
+    return { value: null, error: null }
+  }
+  if (!/^\d+$/.test(trimmed)) {
+    return { value: null, error: invalidMessage }
+  }
+  const value = Number(trimmed)
+  if (!Number.isInteger(value) || value < 1 || value > 65535) {
+    return { value: null, error: rangeMessage }
+  }
+  return { value, error: null }
+}
+
 export const RemoteAccessSettingsSection: Component = () => {
   const { t } = useI18n()
   const [meta, setMeta] = createSignal<ServerMeta | null>(null)
@@ -32,6 +51,13 @@ export const RemoteAccessSettingsSection: Component = () => {
   const [passwordError, setPasswordError] = createSignal<string | null>(null)
   const [savingPassword, setSavingPassword] = createSignal(false)
   const [showAllAddresses, setShowAllAddresses] = createSignal(false)
+  const [httpsPortInput, setHttpsPortInput] = createSignal("")
+  const [httpPortInput, setHttpPortInput] = createSignal("")
+  const [applyingPorts, setApplyingPorts] = createSignal(false)
+  const [portError, setPortError] = createSignal<string | null>(null)
+
+  let lastSyncedHttpsPort: number | undefined
+  let lastSyncedHttpPort: number | undefined
 
   const addresses = createMemo<NetworkAddress[]>(() => meta()?.addresses ?? [])
   const currentMode = createMemo(() => meta()?.listeningMode ?? serverSettings().listeningMode)
@@ -41,6 +67,41 @@ export const RemoteAccessSettingsSection: Component = () => {
     if (!allowExternalConnections()) return { recommended: null, hidden: [] }
     return splitRemoteAddresses(list)
   })
+  const parsedHttpsPort = createMemo(() =>
+    parsePortInput(
+      httpsPortInput(),
+      t("remoteAccess.ports.validation.invalid"),
+      t("remoteAccess.ports.validation.range"),
+    ),
+  )
+  const parsedHttpPort = createMemo(() =>
+    parsePortInput(
+      httpPortInput(),
+      t("remoteAccess.ports.validation.invalid"),
+      t("remoteAccess.ports.validation.range"),
+    ),
+  )
+  const portValidationMessage = createMemo(() => parsedHttpsPort().error ?? parsedHttpPort().error)
+  const portsChanged = createMemo(() => {
+    if (portValidationMessage()) return false
+    return (
+      parsedHttpsPort().value !== (serverSettings().httpsPort ?? null) ||
+      parsedHttpPort().value !== (serverSettings().httpPort ?? null)
+    )
+  })
+
+  createEffect(() => {
+    const nextHttpsPort = serverSettings().httpsPort
+    const nextHttpPort = serverSettings().httpPort
+    if (nextHttpsPort !== lastSyncedHttpsPort) {
+      setHttpsPortInput(formatPortValue(nextHttpsPort))
+      lastSyncedHttpsPort = nextHttpsPort
+    }
+    if (nextHttpPort !== lastSyncedHttpPort) {
+      setHttpPortInput(formatPortValue(nextHttpPort))
+      lastSyncedHttpPort = nextHttpPort
+    }
+  })
 
   const refreshMeta = async () => {
     setLoading(true)
@@ -153,6 +214,46 @@ export const RemoteAccessSettingsSection: Component = () => {
     }
   }
 
+  const handleSavePorts = async () => {
+    setPortError(null)
+    const validationMessage = portValidationMessage()
+    if (validationMessage) {
+      setPortError(validationMessage)
+      return
+    }
+    if (!portsChanged()) {
+      return
+    }
+
+    const confirmed = await showConfirmDialog(t("remoteAccess.ports.restartConfirm.message"), {
+      title: t("remoteAccess.ports.restartConfirm.title"),
+      variant: "warning",
+      confirmLabel: t("remoteAccess.ports.restartConfirm.confirmLabel"),
+      cancelLabel: t("remoteAccess.ports.restartConfirm.cancelLabel"),
+      dismissible: false,
+    })
+
+    if (!confirmed) return
+
+    setApplyingPorts(true)
+    try {
+      await setServerPorts({
+        httpsPort: parsedHttpsPort().value,
+        httpPort: parsedHttpPort().value,
+      })
+      const restarted = await restartCli()
+      if (!restarted) {
+        setPortError(t("remoteAccess.restart.errorManual"))
+      }
+    } catch (err) {
+      setPortError(err instanceof Error ? err.message : String(err))
+    } finally {
+      setApplyingPorts(false)
+    }
+
+    void refreshMeta()
+  }
+
   return (
     <div class="settings-section-stack">
       <div class="settings-card">
@@ -204,6 +305,67 @@ export const RemoteAccessSettingsSection: Component = () => {
         <p class="remote-toggle-note">{t("remoteAccess.toggle.note")}</p>
       </div>
 
+      <div class="settings-card">
+        <div class="settings-card-header">
+          <div class="settings-card-heading-with-icon">
+            <Link2 class="settings-card-heading-icon" />
+            <div>
+              <h3 class="settings-card-title">{t("remoteAccess.sections.ports.label")}</h3>
+              <p class="settings-card-subtitle">{t("remoteAccess.sections.ports.help")}</p>
+            </div>
+          </div>
+          <span class="settings-scope-badge settings-scope-badge-server">{t("settings.scope.server")}</span>
+        </div>
+
+        <div class="settings-card-content">
+          <div class="grid gap-4 md:grid-cols-2">
+            <div class="settings-form-group mt-0">
+              <label class="settings-form-label">{t("remoteAccess.ports.fields.https")}</label>
+              <input
+                class="selector-input w-full"
+                type="text"
+                inputMode="numeric"
+                value={httpsPortInput()}
+                onInput={(event) => setHttpsPortInput(event.currentTarget.value)}
+                placeholder={t("remoteAccess.ports.placeholder.auto")}
+                aria-invalid={Boolean(parsedHttpsPort().error)}
+              />
+            </div>
+
+            <div class="settings-form-group mt-0">
+              <label class="settings-form-label">{t("remoteAccess.ports.fields.http")}</label>
+              <input
+                class="selector-input w-full"
+                type="text"
+                inputMode="numeric"
+                value={httpPortInput()}
+                onInput={(event) => setHttpPortInput(event.currentTarget.value)}
+                placeholder={t("remoteAccess.ports.placeholder.auto")}
+                aria-invalid={Boolean(parsedHttpPort().error)}
+              />
+            </div>
+          </div>
+
+          <p class="settings-help-text mt-3">{t("remoteAccess.ports.note")}</p>
+          <p class="settings-help-text mt-2">{t("remoteAccess.ports.conflictNote")}</p>
+
+          <Show when={portError() || portValidationMessage()}>
+            {(message) => <div class="settings-error-message">{message()}</div>}
+          </Show>
+
+          <div class="settings-password-actions mt-3">
+            <button
+              class="settings-pill-button"
+              type="button"
+              onClick={() => void handleSavePorts()}
+              disabled={loading() || applyingPorts() || !portsChanged() || Boolean(portValidationMessage())}
+            >
+              {applyingPorts() ? t("remoteAccess.ports.actions.applying") : t("remoteAccess.ports.actions.apply")}
+            </button>
+          </div>
+        </div>
+      </div>
+
       <div class="settings-card">
         <div class="settings-card-header">
           <div class="settings-card-heading-with-icon">

packages/ui/src/lib/i18n/messages/en/remoteAccess.ts

@@ -20,6 +20,22 @@ export const remoteAccessMessages = {
   "remoteAccess.listeningMode.restartConfirm.cancelLabel": "Cancel",
   "remoteAccess.restart.errorManual": "Unable to restart automatically. Please restart the app to apply the change.",
 
+  "remoteAccess.sections.ports.label": "Server ports",
+  "remoteAccess.sections.ports.help": "Set fixed desktop launcher ports for the local HTTP and HTTPS endpoints.",
+  "remoteAccess.ports.fields.https": "HTTPS port",
+  "remoteAccess.ports.fields.http": "HTTP port",
+  "remoteAccess.ports.placeholder.auto": "Automatic",
+  "remoteAccess.ports.note": "Leave a field blank to keep automatic port selection.",
+  "remoteAccess.ports.conflictNote": "If another process is already using the configured port, startup will fail until the port is freed or changed.",
+  "remoteAccess.ports.validation.invalid": "Ports must contain digits only.",
+  "remoteAccess.ports.validation.range": "Ports must be between 1 and 65535.",
+  "remoteAccess.ports.actions.apply": "Apply and restart",
+  "remoteAccess.ports.actions.applying": "Applying…",
+  "remoteAccess.ports.restartConfirm.message": "Restart to apply the configured ports? This will stop all running instances.",
+  "remoteAccess.ports.restartConfirm.title": "Apply server ports",
+  "remoteAccess.ports.restartConfirm.confirmLabel": "Restart now",
+  "remoteAccess.ports.restartConfirm.cancelLabel": "Cancel",
+
   "remoteAccess.sections.serverPassword.label": "Server password",
   "remoteAccess.sections.serverPassword.help": "Remote handovers require a password. Set a memorable one to enable logins from other devices.",
   "remoteAccess.authStatus.unavailable": "Authentication status unavailable.",

packages/ui/src/lib/i18n/messages/es/remoteAccess.ts

@@ -20,6 +20,22 @@ export const remoteAccessMessages = {
   "remoteAccess.listeningMode.restartConfirm.cancelLabel": "Cancelar",
   "remoteAccess.restart.errorManual": "No se pudo reiniciar automáticamente. Reinicia la app para aplicar el cambio.",
 
+  "remoteAccess.sections.ports.label": "Puertos del servidor",
+  "remoteAccess.sections.ports.help": "Define puertos fijos para los endpoints HTTP y HTTPS locales del lanzador de escritorio.",
+  "remoteAccess.ports.fields.https": "Puerto HTTPS",
+  "remoteAccess.ports.fields.http": "Puerto HTTP",
+  "remoteAccess.ports.placeholder.auto": "Automático",
+  "remoteAccess.ports.note": "Deja un campo vacío para mantener la selección automática del puerto.",
+  "remoteAccess.ports.conflictNote": "Si otro proceso ya está usando el puerto configurado, el inicio fallará hasta que el puerto se libere o se cambie.",
+  "remoteAccess.ports.validation.invalid": "Los puertos solo pueden contener dígitos.",
+  "remoteAccess.ports.validation.range": "Los puertos deben estar entre 1 y 65535.",
+  "remoteAccess.ports.actions.apply": "Aplicar y reiniciar",
+  "remoteAccess.ports.actions.applying": "Aplicando…",
+  "remoteAccess.ports.restartConfirm.message": "¿Reiniciar para aplicar los puertos configurados? Esto detendrá todas las instancias en ejecución.",
+  "remoteAccess.ports.restartConfirm.title": "Aplicar puertos del servidor",
+  "remoteAccess.ports.restartConfirm.confirmLabel": "Reiniciar ahora",
+  "remoteAccess.ports.restartConfirm.cancelLabel": "Cancelar",
+
   "remoteAccess.sections.serverPassword.label": "Contraseña del servidor",
   "remoteAccess.sections.serverPassword.help": "Las transferencias remotas requieren una contraseña. Define una fácil de recordar para habilitar inicios de sesión desde otros dispositivos.",
   "remoteAccess.authStatus.unavailable": "Estado de autenticación no disponible.",

packages/ui/src/lib/i18n/messages/fr/remoteAccess.ts

@@ -20,6 +20,22 @@ export const remoteAccessMessages = {
   "remoteAccess.listeningMode.restartConfirm.cancelLabel": "Annuler",
   "remoteAccess.restart.errorManual": "Impossible de redémarrer automatiquement. Veuillez redémarrer l'application pour appliquer le changement.",
 
+  "remoteAccess.sections.ports.label": "Ports du serveur",
+  "remoteAccess.sections.ports.help": "Définissez des ports fixes pour les points d'accès HTTP et HTTPS locaux du lanceur desktop.",
+  "remoteAccess.ports.fields.https": "Port HTTPS",
+  "remoteAccess.ports.fields.http": "Port HTTP",
+  "remoteAccess.ports.placeholder.auto": "Automatique",
+  "remoteAccess.ports.note": "Laissez un champ vide pour conserver la sélection automatique du port.",
+  "remoteAccess.ports.conflictNote": "Si un autre processus utilise déjà le port configuré, le démarrage échouera tant que le port ne sera pas libéré ou changé.",
+  "remoteAccess.ports.validation.invalid": "Les ports ne peuvent contenir que des chiffres.",
+  "remoteAccess.ports.validation.range": "Les ports doivent être compris entre 1 et 65535.",
+  "remoteAccess.ports.actions.apply": "Appliquer et redémarrer",
+  "remoteAccess.ports.actions.applying": "Application…",
+  "remoteAccess.ports.restartConfirm.message": "Redémarrer pour appliquer les ports configurés ? Cela arrêtera toutes les instances en cours.",
+  "remoteAccess.ports.restartConfirm.title": "Appliquer les ports du serveur",
+  "remoteAccess.ports.restartConfirm.confirmLabel": "Redémarrer maintenant",
+  "remoteAccess.ports.restartConfirm.cancelLabel": "Annuler",
+
   "remoteAccess.sections.serverPassword.label": "Mot de passe du serveur",
   "remoteAccess.sections.serverPassword.help": "Les passations à distance nécessitent un mot de passe. Définissez-en un facile à retenir pour autoriser la connexion depuis d'autres appareils.",
   "remoteAccess.authStatus.unavailable": "Statut d'authentification indisponible.",

packages/ui/src/lib/i18n/messages/he/remoteAccess.ts

@@ -20,6 +20,22 @@ export const remoteAccessMessages = {
   "remoteAccess.listeningMode.restartConfirm.cancelLabel": "ביטול",
   "remoteAccess.restart.errorManual": "לא ניתן להפעיל מחדש אוטומטית. אנא הפעל מחדש את האפליקציה כדי להחיל את השינוי.",
 
+  "remoteAccess.sections.ports.label": "פורטי השרת",
+  "remoteAccess.sections.ports.help": "הגדר פורטים קבועים עבור נקודות הקצה המקומיות של HTTP ו-HTTPS במשגר הדסקטופ.",
+  "remoteAccess.ports.fields.https": "פורט HTTPS",
+  "remoteAccess.ports.fields.http": "פורט HTTP",
+  "remoteAccess.ports.placeholder.auto": "אוטומטי",
+  "remoteAccess.ports.note": "השארת שדה ריק תשמור על בחירת פורט אוטומטית.",
+  "remoteAccess.ports.conflictNote": "אם תהליך אחר כבר משתמש בפורט שהוגדר, ההפעלה תיכשל עד שהפורט ישוחרר או ישתנה.",
+  "remoteAccess.ports.validation.invalid": "פורטים יכולים להכיל ספרות בלבד.",
+  "remoteAccess.ports.validation.range": "הפורטים חייבים להיות בין 1 ל-65535.",
+  "remoteAccess.ports.actions.apply": "החל והפעל מחדש",
+  "remoteAccess.ports.actions.applying": "מחיל…",
+  "remoteAccess.ports.restartConfirm.message": "להפעיל מחדש כדי להחיל את הפורטים שהוגדרו? פעולה זו תעצור את כל המופעים הפעילים.",
+  "remoteAccess.ports.restartConfirm.title": "החל פורטי שרת",
+  "remoteAccess.ports.restartConfirm.confirmLabel": "הפעל מחדש עכשיו",
+  "remoteAccess.ports.restartConfirm.cancelLabel": "ביטול",
+
   "remoteAccess.sections.serverPassword.label": "סיסמת שרת",
   "remoteAccess.sections.serverPassword.help": "גישה מרוחקת דורשת סיסמה. הגדר סיסמה קלה לזכירה כדי לאפשר כניסות ממכשירים אחרים.",
   "remoteAccess.authStatus.unavailable": "סטטוס האימות אינו זמין.",