@jiayunxie/aerial 0.1.11 → 0.2.1

package/README.md

@@ -11,7 +11,7 @@ It runs locally on `127.0.0.1:18181`. Your GitHub token and Aerial key stay on y
 
 Requirements:
 
-- Node.js 22+
+- Node.js 24+
 - A GitHub account with an active Copilot subscription
 - Codex CLI and/or Claude Code installed
 
@@ -21,6 +21,14 @@ npm install -g @jiayunxie/aerial
 
 ## Quick Start
 
+If you are on a restricted network or Claude models are missing from `aerial probe`, enable Aerial's upstream proxy mode first:
+
+```bash
+aerial proxy enable
+```
+
+`proxy enable` discovers local HTTP(S) and SOCKS5 proxies from macOS network settings, PAC files, environment hints, and common local proxy ports, then validates the route before saving anything.
+
 1. Sign in to GitHub:
 
 ```bash
@@ -93,10 +101,25 @@ To inspect the full model matrix:
 aerial probe
 ```
 
+## Upstream Proxy
+
+Aerial can route its own GitHub and Copilot upstream traffic through a local HTTP(S) or SOCKS5 proxy while keeping the Codex/Claude client-facing server on `127.0.0.1:18181`.
+
+```bash
+aerial proxy status   # show direct/proxy egress IP, region, and Copilot route counts
+aerial proxy enable   # auto-discover and validate a working local proxy
+aerial proxy disable  # return upstream traffic to direct mode
+```
+
+This is useful when Copilot exposes different model routes by region. In direct mode, `proxy status` reports the direct egress. In enabled mode, it reports the selected local proxy endpoint, proxied egress, and whether the `messages` route is visible for Claude Code. SOCKS5 endpoints, including Shadowsocks PAC entries, are bridged internally; users do not need to find or configure an HTTP proxy port by hand.
+
+Advanced override: `AERIAL_UPSTREAM_PROXY` can be set to a bare `http://`, `https://`, `socks://`, `socks5://`, or `socks5h://` proxy endpoint. Path-prefixed proxy URLs are intentionally ignored.
+
 ## Daily Commands
 
 ```bash
 aerial status           # setup, login, service, and health summary
+aerial proxy status     # upstream proxy mode, egress, and route visibility
 aerial service install  # install and start the background service
 aerial doctor           # local diagnostics
 aerial disable          # restore client configs and uninstall the service
@@ -111,6 +134,7 @@ Advanced service lifecycle commands are documented in `docs/usage.md`.
 - `Missing GitHub token`: run `aerial login`.
 - `Invalid or missing Aerial API key`: rerun `aerial setup codex` or `aerial setup claude`, then restart the client.
 - No models listed during setup: run `aerial login` first, then retry setup.
+- Claude models or the `messages` route are missing: run `aerial proxy enable`, then `aerial probe`.
 - Port conflict on `18181`: run `aerial status` to see whether another process is using the port.
 - Need to undo setup: run `aerial disable`, or restore one client with `aerial setup restore <codex|claude> --latest`.
 

package/docs/usage.md

@@ -39,6 +39,26 @@ aerial login
 
 Open the printed URL, enter the user code, and authorize the GitHub OAuth device flow. Aerial saves the GitHub access token locally and exchanges it for short-lived Copilot JWTs when proxy requests arrive.
 
+## 3.5 Upstream Proxy Mode
+
+```bash
+aerial proxy status
+aerial proxy enable
+aerial proxy disable
+```
+
+Aerial's local server always listens on `127.0.0.1:18181`, but its own GitHub and Copilot upstream traffic can optionally go through a local HTTP(S) or SOCKS5 proxy. This helps in restricted regions where direct Copilot egress may return a smaller model catalog or omit Claude-compatible `/v1/messages` routes.
+
+`aerial proxy enable` auto-discovers candidates from `AERIAL_UPSTREAM_PROXY`, standard proxy environment variables, macOS `scutil --proxy`, PAC files, common local SOCKS5 ports such as `1086` and `1080`, and common local HTTP proxy ports such as `1087` and `7890`. It validates that a candidate can reach GitHub and return GitHub's `/rate_limit` JSON before saving `upstreamProxyMode=auto` and the selected endpoint in Aerial's config. If no candidate works, it exits non-zero and leaves the previous config unchanged. PAC files are read with a 1 MiB limit.
+
+SOCKS5 endpoints are first-class candidates. When Aerial selects `socks5://127.0.0.1:1086` from a Shadowsocks PAC file, the config stores that original endpoint; at runtime Aerial starts a loopback-only HTTP CONNECT bridge internally so GitHub/Copilot `fetch` and WebSocket traffic can use the same proxy dispatcher path as HTTP(S) proxies. Users do not need to discover or configure a separate HTTP bridge port.
+
+For explicit overrides, `AERIAL_UPSTREAM_PROXY` accepts bare `http://`, `https://`, `socks://`, `socks5://`, and `socks5h://` endpoints. Aerial intentionally ignores proxy URLs with path, query, or hash components, because upstream proxy dispatchers expect a host-level proxy endpoint.
+
+`aerial proxy status` prints the active mode, the direct or proxied egress IP/region, and the current Copilot route counts from `aerial probe` (`responses`, `responsesWebSocket`, `messages`, and `chat`). In disabled mode the endpoint is `direct`; in enabled mode the endpoint is the selected local proxy plus its discovery source. Use `--json` for the stable `aerial.proxy-status.v1` shape. If a proxy URL contains userinfo, status and enable diagnostics redact it before printing.
+
+`aerial proxy disable` switches back to direct upstream traffic and clears the saved proxy endpoint. Running Aerial processes read this config for each upstream request, so no service restart is required for proxy enable/disable.
+
 ## 4. Start Server
 
 ```bash
@@ -99,12 +119,15 @@ Non-Opus-4.7 Claude requests are not modified.
 
 ```bash
 aerial status
