v1.31.0

changelog.md

@@ -3,6 +3,62 @@
 ## Pending
 
 
+
+## 2026-05-25 - 1.31.0
+
+### Features
+
+- resolve repo manifests and docker digest-tracked images (appstore)
+  - Add catalog source, resolved source, channel, runtime, upgrade strategy, and version metadata types for appstore manifests.
+  - Resolve catalog entries from repo manifests and pin digest-tracked Docker images using registry digests.
+  - Propagate resolved image digests into app version configs and service creation options.
+  - Add runtime coverage for repo manifest resolution and digest-tracked latest images.
+
+## 2026-05-24 - 1.30.2
+
+### Fixes
+
+- reduce remaining reverse proxy wording to required legacy SmartProxy cleanup and migration identifiers
+- clean up legacy reverse proxy naming for SmartProxy (smartproxy)
+  - Update legacy reverse proxy service naming and logs used during SmartProxy startup cleanup.
+  - Clarify migration and documentation wording for the legacy reverse proxy to SmartProxy transition.
+  - Bump @serve.zone/catalog to ^2.12.6 and add pnpm workspace build dependency settings.
+
+## 2026-05-24 - 1.30.1
+
+### Fixes
+
+- align Onebox settings gateway cards with the dees-tile footer action pattern
+- align settings gateway cards with dees-tile footer actions (settings-ui)
+  - Replaces custom gateway card wrappers with dees-tile header and footer slots.
+  - Uses tile-styled action buttons for Admin UI and dcrouter settings saves.
+
+## 2026-05-24 - 1.30.0
+
+### Features
+
+- add configurable Onebox Admin UI domain
+  - expose Admin UI domain in settings
+  - sync the Admin UI route as a first-class dcrouter gateway route
+  - keep Admin UI routing separate from app service routes
+- add configurable Admin UI domain routing (admin-ui)
+  - Expose and validate the Admin UI domain in settings
+  - Sync the Admin UI as a dedicated dcrouter gateway route and SmartProxy route
+  - Preserve configured and legacy Admin UI routes during stale-route reconciliation
+
+### Fixes
+
+- preserve Onebox Admin UI routes during external gateway stale-route reconciliation
+
+## 2026-05-24 - 1.29.0
+
+### Features
+
+- add Onebox runtime update prompts and admin-triggered self-upgrades
+  - expose Onebox update status through system status
+  - reuse the CLI upgrade logic for web-triggered detached upgrades
+  - show an update banner and guided DeesUpdater flow in the dashboard
+
 ## 2026-05-24 - 1.28.0
 
 ### Features

deno.json

@@ -1,6 +1,6 @@
 {
   "name": "@serve.zone/onebox",
-  "version": "1.28.0",
+  "version": "1.31.0",
   "exports": "./mod.ts",
   "tasks": {
     "test": "deno test --allow-all test/",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serve.zone/onebox",
-  "version": "1.28.0",
+  "version": "1.31.0",
   "description": "Self-hosted container platform with automatic SSL and DNS - a mini Heroku for single servers",
   "main": "mod.ts",
   "type": "module",
@@ -52,21 +52,18 @@
     "x64",
     "arm64"
   ],
-  "packageManager": "pnpm@10.18.1+sha512.77a884a165cbba2d8d1c19e3b4880eee6d2fcabd0d879121e282196b80042351d5eb3ca0935fa599da1dc51265cc68816ad2bddd2a2de5ea9fdf92adbec7cd34",
+  "packageManager": "pnpm@11.1.2",
   "dependencies": {
     "@api.global/typedrequest-interfaces": "^3.0.19",
     "@api.global/typedsocket": "^4.1.3",
     "@design.estate/dees-catalog": "^3.81.0",
     "@design.estate/dees-element": "^2.2.4",
-    "@serve.zone/catalog": "^2.12.5"
+    "@serve.zone/catalog": "^2.12.6"
   },
   "devDependencies": {
     "@git.zone/tsbundle": "^2.10.4",
     "@git.zone/tsdeno": "^1.3.2",
     "@git.zone/tswatch": "^3.3.5"
   },
-  "private": true,
+  "private": true
-  "pnpm": {
-    "overrides": {}
-  }
 }

pnpm-lock.yaml

@@ -21,8 +21,8 @@ importers:
         specifier: ^2.2.4
         version: 2.2.4
       '@serve.zone/catalog':
-        specifier: ^2.12.5
+        specifier: ^2.12.6
-        version: 2.12.5(@tiptap/pm@2.27.2)
+        version: 2.12.6(@tiptap/pm@2.27.2)
     devDependencies:
       '@git.zone/tsbundle':
         specifier: ^2.10.4
@@ -977,8 +977,8 @@ packages:
   '@sec-ant/readable-stream@0.4.1':
     resolution: {integrity: sha512-831qok9r2t8AlxLko40y2ebgSDhenenCatLVeW/uBtnHPyhHOvG0C7TvfgecV+wHzIm5KUICgzmVpWS+IMEAeg==}
 
-  '@serve.zone/catalog@2.12.5':
+  '@serve.zone/catalog@2.12.6':
-    resolution: {integrity: sha512-0AgHnxonJ7xyYdA02s4tN9/aZG8yBYml4sAA7AUt9fYpRtKYMuZXUcUOS3Rz/FvUu1PrKe7QLtex9VK5IqZDPw==}
+    resolution: {integrity: sha512-FjieZNCHTCHufMre8OSP8bFP9L4DPL9yNtd7UMwD1yQ8wublgAq6eWrx6Tfb+3k8Hyof33BBt4rbFyrvIEBk+A==}
 
   '@tempfix/lenis@1.3.20':
     resolution: {integrity: sha512-ypeB0FuHLHOCQXW4d0RQ69txPJJH+1CHcpsZIUdcv2t1vR0IVyQr2vHihtde9UOXhjzqEnUphWon/UcJNsa0YA==}
@@ -3572,7 +3572,7 @@ snapshots:
 
   '@sec-ant/readable-stream@0.4.1': {}
 
-  '@serve.zone/catalog@2.12.5(@tiptap/pm@2.27.2)':
+  '@serve.zone/catalog@2.12.6(@tiptap/pm@2.27.2)':
     dependencies:
       '@design.estate/dees-catalog': 3.81.0(@tiptap/pm@2.27.2)
       '@design.estate/dees-domtools': 2.5.6

pnpm-workspace.yaml

@@ -0,0 +1,4 @@
+allowBuilds:
+  esbuild: true
+ignoredBuiltDependencies:
+  - '@design.estate/dees-catalog'

readme.hints.md

@@ -46,7 +46,7 @@ ts/database/
 
 ## Current Migration Version: 15
 
-Migration 15 renames the core reverse proxy platform service from `caddy` to `smartproxy`.
+Migration 15 renames the legacy core reverse proxy platform service type to `smartproxy`.
 
 ## Reverse Proxy (April 2026 - SmartProxy Docker Service)
 

test/appstore_runtime_test.ts

@@ -81,6 +81,96 @@ Deno.test('appstore rejects invalid template ports and volumes', () => {
   );
 });
 
