v1.30.1

fix(settings-ui): align settings gateway cards with dees-tile footer actions
v1.30.0
2026-05-24 17:42:02 +00:00 · 2026-05-24 17:41:34 +00:00 · 2026-05-24 14:46:51 +00:00 · 2026-05-24 14:46:35 +00:00 · 2026-05-24 11:50:10 +00:00 · 2026-05-24 11:49:43 +00:00
41 changed files with 2935 additions and 467 deletions
@@ -3,6 +3,57 @@
 ## Pending


+## 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
+
+- add enterprise-ready App Store runtime support for declared volumes and raw published ports
+  - validate app template schemas before install, fail invalid port/volume declarations early, and preserve declarations across upgrades and backups
+  - preflight Docker/host published port conflicts and back up declared service volume data
+  - show App Store volume mounts and raw host port exposure before deploy
+
+### Fixes
+
+- fix Onebox dashboard system metrics rendering and traffic polling
+- update `@serve.zone/catalog` to `^2.12.5`
+- preserve an existing managed dcrouter config file instead of rewriting it on container creation
+- remove stale external gateway routes during route reconciliation
+
 ## 2026-05-21 - 1.27.0

 ### Features
@@ -1,6 +1,6 @@
 {
  "name": "@serve.zone/onebox",
-  "version": "1.27.0",
+  "version": "1.30.1",
  "exports": "./mod.ts",
  "tasks": {
    "test": "deno test --allow-all test/",
@@ -1,6 +1,6 @@
 {
  "name": "@serve.zone/onebox",
-  "version": "1.27.0",
+  "version": "1.30.1",
  "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.4"
+    "@serve.zone/catalog": "^2.12.5"
  },
  "devDependencies": {
-    "@git.zone/tsbundle": "^2.10.1",
-    "@git.zone/tsdeno": "^1.3.1",
-    "@git.zone/tswatch": "^3.3.3"
+    "@git.zone/tsbundle": "^2.10.4",
+    "@git.zone/tsdeno": "^1.3.2",
+    "@git.zone/tswatch": "^3.3.5"
  },
-  "private": true,
-  "pnpm": {
-    "overrides": {}
-  }
+  "private": true
 }
@@ -0,0 +1,113 @@
+import { assertEquals, assertThrows } from '@std/assert';
+
+import { AppStoreManager } from '../ts/classes/appstore.ts';
+import { OneboxDockerManager } from '../ts/classes/docker.ts';
+import type { IAppVersionConfig } from '../ts/classes/appstore-types.ts';
+import type { IService } from '../ts/types.ts';
+
+const createAppStore = () => new AppStoreManager({} as any);
+
+const baseConfig: IAppVersionConfig = {
+  image: 'example/app:1.0.0',
+  port: 3000,
+  envVars: [
+    {
+      key: 'APP_PORT',
+      value: '3000',
+      description: 'Application port',
+      required: true,
+    },
+  ],
+};
+
+const baseService: IService = {
+  id: 1,
+  name: 'test-service',
+  image: 'example/app:1.0.0',
+  envVars: {},
+  port: 3000,
+  status: 'stopped',
+  createdAt: Date.now(),
+  updatedAt: Date.now(),
+};
+
+Deno.test('appstore normalizes and validates app template runtime fields', () => {
+  const appStore = createAppStore();
+
+  const normalizedVolumes = appStore.normalizeVolumes([
+    '/data/app',
+    { mountPath: '/config', readOnly: true },
+  ]);
+
+  assertEquals(normalizedVolumes, [
+    { mountPath: '/data/app' },
+    { mountPath: '/config', readOnly: true },
+  ]);
+
+  appStore.validateAppVersionConfig({
+    ...baseConfig,
+    volumes: normalizedVolumes,
+    publishedPorts: [
+      { targetPort: 3000, publishedPort: 3000, protocol: 'tcp' },
+      { targetPort: 20000, targetPortEnd: 20002, publishedPort: 20000, publishedPortEnd: 20002, protocol: 'udp' },
+    ],
+  });
+});
+
+Deno.test('appstore rejects invalid template ports and volumes', () => {
+  const appStore = createAppStore();
+
+  assertThrows(
+    () => appStore.validateAppVersionConfig({ ...baseConfig, port: 70000 }),
+    Error,
+    'Invalid app config port',
+  );
+
+  assertThrows(
+    () => appStore.normalizeVolumes([{ mountPath: 'relative/path' }]),
+    Error,
+    'mountPath must be an absolute path',
+  );
+
+  assertThrows(
+    () => appStore.validateAppVersionConfig({
+      ...baseConfig,
+      publishedPorts: [
+        { targetPort: 3000, targetPortEnd: 3002, publishedPort: 3000, publishedPortEnd: 3001, protocol: 'tcp' },
+      ],
+    }),
+    Error,
+    'ranges must have the same size',
+  );
+});
+
+Deno.test('docker service spec validation rejects unsafe volume and port declarations', () => {
+  const dockerManager = new OneboxDockerManager();
+
+  dockerManager.validateServiceSpec({
+    ...baseService,
+    volumes: [{ mountPath: '/data/app' }],
+    publishedPorts: [{ targetPort: 3000, publishedPort: 3000, protocol: 'tcp' }],
+  });
+
+  assertThrows(
+    () => dockerManager.validateServiceSpec({
+      ...baseService,
+      volumes: [{ mountPath: 'relative/path' }],
+    }),
+    Error,
+    'must be an absolute path',
+  );
+
+  assertThrows(
+    () => dockerManager.validateServiceSpec({
+      ...baseService,
+      publishedPorts: [
+        { targetPort: 3001, publishedPort: 3000, hostIp: '127.0.0.1', protocol: 'tcp' },
+        { targetPort: 3000, publishedPort: 3000, protocol: 'tcp' },
+      ],
+    }),
+    Error,
+    'Duplicate published port',
+  );
+});
@@ -7,6 +7,7 @@ class FakeDatabase {
  public settings = new Map<string, string>();
  public secretSettings = new Map<string, string>();
  public domains: IDomain[] = [];
+  public services: IService[] = [];
  public certificates = new Map<string, ISslCertificate>();
  private nextDomainId = 1;

@@ -42,6 +43,10 @@ class FakeDatabase {
    return this.domains.filter((entry) => entry.dnsProvider === provider);
  }

+  getAllServices(): IService[] {
+    return this.services;
+  }
+
  getSSLCertificate(domain: string): ISslCertificate | null {
    return this.certificates.get(domain) ?? null;
  }
@@ -168,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 = {
@@ -241,6 +287,282 @@ Deno.test('ExternalGatewayManager deletes service routes through dcrouter gatewa
  assertEquals((capturedDeleteRequest.ownership as any).hostname, 'hello.example.com');
 });

+Deno.test('ExternalGatewayManager removes stale gateway routes during reconciliation', async () => {
+  const oneboxRef = makeOneboxRef();
+  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', routeId: 'active-route' };
+    }
+    if (method === 'exportCertificate') {
+      return { success: false };
+    }
+    if (method === 'getGatewayClientDnsRecords') {
+      return {
+        records: [
+          {
+            id: 'active-record',
+            domainId: 'domain-1',
+            name: 'active',
+            type: 'A',
+            value: '203.0.113.10',
+            ttl: 300,
+            source: 'route',
+            status: 'active',
+            gatewayClientType: 'onebox',
+            gatewayClientId: 'onebox-token',
+            appId: 'active',
+            hostname: 'active.example.com',
+            routeId: 'active-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 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);
@@ -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',
+    },
+  ]);
+});
@@ -3,6 +3,6 @@
 */
 export const commitinfo = {
  name: '@serve.zone/onebox',
-  version: '1.27.0',
+  version: '1.30.1',
  description: 'Self-hosted container platform with automatic SSL and DNS - a mini Heroku for single servers'
 }
@@ -19,6 +19,27 @@ export interface ICatalogApp {
  tags?: string[];
 }

+export interface IAppCatalogVolume {
+  name?: string;
+  source?: string;
+  mountPath: string;
+  driver?: string;
+  readOnly?: boolean;
+  backup?: boolean;
+  options?: Record<string, string>;
+}
+
+export type TAppCatalogVolumeSpec = string | IAppCatalogVolume;
+
+export interface IAppCatalogPublishedPort {
+  targetPort: number;
+  targetPortEnd?: number;
+  publishedPort?: number;
+  publishedPortEnd?: number;
+  protocol?: 'tcp' | 'udp';
+  hostIp?: string;
+}
+
 export interface IAppMeta {
  id: string;
  name: string;
@@ -35,7 +56,8 @@ export interface IAppVersionConfig {
  image: string;
  port: number;
  envVars?: Array<{ key: string; value: string; description: string; required?: boolean }>;
-  volumes?: string[];
+  volumes?: TAppCatalogVolumeSpec[];
+  publishedPorts?: IAppCatalogPublishedPort[];
  platformRequirements?: {
    mongodb?: boolean;
    s3?: boolean;
@@ -46,6 +68,17 @@ export interface IAppVersionConfig {
  minOneboxVersion?: string;
 }

+export interface IAppInstallOptions {
+  appId: string;
+  version?: string;
+  serviceName: string;
+  domain?: string;
+  port?: number;
+  publishedPorts?: IAppCatalogPublishedPort[];
+  envVars?: Record<string, string>;
+  autoDNS?: boolean;
+}
+
 export interface IMigrationContext {
  service: {
    name: string;
@@ -61,6 +94,9 @@ export interface IMigrationResult {
  success: boolean;
  envVars?: Record<string, string>;
  image?: string;
+  port?: number;
+  volumes?: IAppCatalogVolume[];
+  publishedPorts?: IAppCatalogPublishedPort[];
  warnings: string[];
 }

@@ -8,6 +8,8 @@ import type {
  ICatalog,
  ICatalogApp,
  IAppMeta,
+  IAppCatalogVolume,
+  IAppInstallOptions,
  IAppVersionConfig,
  IMigrationContext,
  IMigrationResult,
@@ -16,7 +18,8 @@ import type {
 import { logger } from '../logging.ts';
 import { getErrorMessage } from '../utils/error.ts';
 import type { Onebox } from './onebox.ts';
-import type { IService } from '../types.ts';
+import type { IService, IServiceVolume } from '../types.ts';
+import { projectInfo } from '../info.ts';

 export class AppStoreManager {
  private oneboxRef: Onebox;
@@ -90,12 +93,50 @@ export class AppStoreManager {
   */
  async getAppVersionConfig(appId: string, version: string): Promise<IAppVersionConfig> {
    try {
-      return await this.fetchJson(`apps/${appId}/versions/${version}/config.json`) as IAppVersionConfig;
+      const config = await this.fetchJson(`apps/${appId}/versions/${version}/config.json`) as IAppVersionConfig;
+      this.validateAppVersionConfig(config, `${appId}@${version}`);
+      return config;
    } catch (error) {
      throw new Error(`Failed to fetch config for ${appId}@${version}: ${getErrorMessage(error)}`);
    }
  }

+  async installApp(optionsArg: IAppInstallOptions): Promise<IService> {
+    this.validateInstallOptions(optionsArg);
+    const appMeta = await this.getAppMeta(optionsArg.appId);
+    const version = optionsArg.version || appMeta.latestVersion;
+    const config = await this.getAppVersionConfig(optionsArg.appId, version);
+    this.assertRuntimeCompatibility(config);
+    const servicePort = optionsArg.port || config.port;
+    this.assertValidPort(servicePort, 'install service port');
+    const volumes = this.normalizeVolumes(config.volumes);
+    const publishedPorts = optionsArg.publishedPorts || config.publishedPorts || [];
+    this.validatePublishedPorts(publishedPorts, `${optionsArg.appId}@${version}`);
+
+    const envVars = this.getAppStoreEnvVars(config, optionsArg.envVars || {});
+    if (this.requiresTemplateValue(envVars, 'SERVICE_DOMAIN') && !optionsArg.domain) {
+      throw new Error('A domain is required because the app template uses ${SERVICE_DOMAIN}');
+    }
+
+    return await this.oneboxRef.services.deployService({
+      name: optionsArg.serviceName,
+      image: config.image,
+      port: servicePort,
+      domain: optionsArg.domain,
+      autoDNS: optionsArg.autoDNS,
+      envVars,
+      volumes,
+      publishedPorts,
+      enableMongoDB: Boolean(config.platformRequirements?.mongodb),
+      enableS3: Boolean(config.platformRequirements?.s3),
+      enableClickHouse: Boolean(config.platformRequirements?.clickhouse),
+      enableRedis: Boolean(config.platformRequirements?.redis),
+      enableMariaDB: Boolean(config.platformRequirements?.mariadb),
+      appTemplateId: optionsArg.appId,
+      appTemplateVersion: version,
+    });
+  }
+
  /**
   * Compare deployed services against catalog to find those with available upgrades
   */
@@ -165,6 +206,9 @@ export class AppStoreManager {
      return {
        success: true,
        image: config.image,
+        port: config.port,
+        volumes: this.normalizeVolumes(config.volumes),
+        publishedPorts: config.publishedPorts,
        envVars: undefined, // Keep existing env vars
        warnings: [],
      };
@@ -265,6 +309,18 @@ export class AppStoreManager {
      updates.image = migrationResult.image;
    }

+    if (migrationResult.port) {
+      updates.port = migrationResult.port;
+    }
+
+    if (migrationResult.volumes) {
+      updates.volumes = migrationResult.volumes;
+    }
+
+    if (migrationResult.publishedPorts) {
+      updates.publishedPorts = migrationResult.publishedPorts;
+    }
+
    if (migrationResult.envVars) {
      // Merge: migration result provides base, user overrides preserved
      const mergedEnvVars = { ...migrationResult.envVars };
@@ -332,4 +388,171 @@ export class AppStoreManager {
    }
    return response.text();
  }
+
+  public normalizeVolumes(volumesArg: IAppVersionConfig['volumes'] = []): IServiceVolume[] {
+    return volumesArg.map((volumeArg, indexArg): IAppCatalogVolume => {
+      if (typeof volumeArg === 'string') {
+        return { mountPath: volumeArg };
+      }
+      return volumeArg;
+    }).map((volumeArg, indexArg) => {
+      this.validateVolume(volumeArg, `volume ${indexArg + 1}`);
+      return volumeArg;
+    });
+  }
+
+  public validateAppVersionConfig(configArg: IAppVersionConfig, labelArg = 'app config'): void {
+    if (!configArg || typeof configArg !== 'object') {
+      throw new Error(`Invalid ${labelArg}: config must be an object`);
+    }
+    if (!configArg.image || typeof configArg.image !== 'string') {
+      throw new Error(`Invalid ${labelArg}: image is required`);
+    }
+    if (configArg.image.endsWith(':latest')) {
+      logger.warn(`App template ${labelArg} uses a mutable ':latest' image tag`);
+    }
+    this.assertValidPort(configArg.port, `${labelArg} port`);
+
+    for (const envVar of configArg.envVars || []) {
+      if (!envVar.key || !/^[A-Z_][A-Z0-9_]*$/.test(envVar.key)) {
+        throw new Error(`Invalid ${labelArg}: env var key '${envVar.key}' is not valid`);
+      }
+      if (envVar.value !== undefined && typeof envVar.value !== 'string') {
+        throw new Error(`Invalid ${labelArg}: env var '${envVar.key}' value must be a string`);
+      }
+    }
+
+    this.normalizeVolumes(configArg.volumes);
+    this.validatePublishedPorts(configArg.publishedPorts || [], labelArg);
+  }
+
+  private validateInstallOptions(optionsArg: IAppInstallOptions): void {
+    if (!optionsArg.appId || !/^[a-z0-9][a-z0-9-]*$/.test(optionsArg.appId)) {
+      throw new Error(`Invalid app id: ${optionsArg.appId}`);
+    }
+    if (!optionsArg.serviceName || !/^[a-zA-Z0-9][a-zA-Z0-9_.-]{0,119}$/.test(optionsArg.serviceName)) {
+      throw new Error(`Invalid service name: ${optionsArg.serviceName}`);
+    }
+    if (optionsArg.port !== undefined) {
+      this.assertValidPort(optionsArg.port, 'install service port');
+    }
+    if (optionsArg.publishedPorts) {
+      this.validatePublishedPorts(optionsArg.publishedPorts, `install options for ${optionsArg.appId}`);
+    }
+  }
+
+  private validateVolume(volumeArg: IAppCatalogVolume, labelArg: string): void {
+    if (!volumeArg.mountPath || !volumeArg.mountPath.startsWith('/')) {
+      throw new Error(`Invalid ${labelArg}: mountPath must be an absolute path`);
+    }
+    if (volumeArg.mountPath.includes(':')) {
+      throw new Error(`Invalid ${labelArg}: mountPath must not contain ':'`);
+    }
+    if ((volumeArg.source || volumeArg.name)?.includes(':')) {
+      throw new Error(`Invalid ${labelArg}: source/name must not contain ':'`);
+    }
+  }
+
+  private validatePublishedPorts(
+    publishedPortsArg: IAppVersionConfig['publishedPorts'] = [],
+    labelArg: string,
+  ): void {
+    const seenPublishedPorts = new Set<string>();
+    for (const portArg of publishedPortsArg) {
+      const protocol = portArg.protocol || 'tcp';
+      const targetStart = portArg.targetPort;
+      const targetEnd = portArg.targetPortEnd || targetStart;
+      const publishedStart = portArg.publishedPort || targetStart;
+      const publishedEnd = portArg.publishedPortEnd || (publishedStart + (targetEnd - targetStart));
+      const hostIp = portArg.hostIp || '0.0.0.0';
+
+      if (!['tcp', 'udp'].includes(protocol)) {
+        throw new Error(`Invalid ${labelArg}: published port protocol '${protocol}' is not supported`);
+      }
+      this.assertValidPort(targetStart, `${labelArg} targetPort`);
+      this.assertValidPort(targetEnd, `${labelArg} targetPortEnd`);
+      this.assertValidPort(publishedStart, `${labelArg} publishedPort`);
+      this.assertValidPort(publishedEnd, `${labelArg} publishedPortEnd`);
+      if (targetEnd < targetStart || publishedEnd < publishedStart) {
+        throw new Error(`Invalid ${labelArg}: published port ranges must be ascending`);
+      }
+      if ((targetEnd - targetStart) !== (publishedEnd - publishedStart)) {
+        throw new Error(`Invalid ${labelArg}: target and published port ranges must have the same size`);
+      }
+      if ((targetEnd - targetStart) > 1000) {
+        throw new Error(`Invalid ${labelArg}: published port ranges may not exceed 1001 ports`);
+      }
+
+      for (let offset = 0; offset <= targetEnd - targetStart; offset++) {
+        const publishedPort = publishedStart + offset;
+        const publishedKey = `${hostIp}/${protocol}/${publishedPort}`;
+        const wildcardKey = `0.0.0.0/${protocol}/${publishedPort}`;
+        const conflictsWithWildcard = hostIp === '0.0.0.0'
+          ? Array.from(seenPublishedPorts).some((keyArg) => keyArg.endsWith(`/${protocol}/${publishedPort}`))
+          : seenPublishedPorts.has(wildcardKey);
+        if (seenPublishedPorts.has(publishedKey) || conflictsWithWildcard) {
+          throw new Error(`Invalid ${labelArg}: duplicate published port ${hostIp}:${publishedPort}/${protocol}`);
+        }
+        seenPublishedPorts.add(publishedKey);
+      }
+    }
+  }
+
+  private assertValidPort(portArg: number, labelArg: string): void {
+    if (!Number.isInteger(portArg) || portArg < 1 || portArg > 65535) {
+      throw new Error(`Invalid ${labelArg}: ${portArg}. Expected an integer port between 1 and 65535.`);
+    }
+  }
+
+  private getAppStoreEnvVars(
+    configArg: IAppVersionConfig,
+    overridesArg: Record<string, string>,
+  ): Record<string, string> {
+    const envVars: Record<string, string> = {};
+    const missingRequiredEnvVars: string[] = [];
+
+    for (const envVar of configArg.envVars || []) {
+      const value = overridesArg[envVar.key] ?? envVar.value ?? '';
+      if (envVar.required && !value) {
+        missingRequiredEnvVars.push(envVar.key);
+      }
+      envVars[envVar.key] = value;
+    }
+
+    for (const [key, value] of Object.entries(overridesArg)) {
+      envVars[key] = value;
+    }
+
+    if (missingRequiredEnvVars.length > 0) {
+      throw new Error(
+        `Missing required app env var(s): ${missingRequiredEnvVars.join(', ')}`,
+      );
+    }
+
+    return envVars;
+  }
+
+  private requiresTemplateValue(envVarsArg: Record<string, string>, templateNameArg: string): boolean {
+    return Object.values(envVarsArg).some((value) => value.includes(`\${${templateNameArg}}`));
+  }
+
+  private assertRuntimeCompatibility(configArg: IAppVersionConfig): void {
+    if (!configArg.minOneboxVersion) return;
+    if (this.compareVersions(projectInfo.version, configArg.minOneboxVersion) < 0) {
+      throw new Error(
+        `App requires Onebox >= ${configArg.minOneboxVersion}; current version is ${projectInfo.version}`,
+      );
+    }
+  }
+
+  private compareVersions(versionAArg: string, versionBArg: string): number {
+    const normalize = (versionArg: string) => versionArg.replace(/^v/, '').split('.').map((partArg) => Number(partArg) || 0);
+    const a = normalize(versionAArg);
+    const b = normalize(versionBArg);
+    for (let i = 0; i < Math.max(a.length, b.length); i++) {
+      const diff = (a[i] || 0) - (b[i] || 0);
+      if (diff !== 0) return diff > 0 ? 1 : -1;
+    }
+    return 0;
+  }
 }
@@ -185,7 +185,12 @@ export class BackupManager {
        await this.exportDockerImage(service.image, `${tempDir}/data/image/image.tar`);
      }

-      // 4. Build ingest items from temp directory files
+      // 4. Export declared service volume data when the volume opts into backup.
+      if (service.volumes?.some((volumeArg) => volumeArg.backup !== false)) {
+        await this.exportServiceVolumes(service, tempDir);
+      }
+
+      // 5. Build ingest items from temp directory files
      const items: Array<{ stream: NodeJS.ReadableStream; name: string; type?: string }> = [];

      // Service config
@@ -218,6 +223,19 @@ export class BackupManager {
        }
      }

+      const volumeDataDir = `${tempDir}/data/volumes`;
+      try {
+        for await (const filePath of this.walkFiles(volumeDataDir)) {
+          items.push({
+            stream: plugins.nodeFs.createReadStream(filePath),
+            name: plugins.path.relative(tempDir, filePath).replaceAll('\\', '/'),
+            type: 'volume',
+          });
+        }
+      } catch {
+        // No service volume data was exported.
+      }
+
      // Docker image
      if (includeImage && service.image) {
        const imagePath = `${tempDir}/data/image/image.tar`;
@@ -233,7 +251,7 @@ export class BackupManager {
        }
      }

-      // 5. Build snapshot tags
+      // 6. Build snapshot tags
      const tags: Record<string, string> = {
        serviceName: service.name,
        serviceId: String(service.id),
@@ -245,10 +263,10 @@ export class BackupManager {
        tags.scheduleId = String(options.scheduleId);
      }

-      // 6. Ingest multi-item snapshot into containerarchive
+      // 7. Ingest multi-item snapshot into containerarchive
      const snapshot = await this.archive.ingestMulti(items, { tags });

-      // 7. Store backup record in database
+      // 8. Store backup record in database
      const backup: IBackup = {
        serviceId: service.id!,
        serviceName: service.name,
@@ -675,6 +693,8 @@ export class BackupManager {
          registry: serviceConfig.registry,
          port: serviceConfig.port,
          domain: serviceConfig.domain,
+          volumes: serviceConfig.volumes,
+          publishedPorts: serviceConfig.publishedPorts,
          useOneboxRegistry: serviceConfig.useOneboxRegistry,
          registryRepository: serviceConfig.registryRepository,
          registryImageTag: serviceConfig.registryImageTag,
@@ -705,6 +725,8 @@ export class BackupManager {
          port: serviceConfig.port,
          domain: options.mode === 'clone' ? undefined : serviceConfig.domain,
          envVars: serviceConfig.envVars,
+          volumes: serviceConfig.volumes,
+          publishedPorts: serviceConfig.publishedPorts,
          useOneboxRegistry: serviceConfig.useOneboxRegistry,
          registryImageTag: serviceConfig.registryImageTag,
          autoUpdateOnPush: serviceConfig.autoUpdateOnPush,
@@ -729,6 +751,8 @@ export class BackupManager {
        }
      }

+      await this.restoreServiceVolumes(service, serviceConfig.volumes || [], tempDir, warnings);
+
      // Cleanup
      await Deno.remove(tempDir, { recursive: true });

@@ -791,6 +815,8 @@ export class BackupManager {
      image: service.image,
      registry: service.registry,
      envVars: service.envVars,
+      volumes: service.volumes,
+      publishedPorts: service.publishedPorts,
      port: service.port,
      domain: service.domain,
      useOneboxRegistry: service.useOneboxRegistry,
@@ -802,6 +828,62 @@ export class BackupManager {
    };
  }

+  private getVolumeBackupName(volumeArg: { mountPath: string }, indexArg: number): string {
+    const safeMountPath = volumeArg.mountPath
+      .replace(/^\/+/, '')
+      .replace(/\/+$/g, '')
+      .replace(/[^a-zA-Z0-9_.-]+/g, '-') || 'root';
+    return `${String(indexArg).padStart(3, '0')}-${safeMountPath}`;
+  }
+
+  private async exportServiceVolumes(serviceArg: IService, tempDirArg: string): Promise<void> {
+    if (!serviceArg.containerID) {
+      throw new Error(`Cannot export service volumes for ${serviceArg.name}: service has no container ID`);
+    }
+
+    const volumes = (serviceArg.volumes || []).filter((volumeArg) => volumeArg.backup !== false);
+    for (let i = 0; i < volumes.length; i++) {
+      const volume = volumes[i];
+      const backupName = this.getVolumeBackupName(volume, i);
+      const outputPath = `${tempDirArg}/data/volumes/${backupName}`;
+      await Deno.mkdir(outputPath, { recursive: true });
+      await this.copyFromContainer(serviceArg.containerID, `${volume.mountPath}/.`, outputPath);
+      logger.info(`Exported volume ${volume.mountPath} for service ${serviceArg.name}`);
+    }
+  }
+
+  private async restoreServiceVolumes(
+    serviceArg: IService,
+    volumesArg: NonNullable<IBackupServiceConfig['volumes']>,
+    tempDirArg: string,
+    warningsArg: string[],
+  ): Promise<void> {
+    if (!serviceArg.containerID) {
+      if (volumesArg.some((volumeArg) => volumeArg.backup !== false)) {
+        warningsArg.push(`Could not restore service volumes for ${serviceArg.name}: service has no container ID`);
+      }
+      return;
+    }
+
+    const volumes = volumesArg.filter((volumeArg) => volumeArg.backup !== false);
+    for (let i = 0; i < volumes.length; i++) {
+      const volume = volumes[i];
+      const backupName = this.getVolumeBackupName(volume, i);
+      const inputPath = `${tempDirArg}/data/volumes/${backupName}`;
+      try {
+        await Deno.stat(inputPath);
+      } catch {
+        continue;
+      }
+      try {
+        await this.copyToContainer(`${inputPath}/.`, serviceArg.containerID, volume.mountPath);
+        logger.info(`Restored volume ${volume.mountPath} for service ${serviceArg.name}`);
+      } catch (error) {
+        warningsArg.push(`Volume restore failed for ${volume.mountPath}: ${getErrorMessage(error)}`);
+      }
+    }
+  }
+
  /**
   * Export MongoDB database
   */
@@ -5,14 +5,258 @@
 */

 import * as plugins from '../plugins.ts';
-import type { IService, IContainerStats } from '../types.ts';
+import type { IService, IContainerStats, IServicePublishedPort } from '../types.ts';
 import { logger } from '../logging.ts';
 import { getErrorMessage } from '../utils/error.ts';

+type TExpandedPublishedPort = Required<Pick<
+  IServicePublishedPort,
+  'targetPort' | 'publishedPort' | 'protocol' | 'hostIp'
+>>;
+
 export class OneboxDockerManager {
  private dockerClient: InstanceType<typeof plugins.docker.Docker> | null = null;
  private networkName = 'onebox-network';

+  private getDockerSafeName(valueArg: string, maxLengthArg = 120): string {
+    const safeName = valueArg
+      .replace(/[^a-zA-Z0-9_.-]+/g, '-')
+      .replace(/^[^a-zA-Z0-9]+|[^a-zA-Z0-9]+$/g, '')
+      .slice(0, maxLengthArg)
+      .replace(/[^a-zA-Z0-9]+$/g, '');
+    return safeName || 'data';
+  }
+
+  private getServiceVolumeSource(serviceArg: IService, mountPathArg: string, requestedSourceArg?: string): string {
+    if (requestedSourceArg) {
+      return this.getDockerSafeName(requestedSourceArg);
+    }
+    const mountName = this.getDockerSafeName(mountPathArg.replace(/^\/+/, '').replace(/\/+$/g, ''), 40);
+    return this.getDockerSafeName(`onebox-${serviceArg.name}-${mountName}`);
+  }
+
+  private getStandaloneVolumeBinds(serviceArg: IService): string[] {
+    return (serviceArg.volumes || []).map((volumeArg) => {
+      const source = this.getServiceVolumeSource(serviceArg, volumeArg.mountPath, volumeArg.source || volumeArg.name);
+      return `${source}:${volumeArg.mountPath}${volumeArg.readOnly ? ':ro' : ''}`;
+    });
+  }
+
+  private getSwarmVolumeMounts(serviceArg: IService): Array<Record<string, unknown>> {
+    return (serviceArg.volumes || []).map((volumeArg) => ({
+      Type: 'volume',
+      Source: this.getServiceVolumeSource(serviceArg, volumeArg.mountPath, volumeArg.source || volumeArg.name),
+      Target: volumeArg.mountPath,
+      ReadOnly: Boolean(volumeArg.readOnly),
+      VolumeOptions: {
+        DriverConfig: {
+          Name: volumeArg.driver || 'local',
+          Options: volumeArg.options || {},
+        },
+        Labels: {
+          'managed-by': 'onebox',
+          'onebox-service': serviceArg.name,
+          'onebox-mount-path': volumeArg.mountPath,
+          'onebox-backup': String(volumeArg.backup !== false),
+        },
+      },
+    }));
+  }
+
+  public validateServiceSpec(serviceArg: IService): void {
+    this.assertValidPort(serviceArg.port, `service port for ${serviceArg.name}`);
+
+    for (const volumeArg of serviceArg.volumes || []) {
+      if (!volumeArg.mountPath || !volumeArg.mountPath.startsWith('/')) {
+        throw new Error(`Volume mountPath for service ${serviceArg.name} must be an absolute path`);
+      }
+      if (volumeArg.mountPath.includes(':')) {
+        throw new Error(`Volume mountPath for service ${serviceArg.name} must not contain ':'`);
+      }
+      if ((volumeArg.source || volumeArg.name)?.includes(':')) {
+        throw new Error(`Volume source/name for service ${serviceArg.name} must not contain ':'`);
+      }
+    }
+
+    this.expandPublishedPorts(serviceArg);
+  }
+
+  private assertValidPort(portArg: number, labelArg: string): void {
+    if (!Number.isInteger(portArg) || portArg < 1 || portArg > 65535) {
+      throw new Error(`Invalid ${labelArg}: ${portArg}. Expected an integer port between 1 and 65535.`);
+    }
+  }
+
+  private expandPublishedPorts(serviceArg: IService): TExpandedPublishedPort[] {
+    const expandedPorts: TExpandedPublishedPort[] = [];
+    const seenPublishedPorts = new Set<string>();
+
+    for (const portArg of serviceArg.publishedPorts || []) {
+      const protocol = portArg.protocol || 'tcp';
+      const targetStart = portArg.targetPort;
+      const targetEnd = portArg.targetPortEnd || targetStart;
+      const publishedStart = portArg.publishedPort || targetStart;
+      const publishedEnd = portArg.publishedPortEnd || (publishedStart + (targetEnd - targetStart));
+      const hostIp = portArg.hostIp || '0.0.0.0';
+
+      if (!['tcp', 'udp'].includes(protocol)) {
+        throw new Error(`Invalid published port protocol for service ${serviceArg.name}: ${protocol}`);
+      }
+      this.assertValidPort(targetStart, `published targetPort for service ${serviceArg.name}`);
+      this.assertValidPort(targetEnd, `published targetPortEnd for service ${serviceArg.name}`);
+      this.assertValidPort(publishedStart, `published publishedPort for service ${serviceArg.name}`);
+      this.assertValidPort(publishedEnd, `published publishedPortEnd for service ${serviceArg.name}`);
+      if (targetEnd < targetStart) {
+        throw new Error(`Invalid target port range for service ${serviceArg.name}: ${targetStart}-${targetEnd}`);
+      }
+      if (publishedEnd < publishedStart) {
+        throw new Error(`Invalid published port range for service ${serviceArg.name}: ${publishedStart}-${publishedEnd}`);
+      }
+      if ((targetEnd - targetStart) !== (publishedEnd - publishedStart)) {
+        throw new Error(
+          `Published port range size must match target port range size for service ${serviceArg.name}`,
+        );
+      }
+      if (!this.isValidHostIp(hostIp)) {
+        throw new Error(`Invalid hostIp for service ${serviceArg.name}: ${hostIp}`);
+      }
+
+      for (let offset = 0; offset <= targetEnd - targetStart; offset++) {
+        const publishedPort = publishedStart + offset;
+        const publishedKey = `${hostIp}/${protocol}/${publishedPort}`;
+        const wildcardKey = `0.0.0.0/${protocol}/${publishedPort}`;
+        const conflictsWithWildcard = hostIp === '0.0.0.0'
+          ? Array.from(seenPublishedPorts).some((keyArg) => keyArg.endsWith(`/${protocol}/${publishedPort}`))
+          : seenPublishedPorts.has(wildcardKey);
+        if (seenPublishedPorts.has(publishedKey) || conflictsWithWildcard) {
+          throw new Error(`Duplicate published port for service ${serviceArg.name}: ${hostIp}:${publishedPort}/${protocol}`);
+        }
+        seenPublishedPorts.add(publishedKey);
+        expandedPorts.push({
+          targetPort: targetStart + offset,
+          publishedPort,
+          protocol,
+          hostIp,
+        });
+      }
+    }
+
+    return expandedPorts;
+  }
+
+  private isValidHostIp(hostIpArg: string): boolean {
+    if (['0.0.0.0', '127.0.0.1', '::', '::1', 'localhost'].includes(hostIpArg)) return true;
+    if (/^(\d{1,3}\.){3}\d{1,3}$/.test(hostIpArg)) {
+      return hostIpArg.split('.').every((partArg) => Number(partArg) >= 0 && Number(partArg) <= 255);
+    }
+    return /^[0-9a-fA-F:]+$/.test(hostIpArg);
+  }
+
+  private async assertPublishedPortsAvailable(serviceArg: IService): Promise<void> {
+    const publishedPorts = this.expandPublishedPorts(serviceArg);
+    if (publishedPorts.length === 0) return;
+
+    await this.assertPublishedPortsNotUsedByDocker(serviceArg, publishedPorts);
+    await this.assertPublishedPortsNotUsedByHost(serviceArg, publishedPorts);
+  }
+
+  private async assertPublishedPortsNotUsedByDocker(
+    serviceArg: IService,
+    publishedPortsArg: TExpandedPublishedPort[],
+  ): Promise<void> {
+    const requestedPorts = new Set(
+      publishedPortsArg.map((portArg) => `${portArg.protocol}/${portArg.publishedPort}`),
+    );
+
+    try {
+      const containersResponse = await this.dockerClient!.request('GET', '/containers/json?all=true', {});
+      if (containersResponse.statusCode === 200 && Array.isArray(containersResponse.body)) {
+        for (const containerArg of containersResponse.body) {
+          const labels = containerArg.Labels || {};
+          if (labels['onebox-service'] === serviceArg.name) continue;
+          for (const portArg of containerArg.Ports || []) {
+            if (!portArg.PublicPort || !portArg.Type) continue;
+            if (requestedPorts.has(`${portArg.Type}/${portArg.PublicPort}`)) {
+              throw new Error(
+                `Published port ${portArg.PublicPort}/${portArg.Type} is already used by container ${containerArg.Names?.[0] || containerArg.Id}`,
+              );
+            }
+          }
+        }
+      }
+
+      const servicesResponse = await this.dockerClient!.request('GET', '/services', {});
+      if (servicesResponse.statusCode === 200 && Array.isArray(servicesResponse.body)) {
+        for (const service of servicesResponse.body) {
+          if (service.Spec?.Name === `onebox-${serviceArg.name}`) continue;
+          for (const portArg of service.Endpoint?.Ports || []) {
+            if (!portArg.PublishedPort || !portArg.Protocol) continue;
+            if (requestedPorts.has(`${portArg.Protocol}/${portArg.PublishedPort}`)) {
+              throw new Error(
+                `Published port ${portArg.PublishedPort}/${portArg.Protocol} is already used by Docker service ${service.Spec?.Name || service.ID}`,
+              );
+            }
+          }
+        }
+      }
+    } catch (error) {
+      if (error instanceof Error && error.message.startsWith('Published port ')) throw error;
+      logger.warn(`Could not complete Docker published-port preflight: ${getErrorMessage(error)}`);
+    }
+  }
+
+  private async assertPublishedPortsNotUsedByHost(
+    serviceArg: IService,
+    publishedPortsArg: TExpandedPublishedPort[],
+  ): Promise<void> {
+    for (const portArg of publishedPortsArg) {
+      try {
+        if (portArg.protocol === 'udp') {
+          await this.assertUdpPortAvailable(portArg.hostIp, portArg.publishedPort);
+        } else {
+          const listener = Deno.listen({ hostname: portArg.hostIp, port: portArg.publishedPort });
+          listener.close();
+        }
+      } catch (error) {
+        throw new Error(
+          `Published port ${portArg.hostIp}:${portArg.publishedPort}/${portArg.protocol} for service ${serviceArg.name} is not available: ${getErrorMessage(error)}`,
+        );
+      }
+    }
+  }
+
+  private async assertUdpPortAvailable(hostIpArg: string, portArg: number): Promise<void> {
+    const dgram = await import('node:dgram');
+    const socket = dgram.createSocket(hostIpArg.includes(':') ? 'udp6' : 'udp4');
+    await new Promise<void>((resolve, reject) => {
+      socket.once('error', reject);
+      socket.bind(portArg, hostIpArg, () => {
+        socket.close();
+        resolve();
+      });
+    });
+  }
+
+  private getStandalonePortConfig(serviceArg: IService): {
+    exposedPorts: Record<string, Record<string, never>>;
+    portBindings: Record<string, Array<{ HostIp: string; HostPort: string }>>;
+  } {
+    const exposedPorts: Record<string, Record<string, never>> = {
+      [`${serviceArg.port}/tcp`]: {},
+    };
+    const portBindings: Record<string, Array<{ HostIp: string; HostPort: string }>> = {
+      [`${serviceArg.port}/tcp`]: [],
+    };
+
+    for (const publishedPort of this.expandPublishedPorts(serviceArg)) {
+      const key = `${publishedPort.targetPort}/${publishedPort.protocol}`;
+      exposedPorts[key] = {};
+      portBindings[key] = [{ HostIp: publishedPort.hostIp, HostPort: String(publishedPort.publishedPort) }];
+    }
+
+    return { exposedPorts, portBindings };
+  }
+
  /**
   * Initialize Docker client and create onebox network
   */
@@ -122,6 +366,9 @@ export class OneboxDockerManager {
   */
  async createContainer(service: IService): Promise<string> {
    try {
+      this.validateServiceSpec(service);
+      await this.assertPublishedPortsAvailable(service);
+
      // Check if Docker is in Swarm mode
      let isSwarmMode = false;
      try {
@@ -158,6 +405,8 @@ export class OneboxDockerManager {
      env.push(`${key}=${value}`);
    }

+    const portConfig = this.getStandalonePortConfig(service);
+
    // Create container using Docker REST API directly
    const response = await this.dockerClient!.request('POST', `/containers/create?name=onebox-${service.name}`, {
      Image: fullImage,
@@ -166,18 +415,14 @@ export class OneboxDockerManager {
        'managed-by': 'onebox',
        'onebox-service': service.name,
      },
-      ExposedPorts: {
-        [`${service.port}/tcp`]: {},
-      },
+      ExposedPorts: portConfig.exposedPorts,
      HostConfig: {
        NetworkMode: this.networkName,
        RestartPolicy: {
          Name: 'unless-stopped',
        },
-        PortBindings: {
-          // Don't bind to host ports - nginx will proxy
-          [`${service.port}/tcp`]: [],
-        },
+        PortBindings: portConfig.portBindings,
+        Binds: this.getStandaloneVolumeBinds(service),
      },
    });

@@ -207,6 +452,25 @@ export class OneboxDockerManager {
      env.push(`${key}=${value}`);
    }

+    const expandedPublishedPorts = this.expandPublishedPorts(service);
+    const endpointPorts: Array<Record<string, unknown>> = [];
+    if (!expandedPublishedPorts.some((publishedPort) => publishedPort.protocol === 'tcp' && publishedPort.targetPort === service.port)) {
+      endpointPorts.push({
+        Protocol: 'tcp',
+        TargetPort: service.port,
+        PublishMode: 'host',
+      });
+    }
+
+    for (const publishedPort of expandedPublishedPorts) {
+      endpointPorts.push({
+        Protocol: publishedPort.protocol,
+        TargetPort: publishedPort.targetPort,
+        PublishedPort: publishedPort.publishedPort,
+        PublishMode: 'host',
+      });
+    }
+
    // Create Swarm service using Docker REST API
    const response = await this.dockerClient!.request('POST', '/services/create', {
      Name: `onebox-${service.name}`,
@@ -218,6 +482,7 @@ export class OneboxDockerManager {
        ContainerSpec: {
          Image: fullImage,
          Env: env,
+          Mounts: this.getSwarmVolumeMounts(service),
          Labels: {
            'managed-by': 'onebox',
            'onebox-service': service.name,
@@ -239,13 +504,7 @@ export class OneboxDockerManager {
        },
      },
      EndpointSpec: {
-        Ports: [
-          {
-            Protocol: 'tcp',
-            TargetPort: service.port,
-            PublishMode: 'host',
-          },
-        ],
+        Ports: endpointPorts,
      },
    });

@@ -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;
@@ -133,6 +139,69 @@ export class ExternalGatewayManager {
    }

    await this.syncDomains();
+    await this.syncServiceRoutes();
+  }
+
+  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' && 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)}`,
+        );
+      }
+    }
+
+    await this.deleteStaleServiceRoutes(activeHostnames);
+  }
+
+  private async deleteStaleServiceRoutes(activeHostnamesArg: Set<string>): Promise<void> {
+    const records = await this.getGatewayDnsRecords();
+    const staleRecordsByHostname = new Map<string, IGatewayDnsRecord>();
+
+    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);
+    }
+
+    for (const record of staleRecordsByHostname.values()) {
+      try {
+        await this.deleteServiceRoute({
+          name: record.serviceName || record.appId,
+          domain: record.hostname,
+        });
+      } catch (error) {
+        logger.warn(
+          `Failed to delete stale external gateway route for ${record.hostname}: ${
+            getErrorMessage(error)
+          }`,
+        );
+      }
+    }
  }

  public async isConfigured(): Promise<boolean> {
@@ -250,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),
-        route: this.buildRoute(service, config),
-        enabled: service.status === 'running',
+        ownership: this.buildGatewayClientOwnership(route, route.domain, config),
+        route: this.buildRoute(route, config),
+        enabled: route.status === 'running',
      },
      config,
    ).catch(async () => {
      return await this.fireDcRouterRequest<IWorkAppRouteSyncResult>(
        'syncWorkAppRoute',
        {
-          ownership: this.buildOwnership(service, service.domain!, config),
-          route: this.buildRoute(service, config),
-          enabled: service.status === 'running',
+          ownership: this.buildOwnership(route, route.domain, config),
+          route: this.buildRoute(route, config),
+          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}`);
-    await this.importCertificateForDomain(service.domain).catch((error) => {
-      logger.debug(`External gateway certificate import skipped for ${service.domain}: ${getErrorMessage(error)}`);
+    logger.success(`External gateway route ${result.action || 'synced'} for ${route.domain}`);
+    await this.importCertificateForDomain(route.domain).catch((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 });
@@ -497,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',
@@ -227,6 +227,7 @@ export class ManagedDcRouterManager {
    const image = this.getImage();
    const token = await this.getAdminToken();
    const dataDir = await this.getAbsoluteDataDir();
+    await this.writeManagedConfig(dataDir);

    await this.oneboxRef.docker.pullImage(image);

@@ -234,6 +235,7 @@ export class ManagedDcRouterManager {
      Image: image,
      Env: [
        `DCROUTER_BASE_DIR=${internalBaseDir}`,
+        `DCROUTER_CONFIG_PATH=${internalBaseDir}/managed-config.json`,
        `DCROUTER_ADMIN_API_TOKEN=${token}`,
        'DCROUTER_ADMIN_API_TOKEN_NAME=Onebox Managed Admin Token',
      ],
@@ -268,6 +270,26 @@ export class ManagedDcRouterManager {
    logger.success(`Managed dcrouter container started: ${response.body.Id}`);
  }

+  private async writeManagedConfig(dataDirArg: string): Promise<void> {
+    const configPath = plugins.path.join(dataDirArg, 'managed-config.json');
+    try {
+      const existingConfig = await Deno.readTextFile(configPath);
+      JSON.parse(existingConfig);
+      return;
+    } catch (error) {
+      if (!(error instanceof Deno.errors.NotFound)) {
+        throw new Error(`Managed dcrouter config exists but is not valid JSON: ${getErrorMessage(error)}`);
+      }
+    }
+
+    const config = {
+      smartProxyConfig: {
+        routes: [],
+      },
+    };
+    await Deno.writeTextFile(configPath, JSON.stringify(config, null, 2));
+  }
+
  private async getExistingContainer(): Promise<any | null> {
    const filters = encodeURIComponent(JSON.stringify({ name: [containerName] }));
    const response = await this.dockerClient!.request('GET', `/containers/json?all=true&filters=${filters}`, {});
@@ -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,
@@ -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
@@ -95,6 +95,8 @@ export class OneboxServicesManager {
        image: options.useOneboxRegistry ? imageToPull : options.image,
        registry: options.registry,
        envVars: options.envVars || {},
+        volumes: options.volumes || [],
+        publishedPorts: options.publishedPorts || [],
        port: options.port,
        domain: options.domain,
        status: 'stopped',
@@ -578,6 +580,8 @@ export class OneboxServicesManager {
      port?: number;
      domain?: string;
      envVars?: Record<string, string>;
+      volumes?: IService['volumes'];
+      publishedPorts?: IService['publishedPorts'];
    }
  ): Promise<IService> {
    try {
@@ -616,6 +620,8 @@ export class OneboxServicesManager {
      if (updates.port !== undefined) updateData.port = updates.port;
      if (updates.domain !== undefined) updateData.domain = updates.domain;
      if (updates.envVars !== undefined) updateData.envVars = updates.envVars;
+      if (updates.volumes !== undefined) updateData.volumes = updates.volumes;
+      if (updates.publishedPorts !== undefined) updateData.publishedPorts = updates.publishedPorts;

      this.database.updateService(service.id!, updateData);

@@ -175,8 +175,10 @@ export class SmartProxyManager {
        throw new Error(`Failed to create SmartProxy service: HTTP ${response.statusCode} - ${JSON.stringify(response.body)}`);
      }

-      logger.info(`SmartProxy service created: ${response.body.ID}`);
+      const serviceId = response.body.ID;
+      logger.info(`SmartProxy service created: ${serviceId}`);

+      await this.waitForServiceTaskRunning(serviceId);
      await this.waitForReady();
      this.serviceRunning = true;
      await this.reloadConfig({ skipRunningCheck: true });
@@ -232,6 +234,37 @@ export class SmartProxyManager {
    throw new Error('SmartProxy service failed to start within timeout');
  }

+  private async waitForServiceTaskRunning(
+    serviceIdArg: string,
+    maxAttempts = 30,
+    intervalMs = 1000,
+  ): Promise<void> {
+    let lastState = 'unknown';
+
+    for (let i = 0; i < maxAttempts; i++) {
+      const tasksResponse = await this.dockerClient!.request(
+        'GET',
+        `/tasks?filters=${encodeURIComponent(JSON.stringify({ service: [serviceIdArg] }))}`,
+        {},
+      );
+
+      if (tasksResponse.statusCode === 200 && Array.isArray(tasksResponse.body)) {
+        const tasks = tasksResponse.body;
+        const runningTask = tasks.find((task: any) => task.Status?.State === 'running');
+        if (runningTask) {
+          return;
+        }
+
+        const latestTask = tasks[0];
+        lastState = latestTask?.Status?.State || lastState;
+      }
+
+      await new Promise((resolve) => setTimeout(resolve, intervalMs));
+    }
+
+    throw new Error(`SmartProxy service task did not reach running state (last state: ${lastState})`);
+  }
+
  async stop(): Promise<void> {
    try {
      await this.ensureDockerClient();
@@ -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
+`;
+  }
+}
@@ -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> {
@@ -214,33 +215,25 @@ async function handleAppStoreCommand(onebox: Onebox, subcommand: string, args: s

      const appMeta = await onebox.appStore.getAppMeta(appId);
      const version = getArg(args, '--version') || appMeta.latestVersion;
-      const config = await onebox.appStore.getAppVersionConfig(appId, version);
      const serviceName = getArg(args, '--name') || appId;
      const domain = getArg(args, '--domain');
-      const port = parseInt(getArg(args, '--port') || String(config.port), 10);
-      const envVars = getAppStoreEnvVars(config, parseEnvArgs(args));
+      const portArg = getArg(args, '--port');
+      const port = portArg ? parseInt(portArg, 10) : undefined;
      const autoDNS = getBooleanArg(args, '--auto-dns', true);

      requireValue(serviceName, '--name');
-      assertValidPort(port, '--port');
-      if (requiresTemplateValue(envVars, 'SERVICE_DOMAIN')) {
-        requireValue(domain, '--domain');
+      if (port !== undefined) {
+        assertValidPort(port, '--port');
      }

-      const service = await onebox.services.deployService({
-        name: serviceName,
-        image: config.image,
-        port,
+      const service = await onebox.appStore.installApp({
+        appId,
+        version,
+        serviceName,
        domain,
+        port,
        autoDNS,
-        envVars,
-        enableMongoDB: Boolean(config.platformRequirements?.mongodb),
-        enableS3: Boolean(config.platformRequirements?.s3),
-        enableClickHouse: Boolean(config.platformRequirements?.clickhouse),
-        enableRedis: Boolean(config.platformRequirements?.redis),
-        enableMariaDB: Boolean(config.platformRequirements?.mariadb),
-        appTemplateId: appId,
-        appTemplateVersion: version,
+        envVars: parseEnvArgs(args),
      });

      logger.success(`Installed ${appMeta.name} ${version} as ${service.name}`);
@@ -508,60 +501,29 @@ async function handleUpgradeCommand(): Promise<void> {
  logger.info('Checking for updates...');

  try {
-    // Get current version
-    const currentVersion = projectInfo.version;
+    const updateManager = new OneboxUpdateManager();
+    const status = await updateManager.getUpdateStatus({ force: true });
+    if (status.error) {
+      throw new Error(status.error);
+    }

-    // Fetch latest version from Gitea API
-    const apiUrl = 'https://code.foss.global/api/v1/repos/serve.zone/onebox/releases/latest';
-    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(`  Current version: ${status.currentVersion}`);
+    console.log(`  Latest version:  ${status.latestVersion}`);
    console.log('');

-    // Compare normalized versions
-    if (normalizedCurrent === normalizedLatest) {
+    if (!status.updateAvailable) {
      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 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);
-    }
+    const upgrade = await updateManager.runUpgradeForeground(status);

    console.log('');
-    logger.success(`Upgraded to ${latestVersion}`);
+    logger.success(upgrade.message);
  } catch (error) {
    logger.error(`Upgrade failed: ${getErrorMessage(error)}`);
    Deno.exit(1);
@@ -0,0 +1,11 @@
+import { BaseMigration } from './base-migration.ts';
+import type { TQueryFunction } from '../types.ts';
+
+export class Migration016ServiceVolumes extends BaseMigration {
+  readonly version = 16;
+  readonly description = 'Add persistent volume declarations to services';
+
+  up(query: TQueryFunction): void {
+    query(`ALTER TABLE services ADD COLUMN volumes TEXT DEFAULT '[]'`);
+  }
+}
@@ -0,0 +1,11 @@
+import { BaseMigration } from './base-migration.ts';
+import type { TQueryFunction } from '../types.ts';
+
+export class Migration017ServicePublishedPorts extends BaseMigration {
+  readonly version = 17;
+  readonly description = 'Add raw published port declarations to services';
+
+  up(query: TQueryFunction): void {
+    query(`ALTER TABLE services ADD COLUMN published_ports TEXT DEFAULT '[]'`);
+  }
+}
@@ -22,6 +22,8 @@ import { Migration012GfsRetention } from './migration-012-gfs-retention.ts';
 import { Migration013AppTemplateVersion } from './migration-013-app-template-version.ts';
 import { Migration014ContainerArchive } from './migration-014-containerarchive.ts';
 import { Migration015SmartProxyPlatformService } from './migration-015-smartproxy-platform-service.ts';
+import { Migration016ServiceVolumes } from './migration-016-service-volumes.ts';
+import { Migration017ServicePublishedPorts } from './migration-017-service-published-ports.ts';
 import type { BaseMigration } from './base-migration.ts';

 export class MigrationRunner {
@@ -48,6 +50,8 @@ export class MigrationRunner {
      new Migration013AppTemplateVersion(),
      new Migration014ContainerArchive(),
      new Migration015SmartProxyPlatformService(),
+      new Migration016ServiceVolumes(),
+      new Migration017ServicePublishedPorts(),
    ].sort((a, b) => a.version - b.version);
  }

@@ -14,17 +14,19 @@ export class ServiceRepository extends BaseRepository {
    const now = Date.now();
    this.query(
      `INSERT INTO services (
-        name, image, registry, env_vars, port, domain, container_id, status,
+        name, image, registry, env_vars, volumes, published_ports, port, domain, container_id, status,
        created_at, updated_at,
        use_onebox_registry, registry_repository, registry_image_tag,
        auto_update_on_push, image_digest, platform_requirements,
        app_template_id, app_template_version
-      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
      [
        service.name,
        service.image,
        service.registry || null,
        JSON.stringify(service.envVars),
+        JSON.stringify(service.volumes || []),
+        JSON.stringify(service.publishedPorts || []),
        service.port,
        service.domain || null,
        service.containerID || null,
@@ -82,6 +84,14 @@ export class ServiceRepository extends BaseRepository {
      fields.push('env_vars = ?');
      values.push(JSON.stringify(updates.envVars));
    }
+    if (updates.volumes !== undefined) {
+      fields.push('volumes = ?');
+      values.push(JSON.stringify(updates.volumes));
+    }
+    if (updates.publishedPorts !== undefined) {
+      fields.push('published_ports = ?');
+      values.push(JSON.stringify(updates.publishedPorts));
+    }
    if (updates.port !== undefined) {
      fields.push('port = ?');
      values.push(updates.port);
@@ -169,18 +179,42 @@ export class ServiceRepository extends BaseRepository {
      }
    }

+    let volumes = [];
+    const volumesRaw = row.volumes ?? row[20];
+    if (volumesRaw && volumesRaw !== 'undefined' && volumesRaw !== 'null') {
+      try {
+        volumes = JSON.parse(String(volumesRaw));
+      } catch (e) {
+        logger.warn(`Failed to parse volumes for service: ${getErrorMessage(e)}`);
+        volumes = [];
+      }
+    }
+
+    let publishedPorts = [];
+    const publishedPortsRaw = row.published_ports;
+    if (publishedPortsRaw && publishedPortsRaw !== 'undefined' && publishedPortsRaw !== 'null') {
+      try {
+        publishedPorts = JSON.parse(String(publishedPortsRaw));
+      } catch (e) {
+        logger.warn(`Failed to parse published_ports for service: ${getErrorMessage(e)}`);
+        publishedPorts = [];
+      }
+    }
+
    return {
      id: Number(row.id || row[0]),
      name: String(row.name || row[1]),
      image: String(row.image || row[2]),
      registry: (row.registry || row[3]) ? String(row.registry || row[3]) : undefined,
      envVars,
-      port: Number(row.port || row[5]),
-      domain: (row.domain || row[6]) ? String(row.domain || row[6]) : undefined,
-      containerID: (row.container_id || row[7]) ? String(row.container_id || row[7]) : undefined,
-      status: String(row.status || row[8]) as IService['status'],
-      createdAt: Number(row.created_at || row[9]),
-      updatedAt: Number(row.updated_at || row[10]),
+      volumes,
+      publishedPorts,
+      port: Number(row.port ?? row[6] ?? row[5]),
+      domain: (row.domain ?? row[7] ?? row[6]) ? String(row.domain ?? row[7] ?? row[6]) : undefined,
+      containerID: (row.container_id ?? row[8] ?? row[7]) ? String(row.container_id ?? row[8] ?? row[7]) : undefined,
+      status: String(row.status ?? row[9] ?? row[8]) as IService['status'],
+      createdAt: Number(row.created_at ?? row[10] ?? row[9]),
+      updatedAt: Number(row.updated_at ?? row[11] ?? row[10]),
      useOneboxRegistry: row.use_onebox_registry ? Boolean(row.use_onebox_registry) : undefined,
      registryRepository: row.registry_repository ? String(row.registry_repository) : undefined,
      registryImageTag: row.registry_image_tag ? String(row.registry_image_tag) : undefined,
@@ -41,6 +41,17 @@ export class AppStoreHandler {
      ),
    );

+    this.typedrouter.addTypedHandler(
+      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_InstallAppTemplate>(
+        'installAppTemplate',
+        async (dataArg) => {
+          await requireAdminIdentity(this.opsServerRef.adminHandler, dataArg);
+          const service = await this.opsServerRef.oneboxRef.appStore.installApp(dataArg.install);
+          return { service };
+        },
+      ),
+    );
+
    // Get services with available upgrades
    this.typedrouter.addTypedHandler(
      new plugins.typedrequest.TypedHandler<interfaces.requests.IReq_GetUpgradeableServices>(
@@ -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)) {
-            this.refreshDcRouterGateway().catch((error) => {
+          if (this.hasRouteSyncSetting(normalizedUpdates)) {
+            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 (onebox.managedDcRouter.getMode() === 'managed') {
-      await onebox.managedDcRouter.restart();
-    } else {
-      await onebox.managedDcRouter.stop();
+    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();
-
-    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)}`);
-      }
-    }));
+    await onebox.externalGateway.syncServiceRoutes();
  }
 }
@@ -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));
+          }
+        },
+      ),
+    );
  }
 }
@@ -9,6 +9,8 @@ export interface IService {
  image: string;
  registry?: string;
  envVars: Record<string, string>;
+  volumes?: IServiceVolume[];
+  publishedPorts?: IServicePublishedPort[];
  port: number;
  domain?: string;
  containerID?: string;
@@ -30,6 +32,27 @@ export interface IService {
  appTemplateVersion?: string;
 }

+export interface IServiceVolume {
+  name?: string;
+  source?: string;
+  mountPath: string;
+  driver?: string;
+  readOnly?: boolean;
+  backup?: boolean;
+  options?: Record<string, string>;
+}
+
+export type TServicePortProtocol = 'tcp' | 'udp';
+
+export interface IServicePublishedPort {
+  targetPort: number;
+  targetPortEnd?: number;
+  publishedPort?: number;
+  publishedPortEnd?: number;
+  protocol?: TServicePortProtocol;
+  hostIp?: string;
+}
+
 // Registry types
 export interface IRegistry {
  id?: number;
@@ -257,6 +280,7 @@ export interface ISetting {
 // Application settings
 export interface IAppSettings {
  serverIP?: string;
+  adminUiDomain?: string;
  cloudflareToken?: string;
  cloudflareZoneId?: string;
  dcrouterMode?: 'managed' | 'external' | 'disabled';
@@ -299,6 +323,8 @@ export interface IServiceDeployOptions {
  image: string;
  registry?: string;
  envVars?: Record<string, string>;
+  volumes?: IServiceVolume[];
+  publishedPorts?: IServicePublishedPort[];
  port: number;
  domain?: string;
  autoSSL?: boolean;
@@ -397,6 +423,8 @@ export interface IBackupServiceConfig {
  image: string;
  registry?: string;
  envVars: Record<string, string>;
+  volumes?: IServiceVolume[];
+  publishedPorts?: IServicePublishedPort[];
  port: number;
  domain?: string;
  useOneboxRegistry?: boolean;
@@ -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);
+  });
+}
@@ -12,6 +12,8 @@ export interface IService {
  image: string;
  registry?: string;
  envVars: Record<string, string>;
+  volumes?: IServiceVolume[];
+  publishedPorts?: IServicePublishedPort[];
  port: number;
  domain?: string;
  containerID?: string;
@@ -33,12 +35,35 @@ export interface IService {
  appTemplateVersion?: string;
 }

+export interface IServiceVolume {
+  name?: string;
+  source?: string;
+  mountPath: string;
+  driver?: string;
+  readOnly?: boolean;
+  backup?: boolean;
+  options?: Record<string, string>;
+}
+
+export type TServicePortProtocol = 'tcp' | 'udp';
+
+export interface IServicePublishedPort {
+  targetPort: number;
+  targetPortEnd?: number;
+  publishedPort?: number;
+  publishedPortEnd?: number;
+  protocol?: TServicePortProtocol;
+  hostIp?: string;
+}
+
 export interface IServiceCreate {
  name: string;
  image: string;
  port: number;
  domain?: string;
  envVars?: Record<string, string>;
+  volumes?: IServiceVolume[];
+  publishedPorts?: IServicePublishedPort[];
  useOneboxRegistry?: boolean;
  registryImageTag?: string;
  autoUpdateOnPush?: boolean;
@@ -57,6 +82,8 @@ export interface IServiceUpdate {
  port?: number;
  domain?: string;
  envVars?: Record<string, string>;
+  volumes?: IServiceVolume[];
+  publishedPorts?: IServicePublishedPort[];
 }

 export interface IContainerStats {
@@ -21,6 +21,7 @@ export interface IManagedDcRouterStatus {
 export interface ISettings {
  cloudflareToken: string;
  cloudflareZoneId: string;
+  adminUiDomain: string;
  dcrouterMode: TDcRouterMode;
  dcrouterManagedImage: string;
  dcrouterManagedOpsPort: number;
@@ -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;
@@ -16,7 +16,8 @@ export interface IAppVersionConfig {
  image: string;
  port: number;
  envVars?: Array<{ key: string; value: string; description: string; required?: boolean }>;
-  volumes?: string[];
+  volumes?: Array<string | data.IServiceVolume>;
+  publishedPorts?: data.IServicePublishedPort[];
  platformRequirements?: {
    mongodb?: boolean;
    s3?: boolean;
@@ -27,6 +28,17 @@ export interface IAppVersionConfig {
  minOneboxVersion?: string;
 }

+export interface IAppInstallOptions {
+  appId: string;
+  version?: string;
+  serviceName: string;
+  domain?: string;
+  port?: number;
+  publishedPorts?: data.IServicePublishedPort[];
+  envVars?: Record<string, string>;
+  autoDNS?: boolean;
+}
+
 export interface IAppMeta {
  id: string;
  name: string;
@@ -76,6 +88,20 @@ export interface IReq_GetAppConfig extends plugins.typedrequestInterfaces.implem
  };
 }

+export interface IReq_InstallAppTemplate extends plugins.typedrequestInterfaces.implementsTR<
+  plugins.typedrequestInterfaces.ITypedRequest,
+  IReq_InstallAppTemplate
+> {
+  method: 'installAppTemplate';
+  request: {
+    identity: data.IIdentity;
+    install: IAppInstallOptions;
+  };
+  response: {
+    service: data.IService;
+  };
+}
+
 export interface IReq_GetUpgradeableServices extends plugins.typedrequestInterfaces.implementsTR<
  plugins.typedrequestInterfaces.ITypedRequest,
  IReq_GetUpgradeableServices
@@ -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;
+  };
+}
@@ -3,6 +3,6 @@
 */
 export const commitinfo = {
  name: '@serve.zone/onebox',
-  version: '1.27.0',
+  version: '1.30.1',
  description: 'Self-hosted container platform with automatic SSL and DNS - a mini Heroku for single servers'
 }
@@ -1048,7 +1048,10 @@ const dispatchCombinedRefreshAction = async () => {
  if (!loginState.isLoggedIn) return;

  try {
-    await systemStatePart.dispatchAction(fetchSystemStatusAction, null);
+    await Promise.all([
+      systemStatePart.dispatchAction(fetchSystemStatusAction, null),
+      networkStatePart.dispatchAction(fetchTrafficStatsAction, null),
+    ]);
  } catch (err) {
    // Silently fail on auto-refresh
  }
@@ -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;
@@ -288,6 +288,34 @@ export class ObViewAppStore extends DeesElement {
        text-align: center;
        color: var(--ci-shade-4, #71717a);
      }
+
+      .footprint-list {
+        display: grid;
+        gap: 8px;
+      }
+
+      .footprint-item {
+        display: flex;
+        justify-content: space-between;
+        gap: 12px;
+        padding: 10px 12px;
+        border: 1px solid var(--ci-shade-2, #27272a);
+        border-radius: 6px;
+        font-size: 13px;
+        color: var(--ci-shade-6, #d4d4d8);
+      }
+
+      .footprint-meta {
+        color: var(--ci-shade-4, #71717a);
+        font-family: monospace;
+      }
+
+      .exposure-warning {
+        margin-top: 10px;
+        color: #fbbf24;
+        font-size: 12px;
+        line-height: 1.5;
+      }
    `,
  ];

@@ -410,6 +438,8 @@ export class ObViewAppStore extends DeesElement {
        </div>
      ` : ''}

+      ${this.renderDeploymentFootprint(config)}
+
      <!-- Version & Image -->
      <div class="detail-card">
        <div class="section-label">Version</div>
@@ -489,6 +519,8 @@ export class ObViewAppStore extends DeesElement {
            Onebox routes this domain to the deployed app. Required when the app uses SERVICE_DOMAIN.
          </div>

+          ${this.renderDeployConfirmation(config)}
+
          <div class="actions-row">
            <button class="btn btn-secondary" @click=${() => { this.currentView = 'grid'; }}>Cancel</button>
            <button class="btn btn-primary" @click=${() => this.handleDeploy()}>
@@ -509,6 +541,73 @@ export class ObViewAppStore extends DeesElement {
    `;
  }

+  private renderDeploymentFootprint(config: interfaces.requests.IAppVersionConfig): TemplateResult | '' {
+    const volumes = this.getConfigVolumes(config);
+    const publishedPorts = config.publishedPorts || [];
+
+    if (volumes.length === 0 && publishedPorts.length === 0) {
+      return '';
+    }
+
+    return html`
+      <div class="detail-card">
+        <div class="section-label">Deployment Footprint</div>
+        <div class="footprint-list">
+          ${volumes.map((volume) => html`
+            <div class="footprint-item">
+              <span>Volume mount</span>
+              <span class="footprint-meta">
+                ${volume.source || volume.name || 'managed volume'}:${volume.mountPath}${volume.readOnly ? ':ro' : ''}
+              </span>
+            </div>
+          `)}
+          ${publishedPorts.map((port) => html`
+            <div class="footprint-item">
+              <span>Published host port</span>
+              <span class="footprint-meta">${this.formatPublishedPort(port)}</span>
+            </div>
+          `)}
+        </div>
+        ${publishedPorts.length > 0 ? html`
+          <div class="exposure-warning">
+            This app publishes raw host ports outside the HTTP proxy. Confirm firewall and network policy before deploying.
+          </div>
+        ` : ''}
+      </div>
+    `;
+  }
+
+  private renderDeployConfirmation(config: interfaces.requests.IAppVersionConfig): TemplateResult | '' {
+    const volumes = this.getConfigVolumes(config);
+    const publishedPorts = config.publishedPorts || [];
+    if (volumes.length === 0 && publishedPorts.length === 0) return '';
+
+    return html`
+      <div class="exposure-warning">
+        Deploying this app will create ${volumes.length} persistent volume(s)
+        ${publishedPorts.length > 0 ? html`and expose ${publishedPorts.length} host port declaration(s)` : ''}.
+      </div>
+    `;
+  }
+
+  private getConfigVolumes(config: interfaces.requests.IAppVersionConfig): interfaces.data.IServiceVolume[] {
+    return (config.volumes || []).map((volume) => {
+      if (typeof volume === 'string') {
+        return { mountPath: volume };
+      }
+      return volume;
+    }).filter((volume) => Boolean(volume.mountPath));
+  }
+
+  private formatPublishedPort(port: interfaces.data.IServicePublishedPort): string {
+    const protocol = port.protocol || 'tcp';
+    const target = port.targetPortEnd ? `${port.targetPort}-${port.targetPortEnd}` : String(port.targetPort);
+    const publishedStart = port.publishedPort || port.targetPort;
+    const publishedEnd = port.publishedPortEnd || (port.targetPortEnd ? publishedStart + (port.targetPortEnd - port.targetPort) : undefined);
+    const published = publishedEnd ? `${publishedStart}-${publishedEnd}` : String(publishedStart);
+    return `${port.hostIp || '0.0.0.0'}:${published}/${protocol} -> ${target}/${protocol}`;
+  }
+
  private async handleViewDetails(e: CustomEvent) {
    const app = e.detail?.app;
    if (!app) return;
@@ -625,25 +724,21 @@ export class ObViewAppStore extends DeesElement {
      }
    }

-    const platformReqs = config.platformRequirements || {};
-    const serviceConfig: interfaces.data.IServiceCreate = {
-      name: this.serviceName || app.id,
-      image: config.image,
-      port: config.port || 80,
-      domain: this.serviceDomain || undefined,
-      envVars,
-      enableMongoDB: platformReqs.mongodb || false,
-      enableS3: platformReqs.s3 || false,
-      enableClickHouse: platformReqs.clickhouse || false,
-      enableRedis: platformReqs.redis || false,
-      enableMariaDB: platformReqs.mariadb || false,
-      appTemplateId: app.id,
-      appTemplateVersion: this.selectedVersion,
-    };
-
    try {
-      await appstate.servicesStatePart.dispatchAction(appstate.createServiceAction, {
-        config: serviceConfig,
+      const identity = appstate.loginStatePart.getState().identity;
+      if (!identity) return;
+      const typedRequest = new plugins.domtools.plugins.typedrequest.TypedRequest<
+        interfaces.requests.IReq_InstallAppTemplate
+      >('/typedrequest', 'installAppTemplate');
+      await typedRequest.fire({
+        identity,
+        install: {
+          appId: app.id,
+          version: this.selectedVersion,
+          serviceName: this.serviceName || app.id,
+          domain: this.serviceDomain || undefined,
+          envVars,
+        },
      });
      setTimeout(() => {
        appRouter.navigateToView('services');
@@ -12,6 +12,20 @@ import {
  type TemplateResult,
 } from '@design.estate/dees-element';

+const byteUnits = ['B', 'KB', 'MB', 'GB', 'TB'];
+
+function getByteUnitIndex(bytes: number): number {
+  if (!bytes || bytes === 0) return 0;
+  return Math.min(Math.floor(Math.log(bytes) / Math.log(1024)), byteUnits.length - 1);
+}
+
+function formatBytes(bytes: number, forcedUnitIndex?: number): string {
+  if ((!bytes || bytes === 0) && forcedUnitIndex === undefined) return '0 B';
+  const unitIndex = forcedUnitIndex ?? getByteUnitIndex(bytes);
+  const value = bytes / Math.pow(1024, unitIndex);
+  return `${value.toFixed(1)} ${byteUnits[unitIndex]}`;
+}
+
@customElement('ob-view-dashboard')
 export class ObViewDashboard extends DeesElement {
  @state()
@@ -69,7 +83,42 @@ export class ObViewDashboard extends DeesElement {
  public static styles = [
    cssManager.defaultStyles,
    shared.viewHostCss,
-    css``,
+    css`
+      .dashboard {
+        display: flex;
+        flex-direction: column;
+        gap: 24px;
+      }
+
+      .section {
+        display: flex;
+        flex-direction: column;
+      }
+
+      .section-title {
+        font-size: 18px;
+        font-weight: 600;
+        color: ${cssManager.bdTheme('#18181b', '#fafafa')};
+        margin: 0 0 12px;
+      }
+
+      .services-grid {
+        display: grid;
+        grid-template-columns: 1fr;
+        gap: 16px;
+        align-items: stretch;
+      }
+
+      .services-grid > * {
+        height: 100%;
+      }
+
+      @media (min-width: 768px) {
+        .services-grid {
+          grid-template-columns: 1fr 1fr;
+        }
+      }
+    `,
  ];

  async connectedCallback() {
@@ -79,6 +128,7 @@ export class ObViewDashboard extends DeesElement {
      appstate.servicesStatePart.dispatchAction(appstate.fetchServicesAction, null),
      appstate.servicesStatePart.dispatchAction(appstate.fetchPlatformServicesAction, null),
      appstate.networkStatePart.dispatchAction(appstate.fetchNetworkStatsAction, null),
+      appstate.networkStatePart.dispatchAction(appstate.fetchTrafficStatsAction, null),
      appstate.networkStatePart.dispatchAction(appstate.fetchCertificatesAction, null),
    ]);
  }
@@ -88,10 +138,15 @@ export class ObViewDashboard extends DeesElement {
    const services = this.servicesState.services;
    const platformServices = this.servicesState.platformServices;
    const networkStats = this.networkState.stats;
+    const trafficStats = this.networkState.trafficStats;
    const certificates = this.networkState.certificates;
+    const statusCounts = trafficStats?.statusCounts || {};

    const runningServices = services.filter((s) => s.status === 'running').length;
    const stoppedServices = services.filter((s) => s.status === 'stopped').length;
+    const memoryUnitIndex = getByteUnitIndex(
+      status?.docker?.memoryTotal || status?.docker?.memoryUsage || 0,
+    );

    const validCerts = certificates.filter((c) => c.isValid).length;
    const expiringCerts = certificates.filter(
@@ -99,65 +154,98 @@ export class ObViewDashboard extends DeesElement {
    ).length;
    const expiredCerts = certificates.filter((c) => !c.isValid).length;

+    const dashboardData = {
+      cluster: {
+        totalServices: services.length,
+        running: runningServices,
+        stopped: stoppedServices,
+        dockerStatus: status?.docker?.running ? 'running' as const : 'stopped' as const,
+      },
+      resourceUsage: {
+        cpu: status?.docker?.cpuUsage || 0,
+        memoryUsed: formatBytes(status?.docker?.memoryUsage || 0, memoryUnitIndex),
+        memoryTotal: formatBytes(status?.docker?.memoryTotal || 0, memoryUnitIndex),
+        networkIn: formatBytes(status?.docker?.networkIn || 0),
+        networkOut: formatBytes(status?.docker?.networkOut || 0),
+        topConsumers: [],
+      },
+      platformServices: platformServices
+        .filter((ps) => ps.status === 'running' || ps.status === 'starting' || ps.status === 'stopping' || ps.isCore)
+        .map((ps) => ({
+          name: ps.displayName,
+          status: ps.status === 'running' ? 'Running' : ps.status === 'starting' ? 'Starting...' : ps.status === 'stopping' ? 'Stopping...' : 'Stopped',
+          running: ps.status === 'running',
+        })),
+      traffic: {
+        requests: trafficStats?.requestCount || 0,
+        errors: trafficStats?.errorCount || 0,
+        errorPercent: trafficStats?.errorRate || 0,
+        avgResponse: trafficStats?.avgResponseTime || 0,
+        reqPerMin: trafficStats?.requestsPerMinute || 0,
+        status2xx: statusCounts['2xx'] || 0,
+        status3xx: statusCounts['3xx'] || 0,
+        status4xx: statusCounts['4xx'] || 0,
+        status5xx: statusCounts['5xx'] || 0,
+      },
+      proxy: {
+        httpPort: String(networkStats?.proxy?.httpPort || 80),
+        httpsPort: String(networkStats?.proxy?.httpsPort || 443),
+        httpActive: networkStats?.proxy?.running || false,
+        httpsActive: networkStats?.proxy?.running || false,
+        routeCount: String(networkStats?.proxy?.routes || 0),
+      },
+      certificates: {
+        valid: validCerts,
+        expiring: expiringCerts,
+        expired: expiredCerts,
+      },
+      dnsConfigured: status?.dns?.configured || false,
+      acmeConfigured: status?.ssl?.configured || false,
+      quickActions: [
+        { label: 'Deploy Service', icon: 'lucide:Plus', primary: true },
+        { label: 'Add Domain', icon: 'lucide:Globe' },
+        { label: 'View Logs', icon: 'lucide:FileText' },
+      ],
+    };
+
    return html`
      <ob-sectionheading>Dashboard</ob-sectionheading>
-      <sz-dashboard-view
-        .data=${{
-          cluster: {
-            totalServices: services.length,
-            running: runningServices,
-            stopped: stoppedServices,
-            dockerStatus: status?.docker?.running ? 'running' : 'stopped',
-          },
-          resourceUsage: {
-            cpu: status?.docker?.cpuUsage || 0,
-            memoryUsed: status?.docker?.memoryUsage || 0,
-            memoryTotal: status?.docker?.memoryTotal || 0,
-            networkIn: status?.docker?.networkIn || 0,
-            networkOut: status?.docker?.networkOut || 0,
-            topConsumers: [],
-          },
-          platformServices: platformServices
-            .filter((ps) => ps.status === 'running' || ps.status === 'starting' || ps.status === 'stopping' || ps.isCore)
-            .map((ps) => ({
-              name: ps.displayName,
-              status: ps.status === 'running' ? 'Running' : ps.status === 'starting' ? 'Starting...' : ps.status === 'stopping' ? 'Stopping...' : 'Stopped',
-              running: ps.status === 'running',
-            })),
-          traffic: {
-            requests: 0,
-            errors: 0,
-            errorPercent: 0,
-            avgResponse: 0,
-            reqPerMin: 0,
-            status2xx: 0,
-            status3xx: 0,
-            status4xx: 0,
-            status5xx: 0,
-          },
-          proxy: {
-            httpPort: networkStats?.proxy?.httpPort || 80,
-            httpsPort: networkStats?.proxy?.httpsPort || 443,
-            httpActive: networkStats?.proxy?.running || false,
-            httpsActive: networkStats?.proxy?.running || false,
-            routeCount: networkStats?.proxy?.routes || 0,
-          },
-          certificates: {
-            valid: validCerts,
-            expiring: expiringCerts,
-            expired: expiredCerts,
-          },
-          dnsConfigured: true,
-          acmeConfigured: true,
-          quickActions: [
-            { label: 'Deploy Service', icon: 'lucide:Plus', primary: true },
-            { label: 'Add Domain', icon: 'lucide:Globe' },
-            { label: 'View Logs', icon: 'lucide:FileText' },
-          ],
-        }}
-        @action-click=${(e: CustomEvent) => this.handleQuickAction(e)}
-        @service-click=${(e: CustomEvent) => this.handlePlatformServiceClick(e)}
-      ></sz-dashboard-view>
+      <div class="dashboard">
+        <section class="section">
+          <h2 class="section-title">Cluster Overview</h2>
+          <sz-status-grid-cluster .stats=${dashboardData.cluster}></sz-status-grid-cluster>
+        </section>
+
+        <section class="section">
+          <h2 class="section-title">Services & Resources</h2>
+          <div class="services-grid">
+            <sz-resource-usage-card .data=${dashboardData.resourceUsage}></sz-resource-usage-card>
+            <sz-platform-services-card
+              .services=${dashboardData.platformServices}
+              @service-click=${(e: CustomEvent) => this.handlePlatformServiceClick(e)}
+            ></sz-platform-services-card>
+          </div>
+        </section>
+
+        <section class="section">
+          <h2 class="section-title">Network & Traffic</h2>
+          <sz-status-grid-network
+            .traffic=${dashboardData.traffic}
+            .proxy=${dashboardData.proxy}
+            .certificates=${dashboardData.certificates}
+          ></sz-status-grid-network>
+        </section>
+
+        <section class="section">
+          <h2 class="section-title">Infrastructure</h2>
+          <sz-status-grid-infra
+            ?dnsConfigured=${dashboardData.dnsConfigured}
+            ?acmeConfigured=${dashboardData.acmeConfigured}
+            .actions=${dashboardData.quickActions}
+            @action-click=${(e: CustomEvent) => this.handleQuickAction(e)}
+          ></sz-status-grid-infra>
+        </section>
+      </div>
    `;
  }

@@ -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;
-        border-bottom: 1px solid ${cssManager.bdTheme('#f4f4f5', '#27272a')};
-        background: ${cssManager.bdTheme('#fafafa', '#101013')};
+        height: 36px;
+        display: flex;
+        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-weight: 600;
-        color: ${cssManager.bdTheme('#18181b', '#fafafa')};
+        font-size: 13px;
+        font-weight: 500;
+        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: 13px;
-        color: ${cssManager.bdTheme('#71717a', '#a1a1aa')};
+        font-size: 12px;
+        color: var(--dees-color-text-muted);
+        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">
-        <div class="gateway-header">
-          <div class="gateway-title">dcrouter Gateway</div>
-          <div class="gateway-subtitle">Run a local managed dcrouter or delegate routing, DNS, and certificates to an external dcrouter.</div>
+      <dees-tile>
+        <div slot="header" class="gateway-header">
+          <div class="gateway-heading">
+            <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">
-          <dees-button
-            .text=${'Save dcrouter Settings'}
-            .type=${'default'}
-            .icon=${'lucide:Save'}
-            @click=${() => this.saveExternalGatewaySettings()}
-          ></dees-button>
+        <div slot="footer" class="gateway-footer">
+          <button class="tile-button primary" type="button" @click=${() => this.saveExternalGatewaySettings()}>
+            Save dcrouter Settings
+          </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 || '',
+      },
+    });
+  }
 }
Author	SHA1	Message	Date
jkunz	070c936a69	v1.30.1 Release / build-and-release (push) Successful in 2m26s Details	2026-05-24 17:42:02 +00:00
jkunz	3f15cbda80	fix(settings-ui): align settings gateway cards with dees-tile footer actions	2026-05-24 17:41:34 +00:00
jkunz	4b48f0056e	v1.30.0 Release / build-and-release (push) Successful in 2m29s Details	2026-05-24 14:46:51 +00:00
jkunz	d91fda084b	feat(admin-ui): add configurable Admin UI domain routing	2026-05-24 14:46:35 +00:00
jkunz	a86d83f835	v1.29.0 Release / build-and-release (push) Successful in 2m33s Details	2026-05-24 11:50:10 +00:00
jkunz	05235ec284	feat(update): add Onebox self-upgrade flow	2026-05-24 11:49:43 +00:00
jkunz	4812621376	v1.28.0 Release / build-and-release (push) Successful in 2m38s Details	2026-05-24 10:19:43 +00:00
jkunz	8b98706d27	chore(release): document catalog update	2026-05-24 10:19:29 +00:00
jkunz	e36207347f	fix(deps): update serve zone catalog	2026-05-24 10:19:17 +00:00
jkunz	5228eeaa23	feat(appstore): add service volumes and published ports	2026-05-24 10:15:56 +00:00