+aerial proxy status
 aerial doctor
 aerial probe
 ```
 
 `aerial status` is the top-level daily check. It combines setup state, local auth files, service state, and health into one short report. Use `--json` for a machine-readable `aerial.status.v1` document.
 
+`aerial proxy status` is the network-path check. Use it when Claude models disappear, when `/v1/messages` is `0`, or when you want to confirm whether direct or proxied egress is being used.
+
 `aerial status --json` top-level fields: `schema`, `ok`, `setup`, `service`, `nextSteps`, `hints`. `nextSteps` lists actions you must take to reach `ok: true` (login / setup / service install / recover local key). `hints` lists non-blocking advisories that you should still pay attention to, such as `AERIAL_GITHUB_TOKEN` being set for the current shell only (the background service may not see it after reboot). Example:
 
 ```json
@@ -217,7 +240,7 @@ Aerial ships a thin platform wrapper around the user-mode service primitives pro
 - Windows: a Task Scheduler task named `AerialLocalProxy`, `/SC ONLOGON /RL LIMITED`, executes a PowerShell wrapper at `<config-dir>\bin\aerial-service.ps1` (default `%APPDATA%\aerial\bin\aerial-service.ps1`). The wrapper is regenerated on every `aerial service install`. The `/TR` argument is wrapped in escaped quotes so paths that contain spaces or non-ASCII characters work without manual quoting.
 - Linux: not implemented in this release. `aerial service install|start|stop|restart|uninstall` throws an unsupported-platform error and exits 1; `aerial service status --json` still emits a schema-valid document with `"supported": false` and exits 1. Run `aerial start` directly or wrap it in your own init system.
 
