@ours.network/install 1.2.1-nightly.11 → 1.2.1-nightly.13

package/lib/effects.mjs

@@ -20,6 +20,7 @@ import { randomUUID, createHash } from 'node:crypto';
 import { dirname, join, resolve } from 'node:path';
 import { clientPackageNames, maintenanceServices, installationPaths, validateInstallation, consumerServiceState, unitNameForStateDir, launchdLabelForStateDir, messengerServicePlan, selectSourcePackages, resolveSourcePolicy, SERVER_SERVICES } from './plan.mjs';
 import { validateHostProfile } from './target.mjs';
+import { serverBase, validateGatewayDiscovery, gatewayCompose, gatewayNginx, gatewayAddress } from './gateway.mjs';
 import { createServerOnboarding } from './server-onboarding.mjs';
 import { atomicWriteConfig, snapshotConfig, restoreConfig } from './config.mjs';
 import { select as selectOnTty, multiselect as multiselectOnTty, askLine as askLineOnTty } from './prompt.mjs';
@@ -537,6 +538,7 @@ export function networkEffects(effects) {
   const baseEnv = (record) => ({
     OURS_DAEMON_ID: record.instanceId,
     OURS_IMAGE: `${record.project}:runtime`,
+    OURS_GATEWAY_IMAGE: `${record.project}:gateway`,
     OURS_MAINTENANCE_IMAGE: `${record.project}:maintenance`,
     OURS_UID: String(record.uid ?? 1000), OURS_GID: String(record.gid ?? 1000),
     OURS_HOST_PORT: String(record.port ?? 3050),
@@ -548,6 +550,7 @@ export function networkEffects(effects) {
     'compose', '--project-directory', record.workDir, '--file', join(record.workDir,
       record.schema === 1 && existsSync(join(record.workDir, 'docker-compose.legacy.yaml'))
         ? 'docker-compose.legacy.yaml' : 'docker-compose.yaml'),
+    ...(record.gateway ? ['--file', join(record.workDir, 'docker-compose.gateway.yaml')] : []),
     '--project-name', record.project, ...args,
   ];
   const compose = (record, args, options = {}) => effects.run('docker', composeArgs(record, args),
@@ -630,7 +633,7 @@ export function networkEffects(effects) {
       const instanceId = env.OURS_DAEMON_ID || randomUUID();
       if (!/^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/.test(instanceId)) throw new Error('OURS_DAEMON_ID must be a lowercase UUID');
       const project = `ours-${createHash('sha256').update(root).digest('hex').slice(0, 16)}`;
-      return { schema: 2, root, mode, instanceId, project, workDir: join(root, 'runtime'), configPath: installationPaths({ schema: 2, root }).config, sourcesPath: join(root, 'sources.json'), services: [...SERVER_SERVICES], port: 3050, coworkPort: 3052, messengerPort: 8420, messengerIdentity: env.OURS_MESSENGER_IDENTITY || null, uid: 1000, gid: 1000 };
+      return { schema: 2, root, mode, instanceId, project, workDir: join(root, 'runtime'), configPath: installationPaths({ schema: 2, root }).config, sourcesPath: join(root, 'sources.json'), services: [...SERVER_SERVICES, ...(mode === 'docker' ? ['gateway'] : [])], ...(mode === 'docker' ? { gateway: { version: 1 } } : {}), port: 3050, coworkPort: 3052, messengerPort: 8420, messengerIdentity: env.OURS_MESSENGER_IDENTITY || null, uid: 1000, gid: 1000 };
     },
     async serverPreflight(record, operation, { existing, sourcePath = record.sourcesPath, sourceManifest, identityName } = {}) {
       if (existing) {
@@ -709,6 +712,44 @@ export function networkEffects(effects) {
       if (!retainConfig) writePrivateNew(record.configPath, JSON.stringify({ stateDir: record.mode === 'docker' ? '/var/lib/ours' : installationPaths(record).daemon, port: record.port, apiVisibility: 'owner' }, null, 2) + '\n');
     },
     async qualifyDockerRuntime(record) { return qualifyDockerRuntime(record, effects); },
+    async prepareGateway(record) {
+      atomicWriteConfig(join(record.workDir, 'docker-compose.gateway.yaml'), gatewayCompose(record));
+      atomicWriteConfig(join(record.workDir, 'nginx.conf'), gatewayNginx(record));
+      atomicWriteConfig(join(record.workDir, 'Dockerfile.gateway'), readFileSync(join(INSTALLER_ASSETS, 'Dockerfile.gateway'), 'utf8'));
+      await compose(record, ['build', 'gateway'], { stream: true, env: { BUILDKIT_PROGRESS: 'plain' } });
+    },
+    async removeGatewayContainer(record) { await compose(record, ['rm', '-f', 'gateway']); },
+    async verifyGateway(record) {
+      const { prefix } = gatewayAddress(record);
+      const script = `const fs=require('node:fs');(async()=>{
+        const base=${JSON.stringify('http://gateway:8080' + prefix)};
+        const get=async(path,options={})=>{const r=await fetch(base+path,{...options,redirect:'error',signal:AbortSignal.timeout(5000)});if(!r.ok)throw Error('Gateway readiness HTTP '+r.status);return r.json();};
+        const selection=await get('/daemon/selection');
+        if(selection.instanceId!==${JSON.stringify(record.instanceId)})throw Error('Gateway daemon instance mismatch');
+        const denied=await fetch(base+'/cowork/management/rpc',{method:'POST',redirect:'error',signal:AbortSignal.timeout(5000),headers:{'content-type':'application/json'},body:'{}'});
+        await denied.body?.cancel();if(denied.status!==401)throw Error('Gateway management does not reject unauthenticated requests');
+        const token=fs.readFileSync('/var/lib/ours/daemon-token','utf8').trim();
+        const headers={'x-ours-api-token':token,'content-type':'application/json'};
+        const identities=await get('/daemon/identities',{headers});
+        if(!Array.isArray(identities.identities))throw Error('Gateway daemon API invalid');
+        const result=await get('/cowork/management/rpc',{method:'POST',headers,body:JSON.stringify({version:1,id:'installer-readiness',method:'room.list',params:{}})});
+        if(result.version!==1||result.id!=='installer-readiness'||!Array.isArray(result.result)||result.error)throw Error('Gateway Cowork management unavailable');
+      })().catch(()=>{console.error('Authenticated gateway readiness failed');process.exitCode=1;});`;
+      await compose(record, ['exec', '-T', 'daemon', 'node', '-e', script], { sensitive: true });
+    },
+    async qualifyGatewayRuntime(record) {
+      for (const [name, args, capability] of [
+        ['cowork', ['--json', 'capabilities'], 'cowork.http-management-v1'],
+        ['messenger-server', ['capabilities'], 'messenger.gateway-prefix-v1'],
+        ['tg-connector', ['capabilities'], 'telegram.gateway-listener-v1'],
+      ]) {
+        const probe = await effects.run('docker', ['run', '--rm', '--network', 'none', '--read-only', '--entrypoint', 'node', `${record.project}:runtime`, `/opt/ours/node_modules/@ours.network/${name}/dist/cli.js`, ...args]);
+        let value; try { value = JSON.parse(probe.stdout); } catch {}
+        const capabilities = value?.result?.capabilities ?? value?.capabilities;
+        if (!Array.isArray(capabilities) || !capabilities.includes(capability))
+          throw new Error(`Selected ${name} artifact lacks ${capability}; select a compatible release before enabling the gateway`);
+      }
+    },
     async prepareInstallation(record, { runtimeOnly = false } = {}) {
       let copied = false;
       if (!existsSync(record.workDir)) {
@@ -723,12 +764,20 @@ export function networkEffects(effects) {
       else if (!readFileSync(materialized).equals(retained)) throw new Error('Materialized sources differ from retained selection');
       if (record.mode === 'docker') {
         refreshDockerPolicyCopy(record);
+        if (record.gateway) {
+          atomicWriteConfig(join(record.workDir, 'docker-compose.gateway.yaml'), gatewayCompose(record));
+          atomicWriteConfig(join(record.workDir, 'nginx.conf'), gatewayNginx(record));
+        }
         // The installer owns these dependencies in both installation modes.
         const { dependencies } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
         writeFileSync(join(record.workDir, 'scripts/maintenance/package.json'), JSON.stringify({ private: true, type: 'module', dependencies }, null, 2) + '\n', { mode: 0o600 });
         const image = await effects.run('docker', ['image', 'inspect', `${record.project}:runtime`], { allowCodes: [1] });
         if (image.code !== 0) await compose(record, ['build', 'daemon'], { stream: true, env: { BUILDKIT_PROGRESS: 'plain' } });
         await effects.qualifyDockerRuntime(record);
+        if (record.gateway) {
+          await effects.qualifyGatewayRuntime(record);
+          await compose(record, ['build', 'gateway'], { stream: true, env: { BUILDKIT_PROGRESS: 'plain' } });
+        }
         if (runtimeOnly) return;
         await compose(record, ['run', '--rm', '--no-deps', '-T', 'prepare', 'prepare']);
       } else {
@@ -869,7 +918,7 @@ export function networkEffects(effects) {
     async publishServerBuild(record, candidate) {
       const previous = join(candidate.root, 'previous-runtime');
       if (record.mode === 'docker') {
-        for (const target of ['runtime', 'maintenance']) {
+        for (const target of ['runtime', 'maintenance', ...(record.gateway ? ['gateway'] : [])]) {
           const retained = `${candidate.project}:previous-${target}`;
           const found = await effects.run('docker', ['image', 'inspect', retained], { allowCodes: [1] });
           if (found.code !== 0) {
@@ -890,7 +939,7 @@ export function networkEffects(effects) {
         renameSync(candidate.workDir, record.workDir);
       } else privateDirectory(record.workDir);
       if (record.mode === 'docker') {
-        for (const target of ['runtime', 'maintenance']) {
+        for (const target of ['runtime', 'maintenance', ...(record.gateway ? ['gateway'] : [])]) {
           await effects.run('docker', ['tag', `${candidate.project}:${target}`, `${record.project}:${target}`]);
         }
       }
@@ -905,7 +954,7 @@ export function networkEffects(effects) {
     },
     async discardServerBuild(candidate) {
       if (candidate.mode === 'docker') {
-        for (const target of ['runtime', 'maintenance', 'previous-runtime', 'previous-maintenance']) {
+        for (const target of ['runtime', 'maintenance', 'previous-runtime', 'previous-maintenance', ...(candidate.gateway ? ['gateway', 'previous-gateway'] : [])]) {
           const image = `${candidate.project}:${target}`;
           const found = await effects.run('docker', ['image', 'inspect', image], { allowCodes: [1] });
           if (found.code === 0) await effects.run('docker', ['image', 'rm', image]);
@@ -1155,14 +1204,17 @@ export function networkEffects(effects) {
       return JSON.parse(readFileSync(path, 'utf8'));
     },
     async discoverClientProfile(endpoint, credentialPath) {
-      const url = new URL(endpoint);
-      if ((url.protocol !== 'http:' && url.protocol !== 'https:') || url.username || url.password || url.pathname !== '/' || url.search || url.hash)
-        throw new Error('Client endpoint must be an HTTP or HTTPS origin');
-      const response = await fetch(`${url.origin}/selection`, { redirect: 'error', signal: AbortSignal.timeout(5000) });
+      const base = serverBase(endpoint);
+      const request = path => fetch(`${base}${path}`, { redirect: 'error', signal: AbortSignal.timeout(5000) });
+      const discovery = await request('/.well-known/ours');
+      if (discovery.ok) return validateGatewayDiscovery(base, await discovery.json(), resolve(credentialPath));
+      // Only an absent discovery resource denotes a legacy direct daemon. Never
+      // reinterpret authentication, redirect, or malformed metadata as legacy.
+      if (discovery.status !== 404) throw new Error(`Gateway discovery answered HTTP ${discovery.status}`);
+      const response = await request('/selection');
       if (!response.ok) throw new Error(`Daemon selection answered HTTP ${response.status}`);
       const selection = await response.json();
-      // Full metadata and authenticated capability validation follows before publication.
-      return validateHostProfile({ endpoint: url.origin, expectedInstanceId: selection.instanceId, credentialPath: resolve(credentialPath) });
+      return validateHostProfile({ endpoint: base, expectedInstanceId: selection.instanceId, credentialPath: resolve(credentialPath) });
     },
     importClientProfile({ profile, sourcesPath, sources: resolvedSources, integrations, fleetSettingsPath, refresh = false }) {
       const root = join(home, '.ours-client');
@@ -1196,7 +1248,26 @@ export function networkEffects(effects) {
       atomicWriteConfig(configPath, JSON.stringify(saved, null, 2) + '\n');
       return { configPath, profile: validateHostProfile(saved), settings };
     },
-    async acquireClientPackages(configPath, sourcesPath, integrations, { refresh = false, hostCliOnly = false } = {}) {
+    async qualifyInstalledGatewayClient(profile) {
+      if (!profile.installer?.integrations?.includes('fleet')) return;
+      let info;
+      try { info = JSON.parse((await effects.run('ours-fleet', ['version', '--json'])).stdout); } catch {}
+      if (!Array.isArray(info?.capabilities) || !info.capabilities.includes('cowork.http-management-v1'))
+        throw new Error('Installed Fleet does not support gateway HTTP management; upgrade Fleet before gateway-enable');
+    },
+    async qualifyGatewayClient({ profile, sourcesPath, sources, integrations, refresh = false }) {
+      if (!profile.serverUrl || !integrations.includes('fleet')) return;
+      // Acquire into the retained package cache without publishing a profile,
+      // credential, native command, or integration. Normal acquisition rechecks it.
+      const staging = mkdtempSync(join(home, '.ours-gateway-client-'));
+      try {
+        const stagedSources = join(staging, 'sources.json');
+        writeFileSync(stagedSources, sources ? JSON.stringify(sources, null, 2) + '\n' : readFileSync(sourcesPath), { mode: 0o600 });
+        await effects.acquireClientPackages(join(home, '.ours-client/profile.json'), stagedSources, integrations,
+          { refresh, gatewayServerUrl: profile.serverUrl, qualifyOnly: true });
+      } finally { rmSync(staging, { recursive: true, force: true }); }
+    },
+    async acquireClientPackages(configPath, sourcesPath, integrations, { refresh = false, hostCliOnly = false, gatewayServerUrl, qualifyOnly = false } = {}) {
       const manifest = JSON.parse(readFileSync(sourcesPath, 'utf8'));
       // Every client installation includes the native CLI and its SDK dependency.
       const selected = clientPackageNames(integrations);
@@ -1234,6 +1305,13 @@ export function networkEffects(effects) {
         writePrivateNew(join(root, '.packages-ready'), 'ready\n');
       }
       verifyReleaseGraph(root, manifest, { requiredPackages: Object.keys(packages) });
+      if (integrations.includes('fleet') && (gatewayServerUrl || readHostProfileFile(configPath)?.serverUrl)) {
+        let info;
+        try { info = JSON.parse(readFileSync(join(root, 'node_modules/@ours.network/fleet/dist/build-info.json'), 'utf8')); } catch {}
+        if (!Array.isArray(info?.capabilities) || !info.capabilities.includes('cowork.http-management-v1'))
+          throw new Error('Selected Fleet artifact does not support gateway HTTP management; select a compatible client release');
+      }
+      if (qualifyOnly) return;
       const cliPolicy = hostCliOnly ? null : hostCliPolicy(manifest);
       // Local acquisition alone does not publish native commands. Use the user's
       // configured npm prefix and retained dependency closure, including on retry.

package/lib/gateway-transition.mjs

@@ -0,0 +1,87 @@
+import { existsSync, lstatSync, readFileSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { gatewayAddress } from './gateway.mjs';
+import { validateInstallation } from './plan.mjs';
+import { atomicWriteConfig, snapshotConfig, restoreConfig } from './config.mjs';
+
+// Called under the installation lock. No stored state or credentials are changed.
+export async function enableGateway(record, args, effects) {
+  validateInstallation(record, record.root);
+  if (record.mode !== 'docker' || record.schema !== 2 || record.buildTransition || record.layoutConversion)
+    throw new Error('Gateway migration requires a settled schema-2 Docker installation');
+  const journal = join(record.root, 'gateway-transition.json');
+  const recordPath = join(record.root, 'installation.json');
+  const profilePath = join(effects.home, '.ours-client', 'profile.json');
+  const paths = [recordPath, ...['docker-compose.gateway.yaml', 'nginx.conf', 'Dockerfile.gateway'].map(name => join(record.workDir, name)), profilePath];
+  const snapshot = path => {
+    if (existsSync(path)) {
+      const stat = lstatSync(path);
+      if (!stat.isFile() || stat.nlink !== 1 || stat.uid !== process.getuid() || (stat.mode & (path === profilePath || path === journal || path === recordPath ? 0o077 : 0o022)))
+        throw new Error('Gateway migration requires private owned configuration files');
+    }
+    return snapshotConfig(path);
+  };
+  async function rollback(saved) {
+    const phase = value => { saved.phase = value; atomicWriteConfig(journal, JSON.stringify(saved, null, 2) + '\n'); };
+    if (saved.phase === 'switching') phase('rollback-stopping');
+    if (saved.phase === 'rollback-stopping') {
+      await effects.serverLifecycle(saved.candidate, 'stop');
+      await effects.removeGatewayContainer(saved.candidate);
+      phase('rollback-restoring');
+    }
+    if (saved.phase === 'preparing') phase('rollback-restoring');
+    if (saved.phase === 'rollback-restoring') {
+      for (let i = 0; i < paths.length; i++) restoreConfig(paths[i], saved.snapshots[i]);
+      phase('rollback-restarting');
+    }
+    await effects.serverLifecycle(saved.original, 'start', saved.running);
+    unlinkSync(journal);
+  }
+  if (existsSync(journal)) {
+    snapshot(journal);
+    const saved = JSON.parse(readFileSync(journal, 'utf8'));
+    validateInstallation(saved.original, record.root);
+    validateInstallation(saved.candidate, record.root);
+    if (saved.schema !== 1 || !['preparing', 'switching', 'rollback-stopping', 'rollback-restoring', 'rollback-restarting'].includes(saved.phase) || !Array.isArray(saved.snapshots) || saved.snapshots.length !== paths.length
+        || !Array.isArray(saved.running) || saved.running.some(name => !saved.original.services.includes(name)))
+      throw new Error('Invalid retained gateway transition; operator recovery required');
+    await rollback(saved);
+    throw new Error('Interrupted gateway migration rolled back; repeat gateway-enable to begin a new migration');
+  }
+  if (record.gateway) {
+    if (args.serverUrl && args.serverUrl !== gatewayAddress(record).base) throw new Error('Gateway URL is already configured; refusing implicit URL replacement');
+    await effects.verifyGateway(record);
+    return record;
+  }
+  const candidate = { ...record, gateway: { version: 1, ...(args.serverUrl ? { serverUrl: args.serverUrl } : {}) }, services: [...record.services, 'gateway'] };
+  validateInstallation(candidate, record.root);
+  const current = effects.readManagedClientProfile();
+  const selected = current?.expectedInstanceId === record.instanceId && current.endpoint === `http://127.0.0.1:${record.port}`;
+  const saved = { schema: 1, phase: 'preparing', original: record, candidate, snapshots: paths.map(snapshot), running: await effects.serverLifecycle(record, 'status') };
+  // Reject old service artifacts before stopping the working deployment.
+  await effects.qualifyGatewayRuntime(candidate);
+  if (selected) await effects.qualifyInstalledGatewayClient(current);
+  atomicWriteConfig(journal, JSON.stringify(saved, null, 2) + '\n');
+  try {
+    await effects.prepareGateway(candidate);
+    saved.phase = 'switching';
+    atomicWriteConfig(journal, JSON.stringify(saved, null, 2) + '\n');
+    await effects.serverLifecycle(record, 'stop');
+    await effects.serverLifecycle(candidate, 'start', [...new Set([...saved.running, 'daemon', 'cowork', 'gateway'])]);
+    await effects.verifyGateway(candidate);
+    if (selected) {
+      const serverUrl = gatewayAddress(candidate).base;
+      atomicWriteConfig(profilePath, JSON.stringify({ ...current, serverUrl, endpoint: serverUrl + '/daemon' }, null, 2) + '\n');
+    }
+    // Preserve the running/stopped selection; gateway follows a running daemon.
+    const keep = [...saved.running, ...(saved.running.includes('daemon') ? ['gateway'] : [])];
+    await effects.serverLifecycle(candidate, 'stop', candidate.services.filter(name => !keep.includes(name)));
+    atomicWriteConfig(recordPath, JSON.stringify(candidate, null, 2) + '\n');
+    unlinkSync(journal);
+    return candidate;
+  } catch (cause) {
+    try { await rollback(saved); }
+    catch (rollbackError) { throw new AggregateError([cause, rollbackError], 'Gateway migration and rollback failed; retained journal requires gateway-enable recovery'); }
+    throw new Error('Gateway migration failed; previous routing, profile and service selection restored', { cause });
+  }
+}

package/lib/gateway.mjs

@@ -0,0 +1,142 @@
+/** One public URL; fixed same-origin service paths are never supplied by a peer. */
+export const GATEWAY_SERVICES = Object.freeze({daemon:'/daemon',cowork:'/cowork',telegram:'/tg-connector',messenger:'/messenger'});
+export function serverBase(value) {
+  if(typeof value!=='string'||/[\s\\?#]/.test(value)||!/^https?:\/\//.test(value))throw new Error('Server URL must be an HTTP or HTTPS base URL');
+  const url=new URL(value);
+  if(url.username||url.password)throw new Error('Server URL cannot contain credentials');
+  return url.origin+url.pathname.replace(/\/+$/,'');
+}
+export function gatewayDiscovery(record) {
+  return {schema:1,instanceId:record.instanceId,services:GATEWAY_SERVICES,capabilities:['ours.gateway-v1','cowork.http-management-v1']};
+}
+export function validateGatewayDiscovery(url,value,credentialPath) {
+  const base=serverBase(url);
+  if(value?.schema!==1||!/^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/.test(value.instanceId??'')
+    ||!Array.isArray(value.capabilities)||!value.capabilities.includes('ours.gateway-v1')||!value.capabilities?.includes('cowork.http-management-v1')
+    ||Object.keys(GATEWAY_SERVICES).some(key=>value.services?.[key]!==GATEWAY_SERVICES[key]))throw new Error('Incompatible server gateway discovery');
+  return {serverUrl:base,endpoint:base+'/daemon',expectedInstanceId:value.instanceId,credentialPath};
+}
+export function gatewayAddress(record) {
+  const base = serverBase(record.gateway?.serverUrl ?? `http://127.0.0.1:${record.port}`);
+  const url = new URL(base);
+  if (!/^\/(?:[A-Za-z0-9_-]+\/)*[A-Za-z0-9_-]*$/.test(url.pathname)) throw new Error('Gateway base path must contain plain URL path segments');
+  return { base, origin: url.origin, prefix: url.pathname.replace(/\/$/, '') };
+}
+export function gatewayCompose(record) {
+  const { origin, prefix } = gatewayAddress(record);
+  return `services:
+  daemon:
+    ports: !reset []
+  telegram:
+    ports: !reset []
+    environment:
+      OURS_TG_CONTROL_HOST: "0.0.0.0"
+  cowork:
+    ports: !reset []
+    environment:
+      OURS_COWORK_HTTP_MANAGEMENT: "1"
+      OURS_COWORK_PUBLIC_ORIGIN: ${JSON.stringify(origin)}
+  messenger:
+    ports: !reset []
+    environment:
+      OURS_MESSENGER_PUBLIC_ORIGIN: ${JSON.stringify(origin)}
+      OURS_MESSENGER_BASE_PATH: ${JSON.stringify(prefix + "/messenger/")}
+  gateway:
+    image: "\${OURS_GATEWAY_IMAGE:-${record.project}:gateway}"
+    build:
+      context: .
+      dockerfile: Dockerfile.gateway
+    user: "101:101"
+    read_only: true
+    cap_drop: [ALL]
+    security_opt: [no-new-privileges:true]
+    tmpfs: ["/tmp:rw,nosuid,nodev,noexec,size=32m,mode=1777"]
+    networks: [ours]
+    ports:
+      - {target: 8080, published: "${record.port}", host_ip: "127.0.0.1"}
+    restart: unless-stopped
+    stop_grace_period: 10s
+    healthcheck:
+      test: [CMD, wget, -q, -O, /dev/null, http://127.0.0.1:8080/healthz]
+      interval: 5s
+      timeout: 3s
+      retries: 6
+`;
+}
+export function gatewayNginx(record) {
+  const { prefix: basePath } = gatewayAddress(record);
+  const routes=[['daemon',3050],['cowork',record.coworkPort??3052],['telegram',3051],['messenger',8420]];
+  const upstream=Object.fromEntries(routes);
+  for(const port of Object.values(upstream))if(!Number.isInteger(port)||port<1||port>65535)throw new Error('Invalid gateway upstream port');
+  const route=(name,servicePath)=> { const prefix=basePath+servicePath; return`location ${prefix}/ {
+      set $upstream_${name} http://${name}:${upstream[name]};
+      rewrite ^${prefix}/(.*)$ /$1 break;
+      proxy_pass $upstream_${name};
+      proxy_set_header Host $http_host;
+      proxy_set_header X-Forwarded-Proto $scheme;
+      proxy_set_header Upgrade $http_upgrade;
+      proxy_set_header Connection $connection_upgrade;
+      proxy_http_version 1.1;
+      proxy_buffering off;
+      proxy_read_timeout 300s;
+    }`; };
+  return `worker_processes 1;
+pid /tmp/nginx.pid;
+error_log /dev/stderr warn;
+events { worker_connections 1024; }
+http {
+  access_log off;
+  client_body_temp_path /tmp/client;
+  proxy_temp_path /tmp/proxy;
+  fastcgi_temp_path /tmp/fastcgi;
+  uwsgi_temp_path /tmp/uwsgi;
+  scgi_temp_path /tmp/scgi;
+  proxy_next_upstream off;
+  resolver 127.0.0.11 valid=5s ipv6=off;
+  map $http_upgrade $connection_upgrade { default upgrade; '' close; }
+  server {
+    listen 8080;
+    server_name _;
+    client_max_body_size 64m;
+    location = /healthz { return 200 'ok'; }
+    location = ${basePath}/.well-known/ours { default_type application/json; return 200 '${JSON.stringify(gatewayDiscovery(record))}'; }
+    location = / { return 302 ${basePath}/messenger/; }
+    location = ${basePath}/daemon { return 308 ${basePath}/daemon/; }
+    location = ${basePath}/cowork { return 308 ${basePath}/cowork/; }
+    location = ${basePath}/tg-connector { return 308 ${basePath}/tg-connector/; }
+    location = ${basePath}/messenger { return 308 ${basePath}/messenger/; }
+    # Never publish the unauthenticated loopback browser RPC. Management has its
+    # own application-level credential check and rejects browser-origin requests.
+    location = ${basePath}/cowork/rpc { return 403; }
+    location ${basePath}/cowork/management/ {
+      client_max_body_size 1m;
+      set $management http://cowork:${upstream.cowork};
+      rewrite ^${basePath}/cowork/(.*)$ /$1 break;
+      proxy_pass $management;
+      proxy_set_header Host $http_host;
+      proxy_http_version 1.1;
+      proxy_read_timeout 60s;
+    }
+    ${route('daemon','/daemon')}
+    ${route('cowork','/cowork')}
+    # Telegram's control API is local-only; no unauthenticated remote proxy.
+    location ${basePath}/tg-connector/ {
+      auth_request /_server_auth;
+      set $telegram http://telegram:3051;
+      rewrite ^${basePath}/tg-connector/(.*)$ /$1 break;
+      proxy_pass $telegram;
+    }
+    location = /_server_auth {
+      internal;
+      set $auth http://daemon:3050/identities;
+      proxy_pass $auth;
+      proxy_pass_request_body off;
+      proxy_set_header Content-Length "";
+      proxy_set_header X-Ours-Api-Token $http_x_ours_api_token;
+    }
+    ${route('messenger','/messenger')}
+    location / { return 404; }
+  }
+}
+`;
+}

package/lib/orchestrate.mjs

@@ -1,3 +1,4 @@
+import { enableGateway } from './gateway-transition.mjs';
 import { executeLegacyMigration } from './legacy-migration.mjs';
 // ours-install v3 — the orchestrator.
 //
@@ -1324,6 +1325,12 @@ async function executeServerCommand(args, effects) {
     record = effects.newInstallation(args.stateDir, args.mode);
     for (const key of ['port', 'coworkPort', 'messengerPort']) if (args[key] !== undefined) record[key] = args[key];
   }
+  if (effects.readJson(join(record.root, 'gateway-transition.json')) && args.operation !== 'gateway-enable' && args.operation !== 'status') throw new Error('Interrupted gateway migration; run server gateway-enable before other changes');
+  if (args.serverUrl && args.operation === 'install') {
+    if (!record.gateway) throw new Error('Use server gateway-enable to migrate an existing Docker installation');
+    if (existing && record.gateway.serverUrl !== args.serverUrl) throw new Error('Conflicting gateway server URL');
+    record.gateway = { ...record.gateway, serverUrl: args.serverUrl };
+  }
   if (record.layoutConversion && !['install', 'start', 'stop', 'status'].includes(args.operation)) {
     throw new Error('Layout conversion is incomplete; resume with server install or server start before changing state or authority');
   }
@@ -1390,7 +1397,10 @@ async function executeServerCommand(args, effects) {
     } else {
       await installStage('Service startup', 'Start the daemon and selected services, then check readiness.', () => effects.serverLifecycle(record, 'start'));
     }
+    if (record.gateway) await effects.verifyGateway(record);
     if (showInstallProgress) effects.out(progress(installStageCount, installStageCount, 'Installation complete', 'The selected services are ready.'));
+  } else if (args.operation === 'gateway-enable') {
+    await enableGateway(record, args, effects);
   } else if (['backup', 'restore', 'reset'].includes(args.operation)) {
     await effects.serverMaintenance(record, args);
   } else if (['update', 'rebuild'].includes(args.operation)) {
@@ -1479,6 +1489,7 @@ export async function runClientCommand(command, effects) {
     resolvedSources = await effects.resolveSourcePolicy(policy, 'client', selectedClients);
   }
   effects.out(progress(0, 4, 'Client configuration', 'Prepare the selected integrations and private connection profile.'));
+  if (profile.serverUrl && integrations.includes('fleet')) await effects.qualifyGatewayClient({ profile, sourcesPath, sources: resolvedSources, integrations, refresh: !!command.preset });
   const imported = effects.importClientProfile({ profile, sourcesPath, sources: resolvedSources, integrations, fleetSettingsPath, refresh: !!command.preset });
   let phase = 'Validate saved server connection';
   try {

package/lib/plan.mjs

@@ -1,3 +1,4 @@
+import { gatewayAddress } from './gateway.mjs';
 // ours-install v3 — daemon creation and boot-service installation.
 //
 // Pure planning code, like lib/target.mjs: the orchestrator
@@ -362,9 +363,14 @@ export function validateInstallation(record, root) {
     || !/^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/.test(record.instanceId ?? '')
     || !/^ours-[a-z0-9]+$/.test(record.project ?? '')
     || (record.sourcePolicyHash !== undefined && !/^[0-9a-f]{64}$/.test(record.sourcePolicyHash))
-    || !Array.isArray(record.services) || record.services[0] !== 'daemon' || new Set(record.services).size !== record.services.length || record.services.some(s => !SERVER_SERVICES.includes(s))) {
+    || !Array.isArray(record.services) || record.services[0] !== 'daemon' || new Set(record.services).size !== record.services.length || record.services.some(s => !SERVER_SERVICES.includes(s) && !(s === 'gateway' && record.gateway?.version === 1))) {
     throw new Error('Invalid or conflicting installation selection');
   }
+  if (record.gateway !== undefined && (record.schema !== 2 || record.mode !== 'docker' || record.gateway?.version !== 1
+    || Object.keys(record.gateway).some(key => !['version', 'serverUrl'].includes(key)) || record.services.at(-1) !== 'gateway')) {
+    throw new Error('Invalid gateway installation selection');
+  }
+  if (record.gateway) gatewayAddress(record);
   if (record.layoutConversion !== undefined) {
     // DEPRECATED (introduced in 2.0): legacy managed-layout conversion only.
     // Removal target: 3.0, after supported installs convert and upgrade inputs
@@ -402,7 +408,7 @@ export function validateInstallation(record, root) {
       throw new Error('Invalid server build transition');
     }
     validateInstallation(candidate, candidate.root);
-    for (const key of ['schema', 'mode', 'instanceId', 'services', 'port', 'coworkPort', 'messengerPort', 'messengerIdentity', 'uid', 'gid']) {
+    for (const key of ['schema', 'mode', 'instanceId', 'services', 'gateway', 'port', 'coworkPort', 'messengerPort', 'messengerIdentity', 'uid', 'gid']) {
       if (JSON.stringify(candidate[key]) !== JSON.stringify(record[key])) throw new Error('Conflicting server build candidate');
     }
   }

package/lib/server-onboarding.mjs

@@ -1,3 +1,4 @@
+import { gatewayAddress } from './gateway.mjs';
 /** Human bootstrap and local client handoff through the existing owner interfaces. */
 import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import { join, resolve, isAbsolute } from 'node:path';
@@ -82,7 +83,8 @@ export function createServerOnboarding(effects, { compose, localEnv, bin }) {
         const settings = JSON.parse(readFileSync(fleetSettingsPath, 'utf8'));
         if (!settings || typeof settings !== 'object' || Array.isArray(settings)) throw new Error('Fleet settings must be a JSON object');
       }
-      const endpoint = `http://127.0.0.1:${record.port}`;
+      const serverUrl = record.gateway ? gatewayAddress(record).base : undefined;
+      const endpoint = serverUrl ? `${serverUrl}/daemon` : `http://127.0.0.1:${record.port}`;
       const current = effects.readManagedClientProfile();
       if (current && (current.endpoint !== endpoint || current.expectedInstanceId !== record.instanceId)) throw new Error('Managed client already selects another server; no credential was issued');
       privatePath(record.root, true);
@@ -93,13 +95,16 @@ export function createServerOnboarding(effects, { compose, localEnv, bin }) {
       const published = join(root, 'issued-' + randomUUID());
       const credential = join(stage, 'credential');
       try {
-        effects.out?.('Issuing a separate local client credential with the retained server authority.');
-        try { await effects.serverAccess(record, 'access-issue', { output: credential }); }
-        catch { throw new Error('Client credential issuance failed; existing profiles were retained'); }
-        const stat = privatePath(credential);
-        if (stat.size > 4096 || !readFileSync(credential, 'utf8').trim()) throw new Error('Issued client credential is empty or invalid');
+        if (!current) {
+          effects.out?.('Issuing a separate local client credential with the retained server authority.');
+          try { await effects.serverAccess(record, 'access-issue', { output: credential }); }
+          catch { throw new Error('Client credential issuance failed; existing profiles were retained'); }
+        }
+        const retainedCredential = current?.credentialPath ?? credential;
+        const stat = privatePath(retainedCredential);
+        if (stat.size > 4096 || !readFileSync(retainedCredential, 'utf8').trim()) throw new Error('Issued client credential is empty or invalid');
         const profile = {
-          ...validateHostProfile({ endpoint, expectedInstanceId: record.instanceId, credentialPath: join(published, 'credential') }),
+          ...validateHostProfile({ ...(serverUrl ? { serverUrl } : {}), endpoint, expectedInstanceId: record.instanceId, credentialPath: current?.credentialPath ?? join(published, 'credential') }),
           installer: { integrations: [...integrations], ...(fleetSettingsPath !== undefined ? { fleetSettingsPath } : {}) },
         };
         writeFileSync(join(stage, 'profile.json'), JSON.stringify(profile, null, 2) + '\n', { flag: 'wx', mode: 0o600 });

package/lib/setup-options.mjs

@@ -1,9 +1,10 @@
+import { serverBase } from './gateway.mjs';
 import { join, resolve, isAbsolute, dirname } from 'node:path';
 
 const scopes = ['all', 'server', 'client'];
 const integrations = ['codex', 'claude-code', 'fleet'];
 const valueFlags = new Map(Object.entries({
-  '--scope': 'scope', '--action': 'operation', '--mode': 'mode', '--state-dir': 'stateDir',
+  '--server-url': 'serverUrl', '--scope': 'scope', '--action': 'operation', '--mode': 'mode', '--state-dir': 'stateDir',
   '--identity-name': 'identityName', '--integrations': 'integrations', '--fleet-settings': 'fleetSettingsPath',
   '--config': 'config', '--sources': 'sources', '--migrate-from': 'migrateFrom', '--port': 'port', '--cowork-port': 'coworkPort', '--messenger-port': 'messengerPort',
 }));
@@ -40,6 +41,10 @@ export function validateSetupOptions(input, { interactive = input?.interactive =
   if (missing.length) throw new Error(`Missing required setup options: ${missing.join(', ')}`);
   if (options.mode === 'native') options.mode = 'packages';
   if (server && !['packages', 'docker'].includes(options.mode)) throw new Error('Mode must be packages (or native) or docker');
+  if (options.serverUrl !== undefined) {
+    if (!server || options.mode !== 'docker' || options.operation !== 'install') throw new Error('--server-url requires Docker server installation');
+    options.serverUrl = serverBase(options.serverUrl);
+  }
   if (server && options.config !== undefined) throw new Error('--config is only valid for client scope');
   if (!server) for (const key of ['mode', 'stateDir', 'identityName', ...Object.keys(defaults), 'compatible', 'migrate']) {
     if (options[key] !== undefined) throw new Error(`${key} is only valid for server or all scope`);

package/lib/setup.mjs

@@ -1,3 +1,4 @@
+import { gatewayAddress } from './gateway.mjs';
 import { inspectLegacyMigration } from './legacy-migration.mjs';
 import { join } from 'node:path';
 import { parseSetupArgs, collectSetupOptions, validateSetupOptions } from './setup-options.mjs';
@@ -10,7 +11,7 @@ import { USAGE } from './usage.mjs';
 import { validateIdentityName } from './server-onboarding.mjs';
 import { validateFleetSettings } from './fleet-settings.mjs';
 
-const maintenance = new Set(['status', 'start', 'stop', 'restart', 'rebuild', 'access-issue', 'access-replace', 'backup', 'restore', 'reset']);
+const maintenance = new Set(['status', 'start', 'stop', 'restart', 'rebuild', 'gateway-enable', 'access-issue', 'access-replace', 'backup', 'restore', 'reset']);
 
 export function completeReleasePolicy(retained, supplied) {
   if (retained?.release) {
@@ -67,7 +68,7 @@ export async function prepareSetupPlan(options, effects) {
     }
     // Reject a local client already attached to another server before changing the server.
     const saved = options.scope === 'all' ? effects.readManagedClientProfile() : null;
-    if (saved && (!plan.existing || saved.expectedInstanceId !== plan.existing.instanceId || saved.endpoint !== `http://127.0.0.1:${plan.port}`)) {
+    if (saved && (!plan.existing || saved.expectedInstanceId !== plan.existing.instanceId || saved.endpoint !== (plan.existing?.gateway ? gatewayAddress(plan.existing).base + '/daemon' : `http://127.0.0.1:${plan.port}`))) {
       throw new InstallUsageError('This user already has clients attached to a different server; their saved connection was not changed');
     }
   } else {