+Deno.test('appstore resolves repo manifests and docker digest-tracked latest images', async () => {
+  const catalogBaseUrl = 'https://catalog.example.test';
+  const manifestUrl = 'https://code.example.test/cloudly/servezone.catalog.json';
+  const digest = 'sha256:1234567890abcdef';
+
+  const fakeFetch: typeof fetch = async (input, init) => {
+    const url = input instanceof Request ? input.url : input.toString();
+    const method = init?.method || 'GET';
+
+    if (url === `${catalogBaseUrl}/catalog.resolved.json`) {
+      return new Response('not found', { status: 404 });
+    }
+
+    if (url === `${catalogBaseUrl}/catalog.json`) {
+      return Response.json({
+        schemaVersion: 1,
+        updatedAt: '2026-05-24T00:00:00Z',
+        apps: [
+          {
+            id: 'cloudly',
+            name: 'Cloudly',
+            description: 'Central metadata can stay curated.',
+            category: 'Dev Tools',
+            latestVersion: '1.0.0',
+            source: {
+              type: 'repoManifest',
+              url: manifestUrl,
+              ref: 'main',
+            },
+          },
+        ],
+      });
+    }
+
+    if (url === manifestUrl) {
+      return Response.json({
+        schemaVersion: 1,
+        app: {
+          id: 'cloudly',
+          name: 'Cloudly',
+          description: 'Manifest-owned app metadata.',
+          category: 'Dev Tools',
+          maintainer: 'serve.zone',
+        },
+        latestVersion: 'latest',
+        source: {
+          type: 'dockerImage',
+          image: 'registry.example.test/serve.zone/cloudly:latest',
+          tracking: 'digest',
+        },
+        runtime: {
+          image: 'registry.example.test/serve.zone/cloudly:latest',
+          port: 80,
+        },
+      });
+    }
+
+    if (
+      url === 'https://registry.example.test/v2/serve.zone/cloudly/manifests/latest' &&
+      method === 'HEAD'
+    ) {
+      return new Response(null, {
+        status: 200,
+        headers: { 'docker-content-digest': digest },
+      });
+    }
+
+    return new Response(`unexpected ${method} ${url}`, { status: 500 });
+  };
+
+  const appStore = new AppStoreManager({} as any, {
+    repoBaseUrl: catalogBaseUrl,
+    fetch: fakeFetch,
+  });
+
+  const catalog = await appStore.getCatalog();
+  assertEquals(catalog.apps[0].latestVersion, `latest@${digest}`);
+  assertEquals(catalog.apps[0].resolvedSource?.manifestHash?.length, 64);
+  assertEquals(catalog.apps[0].upgradeStrategy, 'dockerDigest');
+
+  const appMeta = await appStore.getAppMeta('cloudly');
+  assertEquals(appMeta.latestVersion, `latest@${digest}`);
+  assertEquals(appMeta.versions, [`latest@${digest}`]);
+
+  const config = await appStore.getAppVersionConfig('cloudly', appMeta.latestVersion);
+  assertEquals(config.image, 'registry.example.test/serve.zone/cloudly:latest');
+  assertEquals(config.catalogVersion, `latest@${digest}`);
+  assertEquals(config.resolvedImageDigest, digest);
+});
+
 Deno.test('docker service spec validation rejects unsafe volume and port declarations', () => {
   const dockerManager = new OneboxDockerManager();
 

test/external_gateway_test.ts

@@ -173,6 +173,47 @@ Deno.test('ExternalGatewayManager syncs service routes to dcrouter gatewayClient
   assertEquals(syncRequest.requestData.enabled, true);
 });
 
+Deno.test('ExternalGatewayManager syncs Admin UI route to dcrouter gatewayClient API', async () => {
+  const oneboxRef = makeOneboxRef();
+  oneboxRef.database.settings.set('adminUiDomain', 'Onebox.Example.com');
+  oneboxRef.database.settings.set('serverIP', '203.0.113.10');
+  oneboxRef.database.settings.set('httpPort', '8080');
+
+  const requests: Array<{ method: string; requestData: Record<string, unknown> }> = [];
+  const manager = new ExternalGatewayManager(oneboxRef as any);
+  (manager as any).fireDcRouterRequest = async (
+    method: string,
+    requestData: Record<string, unknown>,
+  ) => {
+    if (method === 'getGatewayClientContext') {
+      return {
+        context: { role: 'gatewayClient', gatewayClient: { type: 'onebox', id: 'onebox-token' } },
+      };
+    }
+    requests.push({ method, requestData });
+    if (method === 'exportCertificate') {
+      return { success: false };
+    }
+    return { success: true, action: 'created', routeId: 'admin-route' };
+  };
+
+  await manager.syncAdminUiRoute();
+
+  const syncRequest = requests.find((request) => request.method === 'syncGatewayClientRoute')!;
+  const route = syncRequest.requestData.route as any;
+  const ownership = syncRequest.requestData.ownership as any;
+
+  assertEquals(ownership, {
+    gatewayClientType: 'onebox',
+    gatewayClientId: 'onebox-token',
+    appId: 'onebox-admin-ui',
+    hostname: 'onebox.example.com',
+  });
+  assertEquals(route.match, { ports: [443], domains: ['onebox.example.com'] });
+  assertEquals(route.action.targets, [{ host: '203.0.113.10', port: 8080 }]);
+  assertEquals(syncRequest.requestData.enabled, true);
+});
+
 Deno.test('ExternalGatewayManager uses managed dcrouter local target in managed mode', async () => {
   const oneboxRef = makeOneboxRef();
   (oneboxRef as any).managedDcRouter = {
@@ -322,6 +363,206 @@ Deno.test('ExternalGatewayManager removes stale gateway routes during reconcilia
   assertEquals((deletes[0].ownership as any).hostname, 'stale.example.com');
 });
 
+Deno.test('ExternalGatewayManager preserves configured Admin UI route during reconciliation', async () => {
+  const oneboxRef = makeOneboxRef();
+  oneboxRef.database.settings.set('adminUiDomain', 'onebox.example.com');
+  oneboxRef.database.settings.set('serverIP', '203.0.113.10');
+  oneboxRef.database.services.push({
+    id: 1,
+    name: 'active',
+    image: 'nginx:latest',
+    envVars: {},
+    port: 3000,
+    domain: 'active.example.com',
+    status: 'running',
+    createdAt: 1,
+    updatedAt: 1,
+  });
+
+  const deletes: Record<string, unknown>[] = [];
+  const manager = new ExternalGatewayManager(oneboxRef as any);
+  (manager as any).fireDcRouterRequest = async (method: string, requestData: Record<string, unknown>) => {
+    if (method === 'getGatewayClientContext') {
+      return { context: { role: 'gatewayClient', gatewayClient: { type: 'onebox', id: 'onebox-token' } } };
+    }
+    if (method === 'syncGatewayClientRoute') {
+      if (requestData.delete) {
+        deletes.push(requestData);
+        return { success: true, action: 'deleted' };
+      }
+      return { success: true, action: 'updated' };
+    }
+    if (method === 'exportCertificate') {
+      return { success: false };
+    }
+    if (method === 'getGatewayClientDnsRecords') {
+      return {
+        records: [
+          {
+            id: 'admin-record',
+            domainId: 'domain-1',
+            name: 'onebox',
+            type: 'A',
+            value: '203.0.113.10',
+            ttl: 300,
+            source: 'route',
+            status: 'active',
+            gatewayClientType: 'onebox',
+            gatewayClientId: 'onebox-token',
+            appId: 'onebox-admin-ui',
+            hostname: 'onebox.example.com',
+            routeId: 'admin-route',
+          },
+          {
+            id: 'stale-record',
+            domainId: 'domain-1',
+            name: 'stale',
+            type: 'A',
+            value: '203.0.113.10',
+            ttl: 300,
+            source: 'route',
+            status: 'active',
+            gatewayClientType: 'onebox',
+            gatewayClientId: 'onebox-token',
+            appId: 'stale',
+            hostname: 'stale.example.com',
+            routeId: 'stale-route',
+          },
+        ],
+      };
+    }
+    throw new Error(`Unexpected method: ${method}`);
+  };
+
+  await manager.syncServiceRoutes();
+
+  assertEquals(deletes.length, 1);
+  assertEquals((deletes[0].ownership as any).hostname, 'stale.example.com');
+});
+
+Deno.test('ExternalGatewayManager preserves legacy Admin UI route when setting is absent', async () => {
+  const oneboxRef = makeOneboxRef();
+  oneboxRef.database.settings.set('serverIP', '203.0.113.10');
+
+  const deletes: Record<string, unknown>[] = [];
+  const manager = new ExternalGatewayManager(oneboxRef as any);
+  (manager as any).fireDcRouterRequest = async (
+    method: string,
+    requestData: Record<string, unknown>,
+  ) => {
+    if (method === 'getGatewayClientContext') {
+      return {
+        context: { role: 'gatewayClient', gatewayClient: { type: 'onebox', id: 'onebox-token' } },
+      };
+    }
+    if (method === 'syncGatewayClientRoute') {
+      if (requestData.delete) {
+        deletes.push(requestData);
+        return { success: true, action: 'deleted' };
+      }
+      return { success: true, action: 'updated' };
+    }
+    if (method === 'getGatewayClientDnsRecords') {
+      return {
+        records: [
+          {
+            id: 'legacy-admin-record',
+            domainId: 'domain-1',
+            name: 'onebox',
+            type: 'A',
+            value: '203.0.113.10',
+            ttl: 300,
+            source: 'route',
+            status: 'active',
+            gatewayClientType: 'onebox',
+            gatewayClientId: 'onebox-token',
+            appId: 'onebox',
+            hostname: 'onebox.example.com',
+            routeId: 'legacy-admin-route',
+          },
+          {
+            id: 'stale-record',
+            domainId: 'domain-1',
+            name: 'stale',
+            type: 'A',
+            value: '203.0.113.10',
+            ttl: 300,
+            source: 'route',
+            status: 'active',
+            gatewayClientType: 'onebox',
+            gatewayClientId: 'onebox-token',
+            appId: 'stale',
+            hostname: 'stale.example.com',
+            routeId: 'stale-route',
+          },
+        ],
+      };
+    }
+    throw new Error(`Unexpected method: ${method}`);
+  };
+
+  await manager.syncServiceRoutes();
+
+  assertEquals(deletes.length, 1);
+  assertEquals((deletes[0].ownership as any).hostname, 'stale.example.com');
+});
+
+Deno.test('ExternalGatewayManager deletes old Admin UI route after domain change', async () => {
+  const oneboxRef = makeOneboxRef();
+  oneboxRef.database.settings.set('adminUiDomain', 'new.example.com');
+  oneboxRef.database.settings.set('serverIP', '203.0.113.10');
+
+  const deletes: Record<string, unknown>[] = [];
+  const manager = new ExternalGatewayManager(oneboxRef as any);
+  (manager as any).fireDcRouterRequest = async (
+    method: string,
+    requestData: Record<string, unknown>,
+  ) => {
+    if (method === 'getGatewayClientContext') {
+      return {
+        context: { role: 'gatewayClient', gatewayClient: { type: 'onebox', id: 'onebox-token' } },
+      };
+    }
+    if (method === 'syncGatewayClientRoute') {
+      if (requestData.delete) {
+        deletes.push(requestData);
+        return { success: true, action: 'deleted' };
+      }
+      return { success: true, action: 'updated' };
+    }
+    if (method === 'exportCertificate') {
+      return { success: false };
+    }
+    if (method === 'getGatewayClientDnsRecords') {
+      return {
+        records: [
+          {
+            id: 'old-admin-record',
+            domainId: 'domain-1',
+            name: 'onebox',
+            type: 'A',
+            value: '203.0.113.10',
+            ttl: 300,
+            source: 'route',
+            status: 'active',
+            gatewayClientType: 'onebox',
+            gatewayClientId: 'onebox-token',
+            appId: 'onebox-admin-ui',
+            hostname: 'old.example.com',
+            routeId: 'old-admin-route',
+          },
+        ],
+      };
+    }
+    throw new Error(`Unexpected method: ${method}`);
+  };
+
+  await manager.syncServiceRoutes();
+
+  assertEquals(deletes.length, 1);
+  assertEquals((deletes[0].ownership as any).hostname, 'old.example.com');
+});
+
 Deno.test('ExternalGatewayManager imports exported dcrouter certificates into Onebox', async () => {
   const oneboxRef = makeOneboxRef();
   const manager = new ExternalGatewayManager(oneboxRef as any);

test/reverseproxy_test.ts

@@ -0,0 +1,50 @@
+import { assertEquals } from '@std/assert';
+
+import { OneboxReverseProxy } from '../ts/classes/reverseproxy.ts';
+import type { IService } from '../ts/types.ts';
+
+class FakeDatabase {
+  public settings = new Map<string, string>();
+  public services: IService[] = [];
+
+  getSetting(key: string): string | null {
+    return this.settings.get(key) ?? null;
+  }
+
+  getAllServices(): IService[] {
+    return this.services;
+  }
+
+  getServiceByID(id: number): IService | null {
+    return this.services.find((service) => service.id === id) ?? null;
+  }
+
+  getAllSSLCertificates(): [] {
+    return [];
+  }
+}
+
+Deno.test('OneboxReverseProxy loads Admin UI domain as local SmartProxy route', async () => {
+  const database = new FakeDatabase();
+  database.settings.set('adminUiDomain', 'onebox.example.com');
+  database.settings.set('serverIP', '203.0.113.10');
+
+  const reverseProxy = new OneboxReverseProxy({ database } as any);
+  const routes: Array<{ domain: string; upstream: string }> = [];
+  (reverseProxy as any).smartProxy = {
+    clear: () => routes.splice(0, routes.length),
+    addRoute: async (domain: string, upstream: string) => {
+      routes.push({ domain, upstream });
+    },
+    getCertificates: () => [],
+  };
+
+  await reverseProxy.reloadRoutes();
+
+  assertEquals(routes, [
+    {
+      domain: 'onebox.example.com',
+      upstream: '203.0.113.10:3000',
+    },
+  ]);
+});

ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@serve.zone/onebox',
-  version: '1.28.0',
+  version: '1.31.0',
   description: 'Self-hosted container platform with automatic SSL and DNS - a mini Heroku for single servers'
 }

ts/classes/appstore-types.ts

@@ -6,6 +6,42 @@ export interface ICatalog {
   schemaVersion: number;
   updatedAt: string;
   apps: ICatalogApp[];
+  resolvedAt?: string;
+}
+
+export type TAppCatalogSourceType = 'inline' | 'repoManifest' | 'dockerImage';
+export type TAppCatalogTrackingMode = 'tag' | 'digest';
+export type TAppUpgradeStrategy = 'semver' | 'branch' | 'dockerDigest';
+
+export interface IAppCatalogInlineSource {
+  type: 'inline';
+}
+
+export interface IAppCatalogRepoManifestSource {
+  type: 'repoManifest';
+  url: string;
+  ref?: string;
+}
+
+export interface IAppCatalogDockerImageSource {
+  type: 'dockerImage';
+  image: string;
+  tracking?: TAppCatalogTrackingMode;
+}
+
+export type TAppCatalogSource =
+  | IAppCatalogInlineSource
+  | IAppCatalogRepoManifestSource
+  | IAppCatalogDockerImageSource;
+
+export interface IResolvedCatalogSource {
+  type: TAppCatalogSourceType;
+  url?: string;
+  ref?: string;
+  image?: string;
+  manifestHash?: string;
+  imageDigest?: string;
+  resolvedAt: string;
 }
 
 export interface ICatalogApp {
@@ -16,7 +52,13 @@ export interface ICatalogApp {
   iconName?: string;
   iconUrl?: string;
   latestVersion: string;
+  versions?: string[];
   tags?: string[];
+  source?: TAppCatalogSource;
+  runtime?: IAppVersionConfig;
+  channel?: string;
+  upgradeStrategy?: TAppUpgradeStrategy;
+  resolvedSource?: IResolvedCatalogSource;
 }
 
 export interface IAppCatalogVolume {
@@ -50,6 +92,9 @@ export interface IAppMeta {
   versions: string[];
   maintainer?: string;
   links?: Record<string, string>;
+  tags?: string[];
+  source?: TAppCatalogSource;
+  resolvedSource?: IResolvedCatalogSource;
 }
 
 export interface IAppVersionConfig {
@@ -66,6 +111,53 @@ export interface IAppVersionConfig {
     mariadb?: boolean;
   };
   minOneboxVersion?: string;
+  catalogVersion?: string;
+  upgradeStrategy?: TAppUpgradeStrategy;
+  source?: TAppCatalogSource;
+  resolvedSource?: IResolvedCatalogSource;
+  resolvedImageDigest?: string;
+  changelog?: string;
+  breaking?: boolean;
+  requiresManualReview?: boolean;
+  migrationRequired?: boolean;
+  backupBeforeUpgrade?: boolean;
+  requiresFeatures?: string[];
+  healthCheck?: {
+    path?: string;
+    port?: number;
+    expectedStatus?: number;
+  };
+}
+
+export interface IServezoneCatalogAppInfo {
+  id: string;
+  name: string;
+  description: string;
+  category: string;
+  iconName?: string;
+  iconUrl?: string;
+  tags?: string[];
+  maintainer?: string;
+  links?: Record<string, string>;
+}
+
+export interface IServezoneCatalogVersion extends IAppVersionConfig {
+  version: string;
+}
+
+export interface IServezoneCatalogManifest {
+  schemaVersion: number;
+  app: IServezoneCatalogAppInfo;
+  latestVersion?: string;
+  channel?: string;
+  channels?: Record<string, string>;
+  source?: TAppCatalogSource;
+  runtime?: IAppVersionConfig;
+  versions?: IServezoneCatalogVersion[];
+  policy?: {
+    allowMutableImage?: boolean;
+    defaultChannel?: string;
+  };
 }
 
 export interface IAppInstallOptions {
@@ -94,6 +186,7 @@ export interface IMigrationResult {
   success: boolean;
   envVars?: Record<string, string>;
   image?: string;
+  imageDigest?: string;
   port?: number;
   volumes?: IAppCatalogVolume[];
   publishedPorts?: IAppCatalogPublishedPort[];

ts/classes/appstore.ts

@@ -14,6 +14,10 @@ import type {
   IMigrationContext,
   IMigrationResult,
   IUpgradeableService,
+  IAppCatalogDockerImageSource,
+  IAppCatalogRepoManifestSource,
+  IResolvedCatalogSource,
+  IServezoneCatalogManifest,
 } from './appstore-types.ts';
 import { logger } from '../logging.ts';
 import { getErrorMessage } from '../utils/error.ts';
@@ -21,15 +25,40 @@ import type { Onebox } from './onebox.ts';
 import type { IService, IServiceVolume } from '../types.ts';
 import { projectInfo } from '../info.ts';
 
+export interface IAppStoreManagerOptions {
+  repoBaseUrl?: string;
+  fetch?: typeof fetch;
+  resolveDockerDigests?: boolean;
+}
+
+interface IResolvedSourceApp {
+  catalogApp: ICatalogApp;
+  appMeta: IAppMeta;
+  configsByVersion: Map<string, IAppVersionConfig>;
+}
+
+interface IParsedDockerImageReference {
+  registry: string;
+  repository: string;
+  tag: string;
+  digest?: string;
+}
+
 export class AppStoreManager {
   private oneboxRef: Onebox;
   private catalogCache: ICatalog | null = null;
+  private sourceAppCache = new Map<string, IResolvedSourceApp>();
   private lastFetchTime = 0;
-  private readonly repoBaseUrl = 'https://code.foss.global/serve.zone/appstore-apptemplates/raw/branch/main';
+  private readonly repoBaseUrl: string;
+  private readonly fetchRef: typeof fetch;
+  private readonly resolveDockerDigests: boolean;
   private readonly cacheTtlMs = 5 * 60 * 1000; // 5 minutes
 
-  constructor(oneboxRef: Onebox) {
+  constructor(oneboxRef: Onebox, optionsArg: IAppStoreManagerOptions = {}) {
     this.oneboxRef = oneboxRef;
+    this.repoBaseUrl = optionsArg.repoBaseUrl || 'https://code.foss.global/serve.zone/appstore-apptemplates/raw/branch/main';
+    this.fetchRef = optionsArg.fetch || fetch;
+    this.resolveDockerDigests = optionsArg.resolveDockerDigests ?? true;
   }
 
   async init(): Promise<void> {
@@ -52,11 +81,12 @@ export class AppStoreManager {
     }
 
     try {
-      const catalog = await this.fetchJson('catalog.json') as ICatalog;
+      const catalog = await this.fetchCatalog();
       if (catalog && catalog.apps && Array.isArray(catalog.apps)) {
-        this.catalogCache = catalog;
+        const resolvedCatalog = await this.resolveCatalog(catalog);
+        this.catalogCache = resolvedCatalog;
         this.lastFetchTime = now;
-        return catalog;
+        return resolvedCatalog;
       }
       throw new Error('Invalid catalog format');
     } catch (error) {
@@ -82,6 +112,14 @@ export class AppStoreManager {
    */
   async getAppMeta(appId: string): Promise<IAppMeta> {
     try {
+      const catalogApp = await this.getCatalogApp(appId);
+      if (catalogApp?.source?.type === 'repoManifest') {
+        const resolvedApp = await this.resolveRepoManifestSource(catalogApp.source, catalogApp);
+        return resolvedApp.appMeta;
+      }
+      if (catalogApp?.source?.type === 'dockerImage') {
+        return this.createAppMetaFromCatalogApp(catalogApp);
+      }
       return await this.fetchJson(`apps/${appId}/app.json`) as IAppMeta;
     } catch (error) {
       throw new Error(`Failed to fetch metadata for app '${appId}': ${getErrorMessage(error)}`);
@@ -93,7 +131,37 @@ export class AppStoreManager {
    */
   async getAppVersionConfig(appId: string, version: string): Promise<IAppVersionConfig> {
     try {
-      const config = await this.fetchJson(`apps/${appId}/versions/${version}/config.json`) as IAppVersionConfig;
+      const catalogApp = await this.getCatalogApp(appId);
+      if (catalogApp?.source?.type === 'repoManifest') {
+        const resolvedApp = await this.resolveRepoManifestSource(catalogApp.source, catalogApp);
+        const config = resolvedApp.configsByVersion.get(version);
+        if (!config) {
+          throw new Error(`Version '${version}' is not defined by the linked app manifest`);
+        }
+        this.validateAppVersionConfig(config, `${appId}@${version}`);
+        return config;
+      }
+
+      if (catalogApp?.source?.type === 'dockerImage' && catalogApp.runtime) {
+        const config: IAppVersionConfig = { ...catalogApp.runtime };
+        await this.applyDockerImageSourceToConfig(catalogApp.source, config, version);
+        this.validateAppVersionConfig(config, `${appId}@${version}`);
+        return config;
+      }
+
+      let config: IAppVersionConfig;
+      try {
+        config = await this.fetchJson(`apps/${appId}/versions/${version}/config.json`) as IAppVersionConfig;
+      } catch (error) {
+        if (catalogApp?.source?.type !== 'dockerImage') {
+          throw error;
+        }
+        const appMeta = await this.fetchJson(`apps/${appId}/app.json`) as IAppMeta;
+        config = await this.fetchJson(`apps/${appId}/versions/${appMeta.latestVersion}/config.json`) as IAppVersionConfig;
+      }
+      if (catalogApp?.source?.type === 'dockerImage') {
+        await this.applyDockerImageSourceToConfig(catalogApp.source, config, version);
+      }
       this.validateAppVersionConfig(config, `${appId}@${version}`);
       return config;
     } catch (error) {
@@ -106,6 +174,7 @@ export class AppStoreManager {
     const appMeta = await this.getAppMeta(optionsArg.appId);
     const version = optionsArg.version || appMeta.latestVersion;
     const config = await this.getAppVersionConfig(optionsArg.appId, version);
+    const catalogVersion = config.catalogVersion || version;
     this.assertRuntimeCompatibility(config);
     const servicePort = optionsArg.port || config.port;
     this.assertValidPort(servicePort, 'install service port');
@@ -133,7 +202,8 @@ export class AppStoreManager {
       enableRedis: Boolean(config.platformRequirements?.redis),
       enableMariaDB: Boolean(config.platformRequirements?.mariadb),
       appTemplateId: optionsArg.appId,
-      appTemplateVersion: version,
+      appTemplateVersion: catalogVersion,
+      imageDigest: config.resolvedImageDigest,
     });
   }
 
@@ -206,6 +276,7 @@ export class AppStoreManager {
       return {
         success: true,
         image: config.image,
+        imageDigest: config.resolvedImageDigest,
         port: config.port,
         volumes: this.normalizeVolumes(config.volumes),
         publishedPorts: config.publishedPorts,
@@ -309,6 +380,10 @@ export class AppStoreManager {
       updates.image = migrationResult.image;
     }
 
+    if (migrationResult.imageDigest !== undefined) {
+      updates.imageDigest = migrationResult.imageDigest;
+    }
+
     if (migrationResult.port) {
       updates.port = migrationResult.port;
     }
@@ -365,12 +440,425 @@ export class AppStoreManager {
     return this.oneboxRef.database.getServiceByName(serviceName)!;
   }
 
+  private async fetchCatalog(): Promise<ICatalog> {
+    try {
+      return await this.fetchJson('catalog.resolved.json') as ICatalog;
+    } catch {
+      return await this.fetchJson('catalog.json') as ICatalog;
+    }
+  }
+
+  private async resolveCatalog(catalogArg: ICatalog): Promise<ICatalog> {
+    this.sourceAppCache.clear();
+    const apps: ICatalogApp[] = [];
+
+    for (const appArg of catalogArg.apps) {
+      try {
+        apps.push(await this.resolveCatalogApp(appArg));
+      } catch (error) {
+        logger.warn(`Failed to resolve catalog source for '${appArg.id}': ${getErrorMessage(error)}`);
+        apps.push(appArg);
+      }
+    }
+
+    return {
+      ...catalogArg,
+      apps,
+      resolvedAt: new Date().toISOString(),
+    };
+  }
+
+  private async resolveCatalogApp(appArg: ICatalogApp): Promise<ICatalogApp> {
+    if (appArg.source?.type === 'repoManifest') {
+      const resolvedApp = await this.resolveRepoManifestSource(appArg.source, appArg);
+      return {
+        ...resolvedApp.catalogApp,
+        ...this.withoutUndefined(appArg),
+        latestVersion: resolvedApp.catalogApp.latestVersion,
+        versions: resolvedApp.catalogApp.versions,
+        source: appArg.source,
+        tags: appArg.tags || resolvedApp.catalogApp.tags,
+        resolvedSource: resolvedApp.catalogApp.resolvedSource,
+      };
+    }
+
+    if (appArg.source?.type === 'dockerImage') {
+      const config = appArg.runtime ? { ...appArg.runtime } : undefined;
+      const resolvedSource = config
+        ? (await this.applyDockerImageSourceToConfig(appArg.source, config, appArg.latestVersion)).resolvedSource
+        : await this.resolveDockerImageSource(appArg.source);
+      const latestVersion = this.createCatalogVersionForDockerSource(
+        appArg.source,
+        appArg.latestVersion,
+        resolvedSource?.imageDigest,
+      );
+      return {
+        ...appArg,
+        runtime: config,
+        latestVersion,
+        versions: this.uniqueStrings([...(appArg.versions || []), latestVersion]),
+        upgradeStrategy: appArg.source.tracking === 'digest' ? 'dockerDigest' : appArg.upgradeStrategy,
+        resolvedSource,
+      };
+    }
+
+    return appArg;
+  }
+
+  private async resolveRepoManifestSource(
+    sourceArg: IAppCatalogRepoManifestSource,
+    catalogAppArg?: ICatalogApp,
+  ): Promise<IResolvedSourceApp> {
+    const cacheKey = `${sourceArg.url}#${sourceArg.ref || ''}`;
+    const cachedApp = this.sourceAppCache.get(cacheKey);
+    if (cachedApp) {
+      return cachedApp;
+    }
+
+    const manifestText = await this.fetchTextFromUrl(sourceArg.url);
+    const manifestHash = await this.createSha256Hex(manifestText);
+    const manifest = JSON.parse(manifestText) as IServezoneCatalogManifest;
+    const resolvedApp = await this.resolveServezoneCatalogManifest(manifest, {
+      type: 'repoManifest',
+      url: sourceArg.url,
+      ref: sourceArg.ref,
+      manifestHash,
+      resolvedAt: new Date().toISOString(),
+    });
+
+    if (catalogAppArg) {
+      resolvedApp.catalogApp = {
+        ...resolvedApp.catalogApp,
+        ...this.withoutUndefined(catalogAppArg),
+        latestVersion: resolvedApp.catalogApp.latestVersion,
+        versions: resolvedApp.catalogApp.versions,
+        source: catalogAppArg.source,
+        tags: catalogAppArg.tags || resolvedApp.catalogApp.tags,
+        resolvedSource: resolvedApp.catalogApp.resolvedSource,
+      };
+      resolvedApp.appMeta = {
+        ...resolvedApp.appMeta,
+        id: resolvedApp.catalogApp.id,
+        name: resolvedApp.catalogApp.name,
+        description: resolvedApp.catalogApp.description,
+        category: resolvedApp.catalogApp.category,
+        iconName: resolvedApp.catalogApp.iconName,
+        latestVersion: resolvedApp.catalogApp.latestVersion,
+        versions: resolvedApp.catalogApp.versions || resolvedApp.appMeta.versions,
+        tags: resolvedApp.catalogApp.tags,
+        source: catalogAppArg.source,
+        resolvedSource: resolvedApp.catalogApp.resolvedSource,
+      };
+    }
+
+    this.sourceAppCache.set(cacheKey, resolvedApp);
+    return resolvedApp;
+  }
+
+  private async resolveServezoneCatalogManifest(
+    manifestArg: IServezoneCatalogManifest,
+    resolvedSourceArg: IResolvedCatalogSource,
+  ): Promise<IResolvedSourceApp> {
+    if (!manifestArg || typeof manifestArg !== 'object') {
+      throw new Error('Manifest must be an object');
+    }
+    if (manifestArg.schemaVersion !== 1) {
+      throw new Error(`Unsupported manifest schemaVersion '${manifestArg.schemaVersion}'`);
+    }
+    if (!manifestArg.app?.id || !manifestArg.app?.name) {
+      throw new Error('Manifest app.id and app.name are required');
+    }
+
+    const configsByVersion = new Map<string, IAppVersionConfig>();
+    const versions: string[] = [];
+    const sourceVersionToResolvedVersion = new Map<string, string>();
+
+    for (const versionArg of manifestArg.versions || []) {
+      const sourceVersion = versionArg.version;
+      const { version: _version, ...versionConfig } = versionArg;
+      const config: IAppVersionConfig = {
+        ...versionConfig,
+        source: versionConfig.source || manifestArg.source,
+        resolvedSource: resolvedSourceArg,
+      };
+      await this.resolveConfigSource(config, sourceVersion);
+      const resolvedVersion = config.catalogVersion || sourceVersion;
+      config.catalogVersion = resolvedVersion;
+      this.validateAppVersionConfig(config, `${manifestArg.app.id}@${resolvedVersion}`);
+      configsByVersion.set(resolvedVersion, config);
+      configsByVersion.set(sourceVersion, config);
+      versions.push(resolvedVersion);
+      sourceVersionToResolvedVersion.set(sourceVersion, resolvedVersion);
+    }
+
+    if (manifestArg.runtime) {
+      const sourceVersion = manifestArg.latestVersion || manifestArg.channel || 'latest';
+      const config: IAppVersionConfig = {
+        ...manifestArg.runtime,
+        source: manifestArg.runtime.source || manifestArg.source,
+        resolvedSource: resolvedSourceArg,
+      };
+      await this.resolveConfigSource(config, sourceVersion);
+      const resolvedVersion = config.catalogVersion || sourceVersion;
+      config.catalogVersion = resolvedVersion;
+      this.validateAppVersionConfig(config, `${manifestArg.app.id}@${resolvedVersion}`);
+      configsByVersion.set(resolvedVersion, config);
+      configsByVersion.set(sourceVersion, config);
+      versions.push(resolvedVersion);
+      sourceVersionToResolvedVersion.set(sourceVersion, resolvedVersion);
+    }
+
+    if (configsByVersion.size === 0) {
+      throw new Error('Manifest must define at least one runtime config or version');
+    }
+
+    const selectedChannel = manifestArg.policy?.defaultChannel || manifestArg.channel || 'stable';
+    const channelVersion = manifestArg.channels?.[selectedChannel];
+    const declaredLatestVersion = manifestArg.latestVersion || channelVersion || versions[versions.length - 1];
+    const latestVersion = sourceVersionToResolvedVersion.get(declaredLatestVersion) || declaredLatestVersion;
+    const uniqueVersions = this.uniqueStrings(versions);
+
+    const catalogApp: ICatalogApp = {
+      id: manifestArg.app.id,
+      name: manifestArg.app.name,
+      description: manifestArg.app.description,
+      category: manifestArg.app.category,
+      iconName: manifestArg.app.iconName,
+      iconUrl: manifestArg.app.iconUrl,
+      latestVersion,
+      versions: uniqueVersions,
+      tags: manifestArg.app.tags,
+      channel: selectedChannel,
+      source: manifestArg.source,
+      upgradeStrategy: this.getUpgradeStrategyForConfig(configsByVersion.get(latestVersion)),
+      resolvedSource: resolvedSourceArg,
+    };
+
+    const appMeta: IAppMeta = {
+      id: manifestArg.app.id,
+      name: manifestArg.app.name,
+      description: manifestArg.app.description,
+      category: manifestArg.app.category,
+      iconName: manifestArg.app.iconName,
+      latestVersion,
+      versions: uniqueVersions,
+      maintainer: manifestArg.app.maintainer,
+      links: manifestArg.app.links,
+      tags: manifestArg.app.tags,
+      source: manifestArg.source,
+      resolvedSource: resolvedSourceArg,
+    };
+
+    return { catalogApp, appMeta, configsByVersion };
+  }
+
+  private async resolveConfigSource(configArg: IAppVersionConfig, versionArg: string): Promise<void> {
+    if (configArg.source?.type === 'dockerImage') {
+      await this.applyDockerImageSourceToConfig(configArg.source, configArg, versionArg);
+    }
+  }
+
+  private async applyDockerImageSourceToConfig(
+    sourceArg: IAppCatalogDockerImageSource,
+    configArg: IAppVersionConfig,
+    versionArg: string,
+  ): Promise<IAppVersionConfig> {
+    configArg.image = sourceArg.image;
+    configArg.source = sourceArg;
+
+    const resolvedSource = await this.resolveDockerImageSource(sourceArg);
+    configArg.resolvedSource = resolvedSource;
+    configArg.resolvedImageDigest = resolvedSource.imageDigest;
+    configArg.upgradeStrategy = sourceArg.tracking === 'digest' ? 'dockerDigest' : configArg.upgradeStrategy;
+    configArg.catalogVersion = this.createCatalogVersionForDockerSource(
+      sourceArg,
+      versionArg,
+      resolvedSource.imageDigest,
+    );
+
+    return configArg;
+  }
+
+  private async resolveDockerImageSource(
+    sourceArg: IAppCatalogDockerImageSource,
+  ): Promise<IResolvedCatalogSource> {
+    let imageDigest: string | undefined;
+    if (sourceArg.tracking === 'digest' && this.resolveDockerDigests) {
+      imageDigest = await this.resolveDockerImageDigest(sourceArg.image) || undefined;
+    }
+
+    return {
+      type: 'dockerImage',
+      image: sourceArg.image,
+      imageDigest,
+      resolvedAt: new Date().toISOString(),
+    };
+  }
+
+  private createAppMetaFromCatalogApp(appArg: ICatalogApp): IAppMeta {
+    return {
+      id: appArg.id,
+      name: appArg.name,
+      description: appArg.description,
+      category: appArg.category,
+      iconName: appArg.iconName,
+      latestVersion: appArg.latestVersion,
+      versions: appArg.versions || [appArg.latestVersion],
+      tags: appArg.tags,
+      source: appArg.source,
+      resolvedSource: appArg.resolvedSource,
+    };
+  }
+
+  private async getCatalogApp(appIdArg: string): Promise<ICatalogApp | undefined> {
+    const catalog = await this.getCatalog();
+    return catalog.apps.find((appArg) => appArg.id === appIdArg);
+  }
+
+  private getUpgradeStrategyForConfig(configArg?: IAppVersionConfig): ICatalogApp['upgradeStrategy'] {
+    if (configArg?.upgradeStrategy) return configArg.upgradeStrategy;
+    if (configArg?.source?.type === 'dockerImage' && configArg.source.tracking === 'digest') return 'dockerDigest';
+    return undefined;
+  }
+
+  private createCatalogVersionForDockerSource(
+    sourceArg: IAppCatalogDockerImageSource,
+    fallbackVersionArg: string,
+    digestArg?: string,
+  ): string {
+    if (sourceArg.tracking !== 'digest' || !digestArg) {
+      return fallbackVersionArg;
+    }
+    const parsedImage = this.parseDockerImageReference(sourceArg.image);
+    return `${parsedImage.tag}@${digestArg}`;
+  }
+
+  private async resolveDockerImageDigest(imageArg: string): Promise<string | null> {
+    try {
+      const parsedImage = this.parseDockerImageReference(imageArg);
+      if (parsedImage.digest) {
+        return parsedImage.digest;
+      }
+      return await this.fetchDockerManifestDigest(parsedImage);
+    } catch (error) {
+      logger.warn(`Failed to resolve Docker image digest for '${imageArg}': ${getErrorMessage(error)}`);
+      return null;
+    }
+  }
+
+  private parseDockerImageReference(imageArg: string): IParsedDockerImageReference {
+    const [imageWithoutDigest, digest] = imageArg.split('@');
+    const imageParts = imageWithoutDigest.split('/');
+    const firstPart = imageParts[0];
+    const hasExplicitRegistry = firstPart.includes('.') || firstPart.includes(':') || firstPart === 'localhost';
+    const registry = hasExplicitRegistry ? firstPart : 'registry-1.docker.io';
+    const repositoryParts = hasExplicitRegistry ? imageParts.slice(1) : imageParts;
+    let repositoryWithTag = repositoryParts.join('/');
+    if (!repositoryWithTag) {
+      throw new Error(`Invalid Docker image reference '${imageArg}'`);
+    }
+
+    if (!hasExplicitRegistry && !repositoryWithTag.includes('/')) {
+      repositoryWithTag = `library/${repositoryWithTag}`;
+    }
+
+    const lastSlashIndex = repositoryWithTag.lastIndexOf('/');
+    const lastColonIndex = repositoryWithTag.lastIndexOf(':');
+    const hasTag = lastColonIndex > lastSlashIndex;
+    const repository = hasTag ? repositoryWithTag.slice(0, lastColonIndex) : repositoryWithTag;
+    const tag = hasTag ? repositoryWithTag.slice(lastColonIndex + 1) : 'latest';
+
+    return { registry, repository, tag, digest };
+  }
+
+  private async fetchDockerManifestDigest(imageArg: IParsedDockerImageReference): Promise<string | null> {
+    const manifestUrl = `https://${imageArg.registry}/v2/${imageArg.repository}/manifests/${imageArg.tag}`;
+    const headers = new Headers({
+      Accept: [
+        'application/vnd.docker.distribution.manifest.v2+json',
+        'application/vnd.oci.image.manifest.v1+json',
+        'application/vnd.docker.distribution.manifest.list.v2+json',
+        'application/vnd.oci.image.index.v1+json',
+      ].join(', '),
+    });
+
+    let response = await this.fetchRef(manifestUrl, { method: 'HEAD', headers });
+    if (response.status === 401) {
+      const authHeader = response.headers.get('www-authenticate');
+      const token = authHeader ? await this.fetchDockerRegistryToken(authHeader, imageArg.repository) : null;
+      if (token) {
+        headers.set('Authorization', `Bearer ${token}`);
+        response = await this.fetchRef(manifestUrl, { method: 'HEAD', headers });
+      }
+    }
+
+    if (!response.ok || !response.headers.get('docker-content-digest')) {
+      response = await this.fetchRef(manifestUrl, { method: 'GET', headers });
+    }
+
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status} while resolving ${imageArg.repository}:${imageArg.tag}`);
+    }
+
+    return response.headers.get('docker-content-digest');
+  }
+
+  private async fetchDockerRegistryToken(authHeaderArg: string, repositoryArg: string): Promise<string | null> {
+    const match = authHeaderArg.match(/^Bearer\s+(.+)$/i);
+    if (!match) return null;
+
+    const authParams = new Map<string, string>();
+    for (const partArg of match[1].match(/(?:[^,\"]+|\"[^\"]*\")+/g) || []) {
+      const [key, rawValue] = partArg.split('=');
+      if (!key || rawValue === undefined) continue;
+      authParams.set(key.trim(), rawValue.trim().replace(/^\"|\"$/g, ''));
+    }
+
+    const realm = authParams.get('realm');
+    if (!realm) return null;
+    const tokenUrl = new URL(realm);
+    const service = authParams.get('service');
+    const scope = authParams.get('scope') || `repository:${repositoryArg}:pull`;
+    if (service) tokenUrl.searchParams.set('service', service);
+    tokenUrl.searchParams.set('scope', scope);
+
+    const response = await this.fetchRef(tokenUrl.toString());
+    if (!response.ok) return null;
+    const tokenResponse = await response.json() as { token?: string; access_token?: string };
+    return tokenResponse.token || tokenResponse.access_token || null;
+  }
+
+  private async createSha256Hex(inputArg: string): Promise<string> {
+    const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(inputArg));
+    return Array.from(new Uint8Array(digest))
+      .map((byteArg) => byteArg.toString(16).padStart(2, '0'))
+      .join('');
+  }
+
+  private uniqueStrings(valuesArg: string[]): string[] {
+    return Array.from(new Set(valuesArg.filter(Boolean)));
+  }
+
+  private withoutUndefined<T extends object>(objectArg: T): Partial<T> {
+    return Object.fromEntries(
+      Object.entries(objectArg).filter(([, valueArg]) => valueArg !== undefined),
+    ) as Partial<T>;
+  }
+
+  private async fetchTextFromUrl(urlArg: string): Promise<string> {
+    const response = await this.fetchRef(urlArg);
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status} for ${urlArg}`);
+    }
+    return response.text();
+  }
+
   /**
    * Fetch JSON from the remote repo
    */
   private async fetchJson(path: string): Promise<unknown> {
     const url = `${this.repoBaseUrl}/${path}`;
-    const response = await fetch(url);
+    const response = await this.fetchRef(url);
     if (!response.ok) {
       throw new Error(`HTTP ${response.status} for ${url}`);
     }
@@ -382,7 +870,7 @@ export class AppStoreManager {
    */
   private async fetchText(path: string): Promise<string> {
     const url = `${this.repoBaseUrl}/${path}`;
-    const response = await fetch(url);
+    const response = await this.fetchRef(url);
     if (!response.ok) {
       throw new Error(`HTTP ${response.status} for ${url}`);
     }
@@ -408,7 +896,7 @@ export class AppStoreManager {
     if (!configArg.image || typeof configArg.image !== 'string') {
       throw new Error(`Invalid ${labelArg}: image is required`);
     }
-    if (configArg.image.endsWith(':latest')) {
+    if (configArg.image.endsWith(':latest') && !configArg.resolvedImageDigest) {
       logger.warn(`App template ${labelArg} uses a mutable ':latest' image tag`);
     }
     this.assertValidPort(configArg.port, `${labelArg} port`);

ts/classes/external-gateway.ts

@@ -1,11 +1,17 @@
 import * as plugins from '../plugins.ts';
 import { logger } from '../logging.ts';
 import { getErrorMessage } from '../utils/error.ts';
+import { normalizeHostname } from '../utils/domain.ts';
 import { OneboxDatabase } from './database.ts';
 import type { IDomain, IService } from '../types.ts';
 import type { TDcRouterMode } from './managed-dcrouter.ts';
 
+const adminUiRouteName = 'onebox-admin-ui';
+
 type TWorkHosterType = 'onebox';
+type TExternalGatewayRoute = Pick<IService, 'id' | 'name' | 'domain' | 'status'> & {
+  domain: string;
+};
 
 interface IExternalGatewayConfig {
   url: string;
@@ -137,15 +143,34 @@ export class ExternalGatewayManager {
   }
 
   public async syncServiceRoutes(): Promise<void> {
+    const adminUiRoute = this.getAdminUiRoute();
+    const adminUiDomain = adminUiRoute?.domain;
     const services = this.database.getAllServices()
-      .filter((service) => service.domain && service.status === 'running');
+      .filter((service) =>
+        service.domain && service.status === 'running' && service.domain !== adminUiDomain
+      );
     const activeHostnames = new Set(services.map((service) => service.domain!));
 
+    if (adminUiRoute) {
+      activeHostnames.add(adminUiRoute.domain);
+      try {
+        await this.syncGatewayRoute(adminUiRoute);
+      } catch (error) {
+        logger.warn(
+          `Failed to sync external gateway route for ${adminUiRoute.domain}: ${
+            getErrorMessage(error)
+          }`,
+        );
+      }
+    }
+
     for (const service of services) {
       try {
         await this.syncServiceRoute(service);
       } catch (error) {
-        logger.warn(`Failed to sync external gateway route for ${service.domain}: ${getErrorMessage(error)}`);
+        logger.warn(
+          `Failed to sync external gateway route for ${service.domain}: ${getErrorMessage(error)}`,
+        );
       }
     }
 
@@ -158,6 +183,7 @@ export class ExternalGatewayManager {
 
     for (const record of records) {
       if (!record.hostname || activeHostnamesArg.has(record.hostname)) continue;
+      if (this.shouldPreserveUnconfiguredAdminUiRecord(record)) continue;
       if (!record.routeId && !record.appId && !record.serviceName) continue;
       staleRecordsByHostname.set(record.hostname, record);
     }
@@ -169,7 +195,11 @@ export class ExternalGatewayManager {
           domain: record.hostname,
         });
       } catch (error) {
-        logger.warn(`Failed to delete stale external gateway route for ${record.hostname}: ${getErrorMessage(error)}`);
+        logger.warn(
+          `Failed to delete stale external gateway route for ${record.hostname}: ${
+            getErrorMessage(error)
+          }`,
+        );
       }
     }
   }
@@ -289,40 +319,72 @@ export class ExternalGatewayManager {
   public async syncServiceRoute(service: IService): Promise<void> {
     if (!service.domain) return;
 
+    await this.syncGatewayRoute({
+      id: service.id,
+      name: service.name,
+      domain: service.domain,
+      status: service.status,
+    });
+  }
+
+  public async syncAdminUiRoute(): Promise<void> {
+    const route = this.getAdminUiRoute();
+    if (!route) return;
+    await this.syncGatewayRoute(route);
+  }
+
+  public async deleteAdminUiRoute(domain: string): Promise<void> {
+    const normalizedDomain = normalizeHostname(domain);
+    if (!normalizedDomain) return;
+    await this.deleteServiceRoute({
+      name: adminUiRouteName,
+      domain: normalizedDomain,
+    });
+  }
+
+  private async syncGatewayRoute(route: TExternalGatewayRoute): Promise<void> {
+    if (!route.domain) return;
+
     const config = await this.getConfig({ requireTarget: true });
     if (!config) return;
 
     const result = await this.fireDcRouterRequest<IWorkAppRouteSyncResult>(
       'syncGatewayClientRoute',
       {
-        ownership: this.buildGatewayClientOwnership(service, service.domain, config),
+        ownership: this.buildGatewayClientOwnership(route, route.domain, config),
-        route: this.buildRoute(service, config),
+        route: this.buildRoute(route, config),
-        enabled: service.status === 'running',
+        enabled: route.status === 'running',
       },
       config,
     ).catch(async () => {
       return await this.fireDcRouterRequest<IWorkAppRouteSyncResult>(
         'syncWorkAppRoute',
         {
-          ownership: this.buildOwnership(service, service.domain!, config),
+          ownership: this.buildOwnership(route, route.domain, config),
-          route: this.buildRoute(service, config),
+          route: this.buildRoute(route, config),
-          enabled: service.status === 'running',
+          enabled: route.status === 'running',
         },
         config,
       );
     });
 
     if (!result.success) {
-      throw new Error(result.message || `dcrouter route sync failed for ${service.domain}`);
+      throw new Error(result.message || `dcrouter route sync failed for ${route.domain}`);
     }
 
-    logger.success(`External gateway route ${result.action || 'synced'} for ${service.domain}`);
+    logger.success(`External gateway route ${result.action || 'synced'} for ${route.domain}`);
-    await this.importCertificateForDomain(service.domain).catch((error) => {
+    await this.importCertificateForDomain(route.domain).catch((error) => {
-      logger.debug(`External gateway certificate import skipped for ${service.domain}: ${getErrorMessage(error)}`);
+      logger.debug(
+        `External gateway certificate import skipped for ${route.domain}: ${
+          getErrorMessage(error)
+        }`,
+      );
     });
   }
 
-  public async deleteServiceRoute(service: Pick<IService, 'id' | 'name' | 'domain'>): Promise<void> {
+  public async deleteServiceRoute(
+    service: Pick<IService, 'id' | 'name' | 'domain'>,
+  ): Promise<void> {
     if (!service.domain) return;
 
     const config = await this.getConfig({ requireTarget: false });
@@ -536,12 +598,35 @@ export class ExternalGatewayManager {
     return ownership;
   }
 
-  private buildRoute(service: IService, config: IExternalGatewayConfig): IDcRouterRouteConfig {
+  private getAdminUiRoute(): TExternalGatewayRoute | null {
+    const domain = normalizeHostname(this.database.getSetting('adminUiDomain') || '');
+    if (!domain) return null;
     return {
-      name: this.routeName(service.domain!),
+      id: 0,
+      name: adminUiRouteName,
+      domain,
+      status: 'running',
+    };
+  }
+
+  private isAdminUiRecord(record: IGatewayDnsRecord): boolean {
+    const ownerName = record.serviceName || record.appId;
+    return ownerName === adminUiRouteName || ownerName === 'onebox';
+  }
+
+  private shouldPreserveUnconfiguredAdminUiRecord(record: IGatewayDnsRecord): boolean {
+    return this.database.getSetting('adminUiDomain') === null && this.isAdminUiRecord(record);
+  }
+
+  private buildRoute(
+    route: TExternalGatewayRoute,
+    config: IExternalGatewayConfig,
+  ): IDcRouterRouteConfig {
+    return {
+      name: this.routeName(route.domain),
       match: {
         ports: [443],
-        domains: [service.domain!],
+        domains: [route.domain],
       },
       action: {
         type: 'forward',

ts/classes/onebox.ts

@@ -5,6 +5,7 @@
  */
 
 import { logger } from '../logging.ts';
+import { projectInfo } from '../info.ts';
 import { getErrorMessage } from '../utils/error.ts';
 import { hashPassword } from '../utils/auth.ts';
 import { OneboxDatabase } from './database.ts';
@@ -26,6 +27,7 @@ import { BackupManager } from './backup-manager.ts';
 import { BackupScheduler } from './backup-scheduler.ts';
 import { ExternalGatewayManager } from './external-gateway.ts';
 import { ManagedDcRouterManager } from './managed-dcrouter.ts';
+import { OneboxUpdateManager } from './update-manager.ts';
 import { OpsServer } from '../opsserver/index.ts';
 
 export class Onebox {
@@ -48,6 +50,7 @@ export class Onebox {
   public backupScheduler: BackupScheduler;
   public managedDcRouter: ManagedDcRouterManager;
   public externalGateway: ExternalGatewayManager;
+  public updateManager: OneboxUpdateManager;
   public opsServer: OpsServer;
 
   private initialized = false;
@@ -93,6 +96,7 @@ export class Onebox {
     // Initialize optional dcrouter gateway integration
     this.managedDcRouter = new ManagedDcRouterManager(this);
     this.externalGateway = new ExternalGatewayManager(this);
+    this.updateManager = new OneboxUpdateManager();
 
     // Initialize OpsServer (TypedRequest-based server)
     this.opsServer = new OpsServer(this);
@@ -305,6 +309,7 @@ export class Onebox {
       const proxyStatus = this.reverseProxy.getStatus();
       const dnsConfigured = this.dns.isConfigured();
       const sslConfigured = this.ssl.isConfigured();
+      const oneboxUpdate = await this.updateManager.getUpdateStatus();
 
       const services = this.services.listServices();
       const runningServices = services.filter((s) => s.status === 'running').length;
@@ -407,6 +412,10 @@ export class Onebox {
       }
 
       return {
+        onebox: {
+          version: projectInfo.version,
+          update: oneboxUpdate,
+        },
         docker: {
           running: dockerRunning,
           version: dockerRunning ? await this.docker.getDockerVersion() : null,

ts/classes/reverseproxy.ts

@@ -10,15 +10,20 @@
 
 import { logger } from '../logging.ts';
 import { getErrorMessage } from '../utils/error.ts';
+import { normalizeHostname } from '../utils/domain.ts';
 import { OneboxDatabase } from './database.ts';
 import { SmartProxyManager } from './smartproxy.ts';
 
+const adminUiRouteName = 'onebox-admin-ui';
+const adminUiPort = 3000;
+
 interface IProxyRoute {
   domain: string;
   targetHost: string;
   targetPort: number;
-  serviceId: number;
+  serviceId?: number;
   serviceName?: string;
+  routeType: 'service' | 'admin-ui';
 }
 
 export class OneboxReverseProxy {
@@ -112,6 +117,7 @@ export class OneboxReverseProxy {
         targetPort,
         serviceId,
         serviceName,
+        routeType: 'service',
       };
 
       this.routes.set(domain, route);
@@ -127,6 +133,25 @@ export class OneboxReverseProxy {
     }
   }
 
+  async addAdminUiRoute(domain: string): Promise<void> {
+    const normalizedDomain = normalizeHostname(domain);
+    if (!normalizedDomain) return;
+
+    const targetHost = this.getAdminUiTargetHost();
+    const route: IProxyRoute = {
+      domain: normalizedDomain,
+      targetHost,
+      targetPort: adminUiPort,
+      serviceName: adminUiRouteName,
+      routeType: 'admin-ui',
+    };
+
+    this.routes.set(normalizedDomain, route);
+    const upstream = `${targetHost}:${adminUiPort}`;
+    await this.smartProxy.addRoute(normalizedDomain, upstream);
+    logger.success(`Added Admin UI proxy route: ${normalizedDomain} -> ${upstream}`);
+  }
+
   /**
    * Remove a route
    */
@@ -166,6 +191,11 @@ export class OneboxReverseProxy {
         }
       }
 
+      const adminUiDomain = this.getAdminUiDomain();
+      if (adminUiDomain) {
+        await this.addAdminUiRoute(adminUiDomain);
+      }
+
       logger.success(`Loaded ${this.routes.size} proxy routes`);
     } catch (error) {
       logger.error(`Failed to reload routes: ${getErrorMessage(error)}`);
@@ -173,6 +203,18 @@ export class OneboxReverseProxy {
     }
   }
 
+  private getAdminUiDomain(): string {
+    return normalizeHostname(this.database.getSetting('adminUiDomain') || '');
+  }
+
+  private getAdminUiTargetHost(): string {
+    const serverIP = this.database.getSetting('serverIP');
+    if (!serverIP) {
+      logger.warn('serverIP is not configured; Admin UI proxy route will use host.docker.internal');
+    }
+    return serverIP || 'host.docker.internal';
+  }
+
   /**
    * Add TLS certificate for a domain
    * Sends PEM content to SmartProxy via Admin API

ts/classes/services.ts

@@ -107,6 +107,7 @@ export class OneboxServicesManager {
         registryRepository: options.useOneboxRegistry ? options.name : undefined,
         registryImageTag: options.registryImageTag || 'latest',
         autoUpdateOnPush: options.autoUpdateOnPush,
+        imageDigest: options.imageDigest,
         // Platform requirements
         platformRequirements,
         // App Store template tracking

ts/classes/smartproxy.ts

@@ -10,7 +10,7 @@ import { logger } from '../logging.ts';
 import { getErrorMessage } from '../utils/error.ts';
 
 const SMARTPROXY_SERVICE_NAME = 'onebox-smartproxy';
-const LEGACY_CADDY_SERVICE_NAME = 'onebox-caddy';
+const LEGACY_REVERSE_PROXY_SERVICE_NAME = 'onebox-caddy';
 const SMARTPROXY_IMAGE = 'code.foss.global/host.today/ht-docker-smartproxy:latest';
 const SMARTPROXY_ADMIN_CONTAINER_PORT = 3000;
 const SMARTPROXY_HTTP_CONTAINER_PORT = 80;
@@ -102,10 +102,12 @@ export class SmartProxyManager {
 
       logger.info('Starting SmartProxy Docker service...');
 
-      const legacyService = await this.getExistingService(LEGACY_CADDY_SERVICE_NAME);
+      const legacyService = await this.getExistingService(LEGACY_REVERSE_PROXY_SERVICE_NAME);
       if (legacyService) {
-        logger.info('Legacy Caddy service exists, removing it before SmartProxy startup...');
+        logger.info(
-        await this.removeService(LEGACY_CADDY_SERVICE_NAME);
+          `Legacy reverse proxy service ${LEGACY_REVERSE_PROXY_SERVICE_NAME} exists, removing it before SmartProxy startup...`,
+        );
+        await this.removeService(LEGACY_REVERSE_PROXY_SERVICE_NAME);
         await new Promise((resolve) => setTimeout(resolve, 2000));
       }
 

ts/classes/update-manager.ts

@@ -0,0 +1,214 @@
+import { logger } from '../logging.ts';
+import { projectInfo } from '../info.ts';
+import { getErrorMessage } from '../utils/error.ts';
+import * as interfaces from '../../ts_interfaces/index.ts';
+
+const ONEBOX_REPOSITORY_URL = 'https://code.foss.global/serve.zone/onebox';
+const ONEBOX_LATEST_RELEASE_API_URL =
+  'https://code.foss.global/api/v1/repos/serve.zone/onebox/releases/latest';
+const ONEBOX_INSTALL_SCRIPT_URL = `${ONEBOX_REPOSITORY_URL}/raw/branch/main/install.sh`;
+const ONEBOX_CHANGELOG_URL = `${ONEBOX_REPOSITORY_URL}/src/branch/main/changelog.md`;
+const UPGRADE_LOG_PATH = '/var/log/onebox-upgrade.log';
+
+interface IGiteaReleaseResponse {
+  tag_name?: unknown;
+  html_url?: unknown;
+}
+
+interface IParsedRelease {
+  tagName: string;
+  releaseUrl: string;
+}
+
+export class OneboxUpdateManager {
+  private cachedStatus: interfaces.data.IOneboxUpdateStatus | null = null;
+  private cachedStatusExpiresAt = 0;
+  private upgradeStartedAt = 0;
+  private readonly statusCacheTtlMs = 5 * 60 * 1000;
+
+  public async getUpdateStatus(
+    optionsArg: { force?: boolean } = {},
+  ): Promise<interfaces.data.IOneboxUpdateStatus> {
+    const now = Date.now();
+    if (!optionsArg.force && this.cachedStatus && this.cachedStatusExpiresAt > now) {
+      return this.cachedStatus;
+    }
+
+    const status = await this.fetchUpdateStatus();
+    this.cachedStatus = status;
+    this.cachedStatusExpiresAt = now + this.statusCacheTtlMs;
+    return status;
+  }
+
+  public async startDetachedUpgrade(): Promise<interfaces.data.IOneboxUpgradeStartResult> {
+    this.assertRoot();
+
+    const status = await this.getUpdateStatus({ force: true });
+    this.assertUpdateCheckSucceeded(status);
+
+    const targetVersion = status.latestVersion || status.currentVersion;
+    if (!status.updateAvailable) {
+      return {
+        accepted: false,
+        currentVersion: status.currentVersion,
+        targetVersion,
+        message: 'Onebox is already up to date.',
+      };
+    }
+
+    if (this.upgradeStartedAt && Date.now() - this.upgradeStartedAt < 10 * 60 * 1000) {
+      return {
+        accepted: false,
+        currentVersion: status.currentVersion,
+        targetVersion,
+        message: 'A Onebox upgrade has already been started.',
+        logPath: UPGRADE_LOG_PATH,
+      };
+    }
+
+    const command = new Deno.Command('bash', {
+      args: ['-c', this.createDetachedUpgradeScript()],
+      stdin: 'null',
+      stdout: 'null',
+      stderr: 'null',
+      detached: true,
+    });
+    const child = command.spawn();
+    child.unref();
+    this.upgradeStartedAt = Date.now();
+
+    logger.info(`Started detached Onebox upgrade process ${child.pid}`);
+    return {
+      accepted: true,
+      currentVersion: status.currentVersion,
+      targetVersion,
+      message: 'Onebox upgrade started. The service will restart automatically.',
+      pid: child.pid,
+      logPath: UPGRADE_LOG_PATH,
+    };
+  }
+
+  public async runUpgradeForeground(
+    statusArg?: interfaces.data.IOneboxUpdateStatus,
+  ): Promise<interfaces.data.IOneboxUpgradeStartResult> {
+    this.assertRoot();
+
+    const status = statusArg || (await this.getUpdateStatus({ force: true }));
+    this.assertUpdateCheckSucceeded(status);
+
+    const targetVersion = status.latestVersion || status.currentVersion;
+    if (!status.updateAvailable) {
+      return {
+        accepted: false,
+        currentVersion: status.currentVersion,
+        targetVersion,
+        message: 'Onebox is already up to date.',
+      };
+    }
+
+    const installCommand = new Deno.Command('bash', {
+      args: ['-c', `curl -sSL ${ONEBOX_INSTALL_SCRIPT_URL} | bash`],
+      stdin: 'inherit',
+      stdout: 'inherit',
+      stderr: 'inherit',
+    });
+    const installResult = await installCommand.output();
+    if (!installResult.success) {
+      throw new Error('Upgrade failed');
+    }
+
+    return {
+      accepted: true,
+      currentVersion: status.currentVersion,
+      targetVersion,
+      message: `Upgraded to ${targetVersion}`,
+    };
+  }
+
+  private async fetchUpdateStatus(): Promise<interfaces.data.IOneboxUpdateStatus> {
+    const currentVersion = this.normalizeVersion(projectInfo.version);
+    const checkedAt = Date.now();
+
+    try {
+      const release = await this.fetchLatestRelease();
+      const latestVersion = this.normalizeVersion(release.tagName);
+      return {
+        currentVersion,
+        latestVersion,
+        updateAvailable: currentVersion !== latestVersion,
+        checkedAt,
+        releaseUrl: release.releaseUrl,
+        changelogUrl: ONEBOX_CHANGELOG_URL,
+      };
+    } catch (error) {
+      return {
+        currentVersion,
+        latestVersion: null,
+        updateAvailable: false,
+        checkedAt,
+        releaseUrl: `${ONEBOX_REPOSITORY_URL}/releases`,
+        changelogUrl: ONEBOX_CHANGELOG_URL,
+        error: getErrorMessage(error),
+      };
+    }
+  }
+
+  private async fetchLatestRelease(): Promise<IParsedRelease> {
+    const abortController = new AbortController();
+    const timeoutId = setTimeout(() => abortController.abort(), 5000);
+
+    try {
+      const response = await fetch(ONEBOX_LATEST_RELEASE_API_URL, {
+        headers: { accept: 'application/json' },
+        signal: abortController.signal,
+      });
+      if (!response.ok) {
+        throw new Error(`Failed to fetch latest release: HTTP ${response.status}`);
+      }
+
+      const release = await response.json() as IGiteaReleaseResponse;
+      if (typeof release.tag_name !== 'string' || !release.tag_name) {
+        throw new Error('Latest release response does not include a tag name');
+      }
+
+      const tagName = release.tag_name;
+      const releaseUrl = typeof release.html_url === 'string' && release.html_url
+        ? release.html_url
+        : `${ONEBOX_REPOSITORY_URL}/releases/tag/${this.normalizeVersion(tagName)}`;
+
+      return { tagName, releaseUrl };
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
+
+  private assertRoot(): void {
+    if (Deno.uid() !== 0) {
+      throw new Error('Onebox upgrades must be started as root. Try: sudo onebox upgrade');
+    }
+  }
+
+  private assertUpdateCheckSucceeded(statusArg: interfaces.data.IOneboxUpdateStatus): void {
+    if (statusArg.error) {
+      throw new Error(`Cannot determine latest Onebox release: ${statusArg.error}`);
+    }
+  }
+
+  private normalizeVersion(versionArg: string): string {
+    const trimmedVersion = versionArg.trim();
+    return trimmedVersion.startsWith('v') ? trimmedVersion : `v${trimmedVersion}`;
+  }
+
+  private createDetachedUpgradeScript(): string {
+    return `
+set -e
+mkdir -p /var/log
+{
+  echo "==== Onebox upgrade started $(date -Is) ===="
+  sleep 2
+  curl -sSL ${ONEBOX_INSTALL_SCRIPT_URL} | bash
+  echo "==== Onebox upgrade finished $(date -Is) ===="
+} >> ${UPGRADE_LOG_PATH} 2>&1
+`;
+  }
+}

ts/cli.ts

@@ -8,6 +8,7 @@ import { getErrorMessage } from './utils/error.ts';
 import { Onebox } from './classes/onebox.ts';
 import { OneboxDaemon } from './classes/daemon.ts';
 import { OneboxSystemd } from './classes/systemd.ts';
+import { OneboxUpdateManager } from './classes/update-manager.ts';
 import type { IAppVersionConfig } from './classes/appstore-types.ts';
 
 export async function runCli(): Promise<void> {
@@ -500,60 +501,29 @@ async function handleUpgradeCommand(): Promise<void> {
   logger.info('Checking for updates...');
 
   try {
-    // Get current version
+    const updateManager = new OneboxUpdateManager();
-    const currentVersion = projectInfo.version;
+    const status = await updateManager.getUpdateStatus({ force: true });
+    if (status.error) {
+      throw new Error(status.error);
+    }
 
-    // Fetch latest version from Gitea API
+    console.log(`  Current version: ${status.currentVersion}`);
-    const apiUrl = 'https://code.foss.global/api/v1/repos/serve.zone/onebox/releases/latest';
+    console.log(`  Latest version:  ${status.latestVersion}`);
-    const curlCmd = new Deno.Command('curl', {
-      args: ['-sSL', apiUrl],
-      stdout: 'piped',
-      stderr: 'piped',
-    });
-    const curlResult = await curlCmd.output();
-    const response = new TextDecoder().decode(curlResult.stdout);
-    const release = JSON.parse(response);
-    const latestVersion = release.tag_name as string; // e.g., "v1.11.0"
-
-    // Normalize versions for comparison (ensure both have "v" prefix)
-    const normalizedCurrent = currentVersion.startsWith('v')
-      ? currentVersion
-      : `v${currentVersion}`;
-    const normalizedLatest = latestVersion.startsWith('v')
-      ? latestVersion
-      : `v${latestVersion}`;
-
-    console.log(`  Current version: ${normalizedCurrent}`);
-    console.log(`  Latest version:  ${normalizedLatest}`);
     console.log('');
 
-    // Compare normalized versions
+    if (!status.updateAvailable) {
-    if (normalizedCurrent === normalizedLatest) {
       logger.success('Already up to date!');
       return;
     }
 
-    logger.info(`New version available: ${latestVersion}`);
+    logger.info(`New version available: ${status.latestVersion}`);
     logger.info('Downloading and installing...');
     console.log('');
 
-    // Download and run the install script
+    const upgrade = await updateManager.runUpgradeForeground(status);
-    const installUrl = 'https://code.foss.global/serve.zone/onebox/raw/branch/main/install.sh';
-    const installCmd = new Deno.Command('bash', {
-      args: ['-c', `curl -sSL ${installUrl} | bash`],
-      stdin: 'inherit',
-      stdout: 'inherit',
-      stderr: 'inherit',
-    });
-    const installResult = await installCmd.output();
-
-    if (!installResult.success) {
-      logger.error('Upgrade failed');
-      Deno.exit(1);
-    }
 
     console.log('');
-    logger.success(`Upgraded to ${latestVersion}`);
+    logger.success(upgrade.message);
   } catch (error) {
     logger.error(`Upgrade failed: ${getErrorMessage(error)}`);
     Deno.exit(1);

ts/database/migrations/migration-015-smartproxy-platform-service.ts

@@ -3,7 +3,7 @@ import type { TQueryFunction } from '../types.ts';
 
 export class Migration015SmartProxyPlatformService extends BaseMigration {
   readonly version = 15;
-  readonly description = 'Rename Caddy platform service to SmartProxy';
+  readonly description = 'Rename legacy reverse proxy platform service to SmartProxy';
 
   up(query: TQueryFunction): void {
     query(

ts/opsserver/handlers/settings.handler.ts

@@ -4,6 +4,7 @@ import * as interfaces from '../../../ts_interfaces/index.ts';
 import { requireAdminIdentity } from '../helpers/guards.ts';
 import { logger } from '../../logging.ts';
 import { getErrorMessage } from '../../utils/error.ts';
+import { isValidHostname, normalizeHostname } from '../../utils/domain.ts';
 
 export class SettingsHandler {
   public typedrouter = new plugins.typedrequest.TypedRouter();
@@ -23,6 +24,7 @@ export class SettingsHandler {
     return {
       cloudflareToken: cloudflareToken || '',
       cloudflareZoneId: settingsMap['cloudflareZoneId'] || '',
+      adminUiDomain: settingsMap['adminUiDomain'] || '',
       dcrouterMode: managedDcRouter.getMode(),
       dcrouterManagedImage: managedDcRouter.getImage(),
       dcrouterManagedOpsPort: managedDcRouter.getOpsPort(),
@@ -64,8 +66,10 @@ export class SettingsHandler {
           const db = this.opsServerRef.oneboxRef.database;
           const updates = dataArg.settings;
 
+          const normalizedUpdates = this.normalizeUpdates(updates);
+
           // Store each setting as key-value pair
-          for (const [key, value] of Object.entries(updates)) {
+          for (const [key, value] of Object.entries(normalizedUpdates)) {
             if (value !== undefined) {
               if (db.isSecretSettingKey(key)) {
                 await db.setSecretSetting(key, String(value));
@@ -75,8 +79,8 @@ export class SettingsHandler {
             }
           }
 
-          if (this.hasExternalGatewaySetting(updates)) {
+          if (this.hasRouteSyncSetting(normalizedUpdates)) {
-            this.refreshDcRouterGateway().catch((error) => {
+            this.refreshGatewayRoutes(normalizedUpdates).catch((error) => {
               logger.warn(`dcrouter gateway settings refresh failed: ${getErrorMessage(error)}`);
             });
           }
@@ -110,8 +114,23 @@ export class SettingsHandler {
     );
   }
 
-  private hasExternalGatewaySetting(settings: Partial<interfaces.data.ISettings>): boolean {
+  private normalizeUpdates(
+    settings: Partial<interfaces.data.ISettings>,
+  ): Partial<interfaces.data.ISettings> {
+    const normalizedUpdates = { ...settings };
+    if (Object.prototype.hasOwnProperty.call(normalizedUpdates, 'adminUiDomain')) {
+      const normalizedDomain = normalizeHostname(String(normalizedUpdates.adminUiDomain || ''));
+      if (!isValidHostname(normalizedDomain)) {
+        throw new plugins.typedrequest.TypedResponseError('Invalid Admin UI domain');
+      }
+      normalizedUpdates.adminUiDomain = normalizedDomain;
+    }
+    return normalizedUpdates;
+  }
+
+  private hasRouteSyncSetting(settings: Partial<interfaces.data.ISettings>): boolean {
     return [
+      'adminUiDomain',
       'dcrouterMode',
       'dcrouterManagedImage',
       'dcrouterManagedOpsPort',
@@ -127,23 +146,29 @@ export class SettingsHandler {
     ].some((key) => Object.prototype.hasOwnProperty.call(settings, key));
   }
 
-  private async refreshDcRouterGateway(): Promise<void> {
+  private hasManagedDcRouterRuntimeSetting(settings: Partial<interfaces.data.ISettings>): boolean {
+    return [
+      'dcrouterMode',
+      'dcrouterManagedImage',
+      'dcrouterManagedOpsPort',
+      'dcrouterManagedHttpPort',
+      'dcrouterManagedHttpsPort',
+      'dcrouterManagedDataDir',
+    ].some((key) => Object.prototype.hasOwnProperty.call(settings, key));
+  }
+
+  private async refreshGatewayRoutes(settings: Partial<interfaces.data.ISettings>): Promise<void> {
     const onebox = this.opsServerRef.oneboxRef;
+    if (this.hasManagedDcRouterRuntimeSetting(settings)) {
       if (onebox.managedDcRouter.getMode() === 'managed') {
         await onebox.managedDcRouter.restart();
       } else {
         await onebox.managedDcRouter.stop();
       }
+    }
 
+    await onebox.reverseProxy.reloadRoutes();
     await onebox.externalGateway.syncDomains();
-
+    await onebox.externalGateway.syncServiceRoutes();
-    const services = onebox.database.getAllServices().filter((service) => service.domain);
-    await Promise.all(services.map(async (service) => {
-      try {
-        await onebox.externalGateway.syncServiceRoute(service);
-      } catch (error) {
-        logger.warn(`Failed to sync external gateway route for ${service.domain}: ${getErrorMessage(error)}`);
-      }
-    }));
   }
 }

ts/opsserver/handlers/status.handler.ts

@@ -2,6 +2,7 @@ import * as plugins from '../../plugins.ts';
 import type { OpsServer } from '../classes.opsserver.ts';
 import * as interfaces from '../../../ts_interfaces/index.ts';
 import { requireAdminIdentity } from '../helpers/guards.ts';
+import { getErrorMessage } from '../../utils/error.ts';
 
 export class StatusHandler {
   public typedrouter = new plugins.typedrequest.TypedRouter();
@@ -22,5 +23,20 @@ export class StatusHandler {
         },
       ),
     );
+
+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_StartOneboxUpgrade>(
+        'startOneboxUpgrade',
+        async (dataArg) => {
+          await requireAdminIdentity(this.opsServerRef.adminHandler, dataArg);
+          try {
+            const upgrade = await this.opsServerRef.oneboxRef.updateManager.startDetachedUpgrade();
+            return { upgrade };
+          } catch (error) {
+            throw new plugins.typedrequest.TypedResponseError(getErrorMessage(error));
+          }
+        },
+      ),
+    );
   }
 }

ts/types.ts

@@ -280,6 +280,7 @@ export interface ISetting {
 // Application settings
 export interface IAppSettings {
   serverIP?: string;
+  adminUiDomain?: string;
   cloudflareToken?: string;
   cloudflareZoneId?: string;
   dcrouterMode?: 'managed' | 'external' | 'disabled';
@@ -332,6 +333,7 @@ export interface IServiceDeployOptions {
   useOneboxRegistry?: boolean;
   registryImageTag?: string;
   autoUpdateOnPush?: boolean;
+  imageDigest?: string;
   // Platform service requirements
   enableMongoDB?: boolean;
   enableS3?: boolean;

ts/utils/domain.ts

@@ -0,0 +1,17 @@
+export function normalizeHostname(valueArg: string): string {
+  const trimmedValue = valueArg.trim().toLowerCase();
+  if (!trimmedValue) return '';
+
+  const withoutProtocol = trimmedValue.replace(/^[a-z][a-z0-9+.-]*:\/\//, '');
+  const withoutPath = withoutProtocol.split('/')[0].split('?')[0].split('#')[0];
+  return withoutPath.replace(/:\d+$/, '').replace(/\.$/, '');
+}
+
+export function isValidHostname(hostnameArg: string): boolean {
+  if (!hostnameArg) return true;
+  if (hostnameArg.length > 253) return false;
+  return hostnameArg.split('.').every((label) => {
+    if (!label || label.length > 63) return false;
+    return /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/.test(label);
+  });
+}

ts_interfaces/data/settings.ts

@@ -21,6 +21,7 @@ export interface IManagedDcRouterStatus {
 export interface ISettings {
   cloudflareToken: string;
   cloudflareZoneId: string;
+  adminUiDomain: string;
   dcrouterMode: TDcRouterMode;
   dcrouterManagedImage: string;
   dcrouterManagedOpsPort: number;

ts_interfaces/data/system.ts

@@ -4,7 +4,30 @@
 
 import type { TPlatformServiceType, TPlatformServiceStatus } from './platform.ts';
 
+export interface IOneboxUpdateStatus {
+  currentVersion: string;
+  latestVersion: string | null;
+  updateAvailable: boolean;
+  checkedAt: number;
+  releaseUrl: string;
+  changelogUrl: string;
+  error?: string;
+}
+
+export interface IOneboxUpgradeStartResult {
+  accepted: boolean;
+  currentVersion: string;
+  targetVersion: string;
+  message: string;
+  pid?: number;
+  logPath?: string;
+}
+
 export interface ISystemStatus {
+  onebox: {
+    version: string;
+    update: IOneboxUpdateStatus;
+  };
   docker: {
     running: boolean;
     version: unknown;

ts_interfaces/requests/status.ts

@@ -13,3 +13,16 @@ export interface IReq_GetSystemStatus extends plugins.typedrequestInterfaces.imp
     status: data.ISystemStatus;
   };
 }
+
+export interface IReq_StartOneboxUpgrade extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_StartOneboxUpgrade
+> {
+  method: 'startOneboxUpgrade';
+  request: {
+    identity: data.IIdentity;
+  };
+  response: {
+    upgrade: data.IOneboxUpgradeStartResult;
+  };
+}

ts_web/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@serve.zone/onebox',
-  version: '1.28.0',
+  version: '1.31.0',
   description: 'Self-hosted container platform with automatic SSL and DNS - a mini Heroku for single servers'
 }

ts_web/elements/ob-app-shell.ts

@@ -41,6 +41,14 @@ export class ObAppShell extends DeesElement {
     refreshInterval: 30000,
   };
 
+  @state()
+  accessor systemState: appstate.ISystemState = {
+    status: null,
+  };
+
+  @state()
+  accessor globalMessages: plugins.deesCatalog.IGlobalMessage[] = [];
+
   @state()
   accessor loginLoading: boolean = false;
 
@@ -126,6 +134,8 @@ export class ObAppShell extends DeesElement {
   ];
 
   private resolvedViewTabs: IResolvedView[] = [];
+  private suppressedUpdateVersion = '';
+  private upgradeFlowRunning = false;
 
   constructor() {
     super();
@@ -135,12 +145,21 @@ export class ObAppShell extends DeesElement {
       .select((stateArg: appstate.ILoginState) => stateArg)
       .subscribe((loginState: appstate.ILoginState) => {
         this.loginState = loginState;
+        this.updateGlobalMessages();
         if (loginState.isLoggedIn) {
           appstate.systemStatePart.dispatchAction(appstate.fetchSystemStatusAction, null);
         }
       });
     this.rxSubscriptions.push(loginSubscription);
 
+    const systemSubscription = appstate.systemStatePart
+      .select((stateArg: appstate.ISystemState) => stateArg)
+      .subscribe((systemState: appstate.ISystemState) => {
+        this.systemState = systemState;
+        this.updateGlobalMessages();
+      });
+    this.rxSubscriptions.push(systemSubscription);
+
     const uiSubscription = appstate.uiStatePart
       .select((stateArg: appstate.IUiState) => stateArg)
       .subscribe((uiState: appstate.IUiState) => {
@@ -214,6 +233,7 @@ export class ObAppShell extends DeesElement {
             name="Onebox"
             .viewTabs=${this.resolvedViewTabs}
             .selectedView=${this.currentViewTab}
+            .globalMessages=${this.globalMessages}
           >
           </dees-simple-appdash>
         </dees-simple-login>
@@ -324,6 +344,177 @@ export class ObAppShell extends DeesElement {
     }
   }
 
+  private updateGlobalMessages(): void {
+    const updateStatus = this.systemState.status?.onebox.update;
+    if (
+      !this.loginState.isLoggedIn ||
+      !updateStatus?.updateAvailable ||
+      !updateStatus.latestVersion ||
+      updateStatus.latestVersion === this.suppressedUpdateVersion
+    ) {
+      this.globalMessages = [];
+      return;
+    }
+
+    this.globalMessages = [
+      {
+        id: `onebox-update-${updateStatus.latestVersion}`,
+        type: 'info',
+        icon: 'lucide:download',
+        message: `Onebox ${updateStatus.latestVersion} is available. Current version: ${updateStatus.currentVersion}.`,
+        dismissible: false,
+        actions: [
+          {
+            name: 'Update Now',
+            iconName: 'lucide:download',
+            action: () => this.startOneboxUpgradeFlow(),
+          },
+          {
+            name: 'Release Notes',
+            iconName: 'lucide:fileText',
+            action: () => this.openUpdateUrl(updateStatus.changelogUrl || updateStatus.releaseUrl),
+          },
+          {
+            name: 'Later',
+            iconName: 'lucide:clock',
+            action: () => {
+              this.suppressedUpdateVersion = updateStatus.latestVersion || '';
+              this.updateGlobalMessages();
+            },
+          },
+        ],
+      },
+    ];
+  }
+
+  private async startOneboxUpgradeFlow(): Promise<void> {
+    if (this.upgradeFlowRunning) {
+      return;
+    }
+
+    const identity = appstate.loginStatePart.getState().identity;
+    const updateStatus = this.systemState.status?.onebox.update;
+    if (!identity || !updateStatus?.latestVersion) {
+      return;
+    }
+
+    this.upgradeFlowRunning = true;
+    const updater = await plugins.deesCatalog.DeesUpdater.createAndShow({
+      currentVersion: updateStatus.currentVersion,
+      updatedVersion: updateStatus.latestVersion,
+      moreInfoUrl: updateStatus.releaseUrl,
+      changelogUrl: updateStatus.changelogUrl,
+      successAction: 'reload',
+      successDelayMs: 30000,
+      successActionLabel: 'Reloading Onebox UI',
+    });
+
+    try {
+      updater.updateProgress({
+        percentage: 10,
+        indeterminate: true,
+        statusText: 'Requesting upgrade...',
+        terminalLines: ['Requesting Onebox upgrade'],
+      });
+
+      const typedRequest = new plugins.domtools.plugins.typedrequest.TypedRequest<
+        interfaces.requests.IReq_StartOneboxUpgrade
+      >('/typedrequest', 'startOneboxUpgrade');
+      const response = await typedRequest.fire({ identity });
+
+      if (!response.upgrade.accepted) {
+        updater.markUpdateError(response.upgrade.message);
+        await this.delay(5000);
+        await updater.destroy();
+        return;
+      }
+
+      updater.appendProgressLine(response.upgrade.message);
+      if (response.upgrade.pid) {
+        updater.appendProgressLine(`Upgrade process PID: ${response.upgrade.pid}`);
+      }
+      if (response.upgrade.logPath) {
+        updater.appendProgressLine(`Upgrade log: ${response.upgrade.logPath}`);
+      }
+      updater.updateProgress({
+        percentage: 45,
+        indeterminate: true,
+        statusText: 'Installer started...',
+      });
+
+      await this.waitForOneboxUpgrade(updater, response.upgrade.targetVersion, identity);
+      await updater.markUpdateReady();
+    } catch (error) {
+      updater.markUpdateError(this.getErrorMessage(error));
+      await this.delay(5000);
+      await updater.destroy();
+    } finally {
+      this.upgradeFlowRunning = false;
+    }
+  }
+
+  private async waitForOneboxUpgrade(
+    updaterArg: plugins.deesCatalog.DeesUpdater,
+    targetVersionArg: string,
+    identityArg: interfaces.data.IIdentity,
+  ): Promise<void> {
+    const normalizedTargetVersion = this.normalizeVersion(targetVersionArg);
+    const timeoutAt = Date.now() + 90000;
+    let attempt = 0;
+
+    updaterArg.appendProgressLine('Waiting for Onebox to restart with the new version');
+    while (Date.now() < timeoutAt) {
+      await this.delay(5000);
+      attempt++;
+
+      try {
+        const typedRequest = new plugins.domtools.plugins.typedrequest.TypedRequest<
+          interfaces.requests.IReq_GetSystemStatus
+        >('/typedrequest', 'getSystemStatus');
+        const response = await typedRequest.fire({ identity: identityArg });
+        const onlineVersion = this.normalizeVersion(response.status.onebox.version);
+        updaterArg.appendProgressLine(`Onebox API answered with ${onlineVersion}`);
+
+        if (onlineVersion === normalizedTargetVersion) {
+          updaterArg.updateProgress({
+            percentage: 100,
+            indeterminate: false,
+            statusText: `Onebox ${normalizedTargetVersion} is online.`,
+          });
+          return;
+        }
+      } catch {
+        updaterArg.appendProgressLine('Onebox API is restarting...');
+      }
+
+      updaterArg.updateProgress({
+        percentage: Math.min(95, 45 + attempt * 5),
+        indeterminate: true,
+        statusText: `Waiting for Onebox ${normalizedTargetVersion}...`,
+      });
+    }
+
+    updaterArg.appendProgressLine('Timed out waiting for the version check; reloading the UI anyway');
+  }
+
+  private openUpdateUrl(urlArg: string): void {
+    window.open(urlArg, '_blank', 'noopener,noreferrer');
+  }
+
+  private async delay(millisecondsArg: number): Promise<void> {
+    const domtools = await this.domtoolsPromise;
+    await domtools.convenience.smartdelay.delayFor(millisecondsArg);
+  }
+
+  private getErrorMessage(errorArg: unknown): string {
+    return errorArg instanceof Error ? errorArg.message : String(errorArg);
+  }
+
+  private normalizeVersion(versionArg: string): string {
+    const trimmedVersion = versionArg.trim();
+    return trimmedVersion.startsWith('v') ? trimmedVersion : `v${trimmedVersion}`;
+  }
+
   private syncAppdashView(viewName: string, subviewName: string | null): void {
     const appDash = this.shadowRoot?.querySelector('dees-simple-appdash') as any;
     if (!appDash || this.resolvedViewTabs.length === 0) return;

ts_web/elements/ob-view-settings.ts

@@ -48,31 +48,45 @@ export class ObViewSettings extends DeesElement {
     cssManager.defaultStyles,
     shared.viewHostCss,
     css`
-      .gateway-card {
+      dees-tile {
+        display: block;
         margin-bottom: 24px;
-        border: 1px solid ${cssManager.bdTheme('#e4e4e7', '#27272a')};
-        border-radius: 12px;
-        background: ${cssManager.bdTheme('#ffffff', '#09090b')};
-        overflow: hidden;
-        box-shadow: 0 1px 2px ${cssManager.bdTheme('rgba(0,0,0,0.04)', 'rgba(0,0,0,0.2)')};
       }
 
       .gateway-header {
-        padding: 16px 20px;
+        height: 36px;
-        border-bottom: 1px solid ${cssManager.bdTheme('#f4f4f5', '#27272a')};
+        display: flex;
-        background: ${cssManager.bdTheme('#fafafa', '#101013')};
+        align-items: center;
+        padding: 0 16px;
+        width: 100%;
+        box-sizing: border-box;
+      }
+
+      .gateway-heading {
+        flex: 1;
+        display: flex;
+        align-items: baseline;
+        gap: 8px;
+        min-width: 0;
       }
 
       .gateway-title {
-        font-size: 15px;
+        font-size: 13px;
-        font-weight: 600;
+        font-weight: 500;
-        color: ${cssManager.bdTheme('#18181b', '#fafafa')};
+        letter-spacing: -0.01em;
+        color: var(--dees-color-text-secondary);
+        white-space: nowrap;
+        overflow: hidden;
+        text-overflow: ellipsis;
       }
 
       .gateway-subtitle {
-        margin-top: 4px;
+        font-size: 12px;
-        font-size: 13px;
+        color: var(--dees-color-text-muted);
-        color: ${cssManager.bdTheme('#71717a', '#a1a1aa')};
+        letter-spacing: -0.01em;
+        white-space: nowrap;
+        overflow: hidden;
+        text-overflow: ellipsis;
       }
 
       .gateway-content {
@@ -176,8 +190,51 @@ export class ObViewSettings extends DeesElement {
 
       .gateway-footer {
         display: flex;
+        flex-direction: row;
         justify-content: flex-end;
-        padding: 0 20px 20px;
+        align-items: center;
+        gap: 0;
+        height: 36px;
+        width: 100%;
+        box-sizing: border-box;
+      }
+
+      .tile-button {
+        padding: 0 16px;
+        height: 100%;
+        text-align: center;
+        font-size: 12px;
+        font-weight: 500;
+        cursor: pointer;
+        user-select: none;
+        transition: all 0.15s ease;
+        background: transparent;
+        border: none;
+        border-left: 1px solid var(--dees-color-border-subtle);
+        color: var(--dees-color-text-muted);
+        white-space: nowrap;
+        display: flex;
+        align-items: center;
+        gap: 6px;
+      }
+
+      .tile-button:first-child {
+        border-left: none;
+      }
+
+      .tile-button:hover {
+        background: var(--dees-color-hover);
+        color: var(--dees-color-text-primary);
+      }
+
+      .tile-button.primary {
+        color: ${cssManager.bdTheme('hsl(217.2 91.2% 59.8%)', 'hsl(213.1 93.9% 67.8%)')};
+        font-weight: 600;
+      }
+
+      .tile-button.primary:hover {
+        background: ${cssManager.bdTheme('hsl(217.2 91.2% 59.8% / 0.08)', 'hsl(213.1 93.9% 67.8% / 0.08)')};
+        color: ${cssManager.bdTheme('hsl(217.2 91.2% 50%)', 'hsl(213.1 93.9% 75%)')};
       }
 
       @media (max-width: 700px) {
@@ -201,12 +258,14 @@ export class ObViewSettings extends DeesElement {
   public render(): TemplateResult {
     return html`
       <ob-sectionheading>Settings</ob-sectionheading>
+      ${this.renderAdminUiSettings()}
       ${this.renderExternalGatewaySettings()}
       <sz-settings-view
         .settings=${this.settingsState.settings || {
           darkMode: true,
           cloudflareToken: '',
           cloudflareZoneId: '',
+          adminUiDomain: '',
           dcrouterMode: 'managed',
           dcrouterManagedImage: 'code.foss.global/serve.zone/dcrouter:latest',
           dcrouterManagedOpsPort: 3300,
@@ -244,14 +303,39 @@ export class ObViewSettings extends DeesElement {
     `;
   }
 
+  private renderAdminUiSettings(): TemplateResult {
+    const settings = this.settingsState.settings;
+    return html`
+      <dees-tile>
+        <div slot="header" class="gateway-header">
+          <div class="gateway-heading">
+            <span class="gateway-title">Onebox Admin UI</span>
+            <span class="gateway-subtitle">Configure the public hostname for this Onebox dashboard</span>
+          </div>
+        </div>
+        <div class="gateway-content">
+          ${this.renderGatewayInput('adminUiDomain', 'Admin UI Domain', settings?.adminUiDomain || '', 'Example: onebox.example.com. Leave empty to disable the public Admin UI route.')}
+          ${this.renderGatewayReadonly('Local Target', 'Onebox OpsServer on port 3000', 'The external gateway forwards to SmartProxy, which forwards this hostname to the Onebox Admin UI.')}
+        </div>
+        <div slot="footer" class="gateway-footer">
+          <button class="tile-button primary" type="button" @click=${() => this.saveAdminUiSettings()}>
+            Save Admin UI Domain
+          </button>
+        </div>
+      </dees-tile>
+    `;
+  }
+
   private renderExternalGatewaySettings(): TemplateResult {
     const settings = this.settingsState.settings;
     const mode = settings?.dcrouterMode || 'managed';
     return html`
-      <section class="gateway-card">
+      <dees-tile>
-        <div class="gateway-header">
+        <div slot="header" class="gateway-header">
-          <div class="gateway-title">dcrouter Gateway</div>
+          <div class="gateway-heading">
-          <div class="gateway-subtitle">Run a local managed dcrouter or delegate routing, DNS, and certificates to an external dcrouter.</div>
+            <span class="gateway-title">dcrouter Gateway</span>
+            <span class="gateway-subtitle">Run a local managed dcrouter or delegate routing to an external dcrouter</span>
+          </div>
         </div>
         <div class="gateway-mode-row">
           ${this.renderModeButton('managed', 'Managed Local', mode)}
@@ -277,15 +361,12 @@ export class ObViewSettings extends DeesElement {
             <div class="gateway-disabled">dcrouter route delegation is disabled. Onebox will keep using its local SmartProxy directly.</div>
           `}
         </div>
-        <div class="gateway-footer">
+        <div slot="footer" class="gateway-footer">
-          <dees-button
+          <button class="tile-button primary" type="button" @click=${() => this.saveExternalGatewaySettings()}>
-            .text=${'Save dcrouter Settings'}
+            Save dcrouter Settings
-            .type=${'default'}
+          </button>
-            .icon=${'lucide:Save'}
-            @click=${() => this.saveExternalGatewaySettings()}
-          ></dees-button>
         </div>
-      </section>
+      </dees-tile>
     `;
   }
 
@@ -329,7 +410,7 @@ export class ObViewSettings extends DeesElement {
     isPassword = false,
   ): TemplateResult {
     return html`
-      <div class="gateway-field ${key === 'dcrouterGatewayUrl' ? 'full' : ''}">
+      <div class="gateway-field ${key === 'dcrouterGatewayUrl' || key === 'adminUiDomain' ? 'full' : ''}">
         <dees-input-text
           .key=${key}
           .label=${label}
@@ -393,4 +474,15 @@ export class ObViewSettings extends DeesElement {
     });
     await appstate.settingsStatePart.dispatchAction(appstate.fetchManagedDcRouterStatusAction, null);
   }
+
+  private async saveAdminUiSettings(): Promise<void> {
+    const settings = this.settingsState.settings;
+    if (!settings) return;
+
+    await appstate.settingsStatePart.dispatchAction(appstate.updateSettingsAction, {
+      settings: {
+        adminUiDomain: settings.adminUiDomain || '',
+      },
+    });
+  }
 }