-Both wrappers do the same three things before exec-ing the proxy: (1) startup-rotate the captured stdio log (`aerial-stdio.log` → `.1` → `.2` → `.3`) if it has grown beyond the configured cap; (2) export `AERIAL_LOG_FILE=<config-dir>/logs/aerial.log`, plus `AERIAL_LOG_MAX_BYTES` and `AERIAL_LOG_BACKUPS` (default `5242880` / `3`, or whatever value was present in the installer's environment — see below), and — when `AERIAL_CONFIG_DIR` was set at install time — re-export `AERIAL_CONFIG_DIR` so the service sees the same config root as the installer; (3) `exec` `node src/cli.js start --host <host> --port <port>` with stdout and stderr appended to `aerial-stdio.log`. The structured event log is opt-in via `AERIAL_LOG_FILE`: when this env var is set (always set by the wrapper, never by foreground `aerial start`), structured events go to that file only; when unset, they go to stderr only. There is no double-write.
+Both wrappers do the same three things before exec-ing the proxy: (1) startup-rotate the captured stdio log (`aerial-stdio.log` → `.1` → `.2` → `.3`) if it has grown beyond the configured cap; (2) export `AERIAL_LOG_FILE=<config-dir>/logs/aerial.log`, plus `AERIAL_LOG_MAX_BYTES` and `AERIAL_LOG_BACKUPS` (default `5242880` / `3`, or whatever value was present in the installer's environment — see below), and — when `AERIAL_CONFIG_DIR` was set at install time — re-export `AERIAL_CONFIG_DIR` so the service sees the same config root as the installer; (3) `exec` `node src/cli.js start --host <host> --port <port>` with stdout and stderr appended to `aerial-stdio.log`. The service wrapper prefers a Node.js 24+ binary; on macOS, if the installer is running under an older Node and Codex's bundled Node 24+ exists at `/Applications/Codex.app/Contents/Resources/node`, Aerial uses that for the generated wrapper. Set `AERIAL_SERVICE_NODE` before `aerial service install` to override this selection explicitly. The structured event log is opt-in via `AERIAL_LOG_FILE`: when this env var is set (always set by the wrapper, never by foreground `aerial start`), structured events go to that file only; when unset, they go to stderr only. There is no double-write.
 
 Wrapper env values are baked in at install time. If you set `AERIAL_LOG_MAX_BYTES` and/or `AERIAL_LOG_BACKUPS` in the shell before running `aerial service install`, the generated wrapper hard-codes those values and the next start of the service inherits them. Changing the env in another shell after install has no effect on the already-installed wrapper. To apply new values to an already-managed service, rerun `aerial service install` (which always regenerates the definition, including the wrapper) and then `aerial service restart` to swap the running process onto the regenerated wrapper.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jiayunxie/aerial",
-  "version": "0.1.11",
-  "description": "Local-only GitHub Copilot proxy for Codex CLI and Claude Code.",
+  "version": "0.2.1",
+  "description": "Local GitHub Copilot proxy for Codex CLI and Claude Code with smart HTTP(S)/SOCKS5 upstream proxy support.",
   "type": "module",
   "private": false,
   "homepage": "https://github.com/Xiejiayun/aerial#readme",
@@ -16,7 +16,11 @@
     "copilot",
     "codex",
     "claude-code",
-    "local-proxy"
+    "local-proxy",
+    "upstream-proxy",
+    "socks5",
+    "shadowsocks",
+    "restricted-network"
   ],
   "files": [
     "src",
@@ -34,7 +38,7 @@
     "prepublishOnly": "npm test"
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=24"
   },
   "license": "MIT",
   "publishConfig": {
@@ -42,6 +46,7 @@
   },
   "dependencies": {
     "smol-toml": "^1.6.1",
+    "socks": "^2.8.9",
     "undici": "^7.25.0"
   }
 }

package/src/auth.js

@@ -2,6 +2,7 @@ import fs from "node:fs";
 import { COPILOT_TOKEN_URL, GITHUB_CLIENT_ID } from "./constants.js";
 import { githubTokenPath, writePrivateFile } from "./paths.js";
 import { logEvent } from "./log.js";
+import { upstreamFetch } from "./upstream-fetch.js";
 
 let cachedCopilotToken;
 let refreshPromise;
@@ -12,7 +13,7 @@ function formBody(values) {
 
 export async function startDeviceFlow() {
   logEvent("login_start");
-  const response = await fetch("https://github.com/login/device/code", {
+  const response = await upstreamFetch("https://github.com/login/device/code", {
     method: "POST",
     headers: { accept: "application/json", "content-type": "application/x-www-form-urlencoded" },
     body: formBody({ client_id: GITHUB_CLIENT_ID, scope: "read:user copilot" })
@@ -25,7 +26,7 @@ export async function pollDeviceFlow(deviceCode, intervalSeconds) {
   let interval = Math.max(Number(intervalSeconds || 5), 1);
   while (true) {
     await new Promise((resolve) => setTimeout(resolve, interval * 1000));
-    const response = await fetch("https://github.com/login/oauth/access_token", {
+    const response = await upstreamFetch("https://github.com/login/oauth/access_token", {
       method: "POST",
       headers: { accept: "application/json", "content-type": "application/x-www-form-urlencoded" },
       body: formBody({ client_id: GITHUB_CLIENT_ID, device_code: deviceCode, grant_type: "urn:ietf:params:oauth:grant-type:device_code" })
@@ -75,7 +76,7 @@ function jwtExpirySeconds(token) {
 
 export async function exchangeCopilotToken(githubToken = readGitHubToken()) {
   if (!githubToken) throw new Error("Missing GitHub token. Run: aerial login");
-  const response = await fetch(COPILOT_TOKEN_URL, {
+  const response = await upstreamFetch(COPILOT_TOKEN_URL, {
     headers: {
       authorization: `Bearer ${githubToken}`,
       accept: "application/json",

package/src/cli.js

@@ -12,6 +12,8 @@ import { chooseSetupModel, formatModelChoices } from "./model-selection.js";
 import { chooseSetupEffort, formatEffortSelection, assertValidEffort } from "./setup-selection.js";
 import { printVersion } from "./version.js";
 import { computeAppStatus } from "./app-status.js";
+import { disableUpstreamProxy, enableUpstreamProxy, probeEgress, upstreamProxyState } from "./upstream-fetch.js";
+import { redactProxyEndpoint, redactProxySource } from "./proxy-config.js";
 
 const CLI_ENTRY = fileURLToPath(import.meta.url);
 
@@ -42,6 +44,7 @@ Usage:
   aerial setup claude [--model <id>] [--effort <low|medium|high|xhigh|max>]
   aerial service install
   aerial status [--json]
+  aerial proxy status|enable|disable [--json]
 
 Diagnostics and rollback:
   aerial setup status [--json]
@@ -147,6 +150,180 @@ function printServiceSummary(status) {
   console.log(`health: ${health}`);
 }
 
+function printRestoreResults(results) {
+  for (const r of Object.values(results)) {
+    if (r.restored) {
+      console.log(`Restored ${r.target}: ${r.file} <- ${r.from}`);
+      if (r.snapshot) console.log(`  pre-restore snapshot: ${r.snapshot}`);
+    } else if (r.reason === "no_backup") {
+      console.log(`Restored ${r.target}: no backup to restore`);
+    } else if (r.error) {
+      console.log(`Restored ${r.target}: FAILED  ${r.error}`);
+    }
+  }
+}
+
+function printServiceDiagnostics(diagnostics) {
+  if (!diagnostics) return;
+  if (diagnostics.stdioLog) console.log(`  stdio log: ${diagnostics.stdioLog}`);
+  if (diagnostics.aerialLog) console.log(`  aerial log: ${diagnostics.aerialLog}`);
+  if (diagnostics.wrapperNode) console.log(`  wrapper node: ${diagnostics.wrapperNode}`);
+  if (diagnostics.health) {
+    const h = diagnostics.health;
+    const tail = h.lastError ? `, last error: ${h.lastError}` : (h.lastStatus !== undefined ? `, last status: ${h.lastStatus}` : "");
+    console.log(`  health probe: ${h.attempts} attempts over ${h.elapsedMs}ms${tail}`);
+  }
+  console.log(`  Run: aerial service status --json`);
+}
+
+function printServiceWarning(result) {
+  if (result.warning) console.log(`  WARNING: ${result.warning.message}`);
+}
+
+function formatEgress(egress) {
+  if (!egress?.ok) return `unavailable (${egress?.error || "unknown"})`;
+  const place = [egress.city, egress.region, egress.country].filter(Boolean).join(", ");
+  return [egress.ip, place].filter(Boolean).join("  ");
+}
+
+async function proxyRouteSummary() {
+  try {
+    const report = await runProbe();
+    if (!report.ok) return { ok: false, error: JSON.stringify(report.error) };
+    return {
+      ok: true,
+      models: report.models.length,
+      responses: report.summary.responses,
+      responsesWebSocket: report.summary.websocketResponses,
+      messages: report.summary.messages,
+      chat: report.summary.chat
+    };
+  } catch (err) {
+    return { ok: false, error: err.message };
+  }
+}
+
+async function proxyStatus({ includeRoutes = true } = {}) {
+  const state = upstreamProxyState(loadConfig());
+  const egress = await probeEgress({ endpoint: state.endpoint });
+  return {
+    schema: "aerial.proxy-status.v1",
+    mode: state.mode,
+    enabled: state.enabled,
+    endpoint: state.endpoint,
+    source: state.source,
+    egress,
+    routes: includeRoutes ? await proxyRouteSummary() : undefined
+  };
+}
+
+function publicProxyCandidate(candidate) {
+  if (!candidate || typeof candidate !== "object") return candidate;
+  return {
+    ...candidate,
+    endpoint: redactProxyEndpoint(candidate.endpoint),
+    source: redactProxySource(candidate.source)
+  };
+}
+
+function publicProxyStatus(status) {
+  if (!status || typeof status !== "object") return status;
+  return {
+    ...status,
+    endpoint: redactProxyEndpoint(status.endpoint),
+    source: redactProxySource(status.source)
+  };
+}
+
+function publicProxyEnableResult(result) {
+  if (!result || typeof result !== "object") return result;
+  return {
+    ...result,
+    selected: publicProxyCandidate(result.selected),
+    candidates: Array.isArray(result.candidates) ? result.candidates.map(publicProxyCandidate) : result.candidates,
+    status: publicProxyStatus(result.status)
+  };
+}
+
+function printProxyStatus(status) {
+  const safeStatus = publicProxyStatus(status);
+  console.log(`proxy: ${status.enabled ? `enabled (${status.mode})` : "disabled"}`);
+  console.log(`endpoint: ${status.enabled ? `${safeStatus.endpoint} (${safeStatus.source})` : "direct"}`);
+  console.log(`egress: ${formatEgress(status.egress)}`);
+  if (status.routes) {
+    if (status.routes.ok) {
+      console.log(`copilot routes: responses=${status.routes.responses}, responsesWebSocket=${status.routes.responsesWebSocket}, messages=${status.routes.messages}, chat=${status.routes.chat}`);
+    } else {
+      console.log(`copilot routes: unavailable (${status.routes.error})`);
+    }
+  }
+}
+
+async function runProxyCli(subcommand, rest) {
+  const json = rest.includes("--json") || subcommand === "--json";
+  if (!subcommand || subcommand === "status" || subcommand === "--json") {
+    const status = await proxyStatus();
+    if (json) console.log(JSON.stringify(publicProxyStatus(status), null, 2));
+    else printProxyStatus(status);
+    return;
+  }
+  if (subcommand === "enable") {
+    const result = await enableUpstreamProxy();
+    if (!result.ok) {
+      if (json) console.log(JSON.stringify(publicProxyEnableResult(result), null, 2));
+      else {
+        console.error(`Proxy enable failed: ${result.error}`);
+        if (result.candidates?.length) {
+          console.error(`Checked: ${result.candidates.map((c) => redactProxyEndpoint(c.endpoint)).join(", ")}`);
+        }
+      }
+      process.exitCode = 1;
+      return;
+    }
+    const status = await proxyStatus();
+    if (json) console.log(JSON.stringify(publicProxyEnableResult({ ...result, status }), null, 2));
+    else {
+      console.log(`Proxy enabled: ${redactProxyEndpoint(result.selected.endpoint)} (${redactProxySource(result.selected.source)})`);
+      printProxyStatus(status);
+    }
+    return;
+  }
+  if (subcommand === "disable") {
+    disableUpstreamProxy();
+    const status = await proxyStatus();
+    if (json) console.log(JSON.stringify(publicProxyStatus(status), null, 2));
+    else {
+      console.log("Proxy disabled.");
+      printProxyStatus(status);
+    }
+    return;
+  }
+  throw new Error("Usage: aerial proxy status|enable|disable [--json]");
+}
+
+function printServiceUninstallResult(r, { prefix = "Service uninstall" } = {}) {
+  if (r.note === "no service installed") console.log(`${prefix}: no service installed`);
+  else if (r.ok) console.log(`${prefix}: ok (${r.platform})`);
+  else {
+    console.log(`${prefix}: FAILED (${r.reason || "see stderr"})`);
+    if (r.message) console.log(`  ${r.message}`);
+    else console.log(`  Retry with: aerial service uninstall`);
+  }
+  if (r.delete?.stderr) console.log(`  schtasks stderr: ${r.delete.stderr.trim()}`);
+  if (r.bootout?.stderr) console.log(`  bootout stderr: ${r.bootout.stderr.trim()}`);
+}
+
+async function runServiceCliAction(action, render) {
+  try {
+    const result = await action();
+    render(result);
+    process.exitCode = result.ok ? 0 : 1;
+  } catch (err) {
+    console.error(err.message);
+    process.exitCode = 1;
+  }
+}
+
 async function appStatus({ json = false } = {}) {
   const setup = setupStatus();
   const service = await serviceStatus();
@@ -180,6 +357,11 @@ async function main() {
     return;
   }
 
+  if (command === "proxy") {
+    await runProxyCli(subcommand, rest);
+    return;
+  }
+
   if (command === "login") {
     const loginArgs = args.slice(1);
     const force = loginArgs.includes("--force");
@@ -307,16 +489,7 @@ async function main() {
       if (!rest.includes("--latest")) throw new Error("aerial setup restore: only --latest is supported in this release");
       if (which === "all") {
         const { ok, results } = restoreAllClients();
-        for (const r of Object.values(results)) {
-          if (r.restored) {
-            console.log(`Restored ${r.target}: ${r.file} <- ${r.from}`);
-            if (r.snapshot) console.log(`  pre-restore snapshot: ${r.snapshot}`);
-          } else if (r.reason === "no_backup") {
-            console.log(`Restored ${r.target}: no backup to restore`);
-          } else if (r.error) {
-            console.log(`Restored ${r.target}: FAILED  ${r.error}`);
-          }
-        }
+        printRestoreResults(results);
         process.exitCode = ok ? 0 : 1;
         return;
       }
@@ -334,16 +507,7 @@ async function main() {
 
   if (command === "disable") {
     const { ok: restoreOk, results } = restoreAllClients();
-    for (const r of Object.values(results)) {
-      if (r.restored) {
-        console.log(`Restored ${r.target}: ${r.file} <- ${r.from}`);
-        if (r.snapshot) console.log(`  pre-restore snapshot: ${r.snapshot}`);
-      } else if (r.reason === "no_backup") {
-        console.log(`Restored ${r.target}: no backup to restore`);
-      } else if (r.error) {
-        console.log(`Restored ${r.target}: FAILED  ${r.error}`);
-      }
-    }
+    printRestoreResults(results);
     if (!restoreOk) {
       console.log("service uninstall: skipped because client restore reported failures; resolve restore errors then rerun `aerial disable` or `aerial service uninstall`.");
       process.exitCode = 1;
@@ -351,15 +515,7 @@ async function main() {
     }
     try {
       const r = serviceUninstall();
-      if (r.note === "no service installed") console.log("service uninstall: no service installed");
-      else if (r.ok) console.log(`service uninstall: ok (${r.platform})`);
-      else {
-        console.log(`service uninstall: FAILED (${r.reason || "see stderr"})`);
-        if (r.message) console.log(`  ${r.message}`);
-        else console.log(`  Retry with: aerial service uninstall`);
-      }
-      if (r.bootout?.stderr) console.log(`  bootout stderr: ${r.bootout.stderr.trim()}`);
-      if (r.delete?.stderr) console.log(`  schtasks stderr: ${r.delete.stderr.trim()}`);
+      printServiceUninstallResult(r, { prefix: "service uninstall" });
       process.exitCode = r.ok ? 0 : 1;
     } catch (err) {
       if (/unsupported platform/.test(err.message)) {
@@ -376,8 +532,7 @@ async function main() {
 
   if (command === "service") {
     if (subcommand === "install") {
-      try {
-        const r = await serviceInstall();
+      await runServiceCliAction(serviceInstall, (r) => {
         if (r.ok && r.note) console.log(`Service install: ${r.note} (${r.platform}).`);
         else if (r.ok) console.log(`Service installed (${r.platform}).`);
         else console.log(`Service install: FAILED (${r.reason || "unknown"}): ${r.message || ""}`);
@@ -387,98 +542,44 @@ async function main() {
         if (r.bootstrap?.stderr) console.log(`  bootstrap stderr: ${r.bootstrap.stderr.trim()}`);
         if (r.create?.stderr) console.log(`  schtasks stderr: ${r.create.stderr.trim()}`);
         if (r.run?.stderr) console.log(`  schtasks /Run stderr: ${r.run.stderr.trim()}`);
-        if (r.diagnostics) {
-          if (r.diagnostics.stdioLog) console.log(`  stdio log: ${r.diagnostics.stdioLog}`);
-          if (r.diagnostics.aerialLog) console.log(`  aerial log: ${r.diagnostics.aerialLog}`);
-          if (r.diagnostics.wrapperNode) console.log(`  wrapper node: ${r.diagnostics.wrapperNode}`);
-          if (r.diagnostics.health) {
-            const h = r.diagnostics.health;
-            const tail = h.lastError ? `, last error: ${h.lastError}` : (h.lastStatus !== undefined ? `, last status: ${h.lastStatus}` : "");
-            console.log(`  health probe: ${h.attempts} attempts over ${h.elapsedMs}ms${tail}`);
-          }
-          console.log(`  Run: aerial service status --json`);
-        }
-        if (r.warning) console.log(`  WARNING: ${r.warning.message}`);
-        process.exitCode = r.ok ? 0 : 1;
-      } catch (err) {
-        console.error(err.message);
-        process.exitCode = 1;
-      }
+        printServiceDiagnostics(r.diagnostics);
+        printServiceWarning(r);
+      });
       return;
     }
     if (subcommand === "start") {
-      try {
-        const r = await serviceStart();
+      await runServiceCliAction(serviceStart, (r) => {
         if (r.ok && r.note) console.log(`Service start: ${r.note} (${r.platform})`);
         else if (r.ok) console.log(`Service start: ok (${r.platform})`);
         else console.log(`Service start: FAILED (${r.reason || `status=${r.status}`})${r.message ? ": " + r.message : ""}`);
         if (r.stderr) console.log(`  ${r.stderr.trim()}`);
-        if (r.diagnostics) {
-          if (r.diagnostics.stdioLog) console.log(`  stdio log: ${r.diagnostics.stdioLog}`);
-          if (r.diagnostics.aerialLog) console.log(`  aerial log: ${r.diagnostics.aerialLog}`);
-          if (r.diagnostics.wrapperNode) console.log(`  wrapper node: ${r.diagnostics.wrapperNode}`);
-          if (r.diagnostics.health) {
-            const h = r.diagnostics.health;
-            const tail = h.lastError ? `, last error: ${h.lastError}` : (h.lastStatus !== undefined ? `, last status: ${h.lastStatus}` : "");
-            console.log(`  health probe: ${h.attempts} attempts over ${h.elapsedMs}ms${tail}`);
-          }
-          console.log(`  Run: aerial service status --json`);
-        }
-        if (r.warning) console.log(`  WARNING: ${r.warning.message}`);
-        process.exitCode = r.ok ? 0 : 1;
-      } catch (err) {
-        console.error(err.message);
-        process.exitCode = 1;
-      }
+        printServiceDiagnostics(r.diagnostics);
+        printServiceWarning(r);
+      });
       return;
     }
     if (subcommand === "stop") {
-      try {
-        const r = serviceStop();
+      await runServiceCliAction(serviceStop, (r) => {
         if (r.note) console.log(`Service stop: ${r.note} (${r.platform})`);
         else if (r.ok) console.log(`Service stop: ok (${r.platform})`);
         else console.log(`Service stop: FAILED (status=${r.status})`);
         if (r.stderr) console.log(`  ${r.stderr.trim()}`);
-        process.exitCode = r.ok ? 0 : 1;
-      } catch (err) {
-        console.error(err.message);
-        process.exitCode = 1;
-      }
+      });
       return;
     }
     if (subcommand === "restart") {
-      try {
-        const r = await serviceRestart();
+      await runServiceCliAction(serviceRestart, (r) => {
         if (!r.ok && r.reason === "stop_failed") console.log(`Service restart: FAILED on stop; start not attempted`);
         else if (r.ok) console.log(`Service restart: ok`);
         else console.log(`Service restart: FAILED`);
         if (r.stop?.stderr) console.log(`  stop: ${r.stop.stderr.trim()}`);
         if (r.start?.stderr) console.log(`  start: ${r.start.stderr.trim()}`);
-        if (r.warning) console.log(`  WARNING: ${r.warning.message}`);
-        process.exitCode = r.ok ? 0 : 1;
-      } catch (err) {
-        console.error(err.message);
-        process.exitCode = 1;
-      }
+        printServiceWarning(r);
+      });
       return;
     }
     if (subcommand === "uninstall") {
-      try {
-        const r = serviceUninstall();
-        if (r.note === "no service installed") console.log("Service uninstall: no service installed");
-        else if (r.ok) console.log(`Service uninstall: ok (${r.platform})`);
-        else {
-          console.log(`Service uninstall: FAILED (${r.reason || "see stderr"})`);
-          if (r.message) console.log(`  ${r.message}`);
-          else console.log(`  Retry with: aerial service uninstall`);
-        }
-        if (r.delete?.stderr) console.log(`  schtasks stderr: ${r.delete.stderr.trim()}`);
-        if (r.bootout?.stderr) console.log(`  bootout stderr: ${r.bootout.stderr.trim()}`);
-        process.exitCode = r.ok ? 0 : 1;
-      } catch (err) {
-        console.error(err.message);
-        process.exitCode = 1;
-      }
+      await runServiceCliAction(serviceUninstall, printServiceUninstallResult);
       return;
     }
     if (subcommand === "status") {

package/src/config.js

@@ -3,6 +3,7 @@ import { CONFIG_VERSION, DEFAULT_HOST, DEFAULT_PORT, DEFAULT_VERSIONS } from "./
 import { apiKeyPath, configPath, readJsonIfExists, writeJsonPrivate, writePrivateFile } from "./paths.js";
 import { hashApiKey, randomApiKey, verifyApiKey } from "./crypto.js";
 import { DEFAULT_EFFORT, normalizeEffort } from "./setup-selection.js";
+import { PROXY_MODE_AUTO, normalizeProxyEndpoint, normalizeProxyMode } from "./proxy-config.js";
 
 export function defaultConfig() {
   return {
@@ -15,6 +16,9 @@ export function defaultConfig() {
     logLevel: "info",
     promptCacheRetention: "in_memory",
     promptCacheKey: "auto",
+    upstreamProxyMode: "disabled",
+    upstreamProxyEndpoint: undefined,
+    upstreamProxySource: undefined,
     versions: DEFAULT_VERSIONS
   };
 }
@@ -42,7 +46,24 @@ export function loadConfig() {
   const promptCacheRetention = envRetention === undefined ? (loaded.promptCacheRetention ?? defaults.promptCacheRetention) : envRetention;
   const promptCacheKey = envCacheKey === undefined ? (loaded.promptCacheKey ?? defaults.promptCacheKey) : envCacheKey;
   const defaultEffort = normalizeEffort(loaded.defaultEffort) || DEFAULT_EFFORT;
-  return { ...defaults, ...loaded, defaultEffort, promptCacheRetention, promptCacheKey, versions: { ...DEFAULT_VERSIONS, ...(loaded.versions || {}) } };
+  const loadedProxyMode = normalizeProxyMode(loaded.upstreamProxyMode);
+  const loadedProxyEndpoint = normalizeProxyEndpoint(loaded.upstreamProxyEndpoint);
+  const upstreamProxyEndpoint = loadedProxyMode === PROXY_MODE_AUTO ? loadedProxyEndpoint : undefined;
+  const upstreamProxyMode = upstreamProxyEndpoint ? PROXY_MODE_AUTO : "disabled";
+  const upstreamProxySource = upstreamProxyEndpoint && typeof loaded.upstreamProxySource === "string"
+    ? loaded.upstreamProxySource
+    : undefined;
+  return {
+    ...defaults,
+    ...loaded,
+    defaultEffort,
+    promptCacheRetention,
+    promptCacheKey,
+    upstreamProxyMode,
+    upstreamProxyEndpoint,
+    upstreamProxySource,
+    versions: { ...DEFAULT_VERSIONS, ...(loaded.versions || {}) }
+  };
 }
 
 export function saveConfig(config) {