From 40e6ad38da19df42e92f04773c955ded403f2102 Mon Sep 17 00:00:00 2001
From: saphid <saphid@users.noreply.github.com>
Date: Fri, 30 Oct 2026 14:11:09 +1100
Subject: [PATCH 01/26] feat(server): route Claude, Codex, and OpenCode through
 a CLIProxyAPI proxy

Adds a per-environment proxy connection (Settings -> Providers -> Proxy) and
a Use proxy switch on Claude, Codex, and OpenCode instances. Routing applies at
harness spawn only; Codex pins thread start and resume to the t3_proxy model
provider. A proxy management key feeds Usage -> Limits automatically.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../Adapters/ClaudeAdapterV2.ts               |  8 +-
 .../Adapters/CodexAdapterV2.test.ts           | 76 +++++++++++++++
 .../Adapters/CodexAdapterV2.ts                | 38 +++++++-
 apps/server/src/provider/ClaudeProvider.ts    | 48 ++++++----
 apps/server/src/provider/CodexProvider.ts     | 24 ++++-
 .../src/provider/Drivers/ClaudeDriver.ts      |  9 +-
 .../src/provider/Drivers/ClaudeHome.test.ts   | 23 +++++
 .../server/src/provider/Drivers/ClaudeHome.ts | 25 +++++
 .../src/provider/Drivers/CodexDriver.ts       | 28 +++++-
 .../provider/ProviderInstanceRegistry.test.ts | 33 +++++++
 .../src/provider/ProviderInstanceRegistry.ts  | 51 ++++++++--
 .../ProviderInstanceRegistryHydration.test.ts | 22 +++++
 .../ProviderInstanceRegistryHydration.ts      | 23 ++++-
 .../ProviderInstanceRegistryMutator.ts        | 11 ++-
 .../src/provider/codexLaunchArgs.test.ts      | 43 ++++++++-
 apps/server/src/provider/codexLaunchArgs.ts   | 32 +++++++
 apps/server/src/serverSettings.test.ts        | 13 ++-
 apps/server/src/settingsSecrets.ts            | 10 ++
 .../src/usage/UsageLimitSources.test.ts       | 33 ++++++-
 apps/server/src/usage/UsageLimitSources.ts    | 36 ++++++-
 .../settings/ProviderInstanceCard.tsx         | 65 +++++++++++++
 .../settings/ProviderProxySettings.tsx        | 93 +++++++++++++++++++
 .../settings/ProviderSettingsPanel.tsx        | 12 +++
 .../src/components/settings/settingsSearch.ts |  9 ++
 docs/user/install.md                          | 13 +++
 docs/user/usage.md                            |  5 +-
 packages/contracts/src/providerInstance.ts    |  9 ++
 packages/contracts/src/settings.ts            | 20 +++-
 packages/provider-core/package.json           |  4 +
 packages/provider-core/src/server/driver.ts   |  3 +
 .../provider-core/src/server/providerProxy.ts | 19 ++++
 .../OpenCodeRuntime.environment.test.ts       | 27 ++++++
 .../src/server/OpenCodeRuntime.ts             | 47 ++++++++++
 .../provider-opencode/src/server/adapter.ts   |  5 +-
 .../provider-opencode/src/server/driver.ts    | 15 ++-
 35 files changed, 871 insertions(+), 61 deletions(-)
 create mode 100644 apps/web/src/components/settings/ProviderProxySettings.tsx
 create mode 100644 packages/provider-core/src/server/providerProxy.ts

diff --git a/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts b/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts
index 496a0b2e77d0f..ecb1e2baeac9a 100644
--- a/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts
+++ b/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts
@@ -150,6 +150,7 @@ import { expandHomePath } from "@t3tools/provider-core/server/pathExpansion";
 import { spawnAndCollect } from "@t3tools/provider-core/server/snapshotProbe";
 import { signalProcessGroup } from "@t3tools/provider-core/server/processGroup";
 import {
+  applyClaudeProxyEnvironment,
   claudeSignedOutMessage,
   makeClaudeEnvironment,
   resolveClaudeHomePath,
@@ -11206,14 +11207,17 @@ export const createClaudeAdapterV2 = Effect.fn("ClaudeAdapterV2Driver.create")(
     input: ProviderAdapterDriverCreateInput<ClaudeSettings>,
     hooks: Pick<ClaudeAdapterV2Options, "scopedLimitNames" | "onUsageLimits"> = {},
   ) {
-    const { instanceId, environment, enabled, config } = input;
+    const { instanceId, environment, enabled, config, proxy } = input;
     const fileSystem = yield* FileSystem.FileSystem;
     const hostEnvironment = yield* HostProcess.Environment;
     const idAllocator = yield* IdAllocator.IdAllocatorV2;
     const queryRunner = yield* ClaudeAgentSdkQueryRunner;
     const serverConfig = yield* ServerConfig.ServerConfig;
     const continuationRequests = yield* ProviderContinuationRequests.ProviderContinuationRequests;
-    const baseEnvironment = yield* mergeProviderInstanceEnvironment(environment, hostEnvironment);
+    const baseEnvironment = applyClaudeProxyEnvironment(
+      yield* mergeProviderInstanceEnvironment(environment, hostEnvironment),
+      proxy,
+    );
     const claudeEnvironment = yield* makeClaudeEnvironment(config, baseEnvironment);
     const path = yield* Path.Path;
     const crypto = yield* Crypto.Crypto;
diff --git a/apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.test.ts b/apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.test.ts
index c20994423f3e9..bda360e227d1b 100644
--- a/apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.test.ts
+++ b/apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.test.ts
@@ -66,6 +66,7 @@ import * as Orchestrator from "../Orchestrator.ts";
 import * as ProviderReplayHarness from "../testkit/ProviderReplayHarness.ts";
 import * as ProviderAdapter from "@t3tools/provider-core/server/ProviderAdapter";
 import type * as ProviderContinuationRequests from "@t3tools/provider-core/server/ProviderContinuationRequests";
+import * as CodexLaunchArgs from "../../provider/codexLaunchArgs.ts";
 import * as CodexAdapterV2 from "./CodexAdapterV2.ts";
 import { withCodexReplayChildMetadata } from "./CodexAdapterV2.testkit.ts";
 import * as CodexAdapterV2Testkit from "./CodexAdapterV2.testkit.ts";
@@ -1086,6 +1087,7 @@ describe("CodexAdapterV2 post-settle continuation", () => {
       Effect.void,
     onRequest: (method: string, params: unknown) => Effect.Effect<void> = () => Effect.void,
     readChildMetadata?: Parameters<typeof withCodexReplayChildMetadata>[2],
+    modelProvider?: string,
   ) =>
     Effect.gen(function* () {
       const fileSystem = yield* FileSystem.FileSystem;
@@ -1131,6 +1133,7 @@ describe("CodexAdapterV2 post-settle continuation", () => {
         instanceId: CodexAdapterV2.CODEX_DEFAULT_INSTANCE_ID,
         settings: DEFAULT_CODEX_SETTINGS,
         environment: {},
+        modelProvider,
         clientFactory,
         crypto: yield* Crypto.Crypto,
         fileSystem,
@@ -2259,6 +2262,79 @@ describe("CodexAdapterV2 post-settle continuation", () => {
     ),
   );
 
+  it.effect("pins thread start and resume to the proxy provider when no model is resent", () =>
+    Effect.scoped(
+      Effect.gen(function* () {
+        const nativeThreadId = "proxied-thread";
+        const modelProvider = CodexLaunchArgs.CODEX_PROXY_MODEL_PROVIDER;
+        const preamble = codexReplayPreamble({
+          nativeThreadId,
+          nativeTurnId: "unused-turn",
+          prompt: "unused-prompt",
+        })
+          .slice(0, 5)
+          .map((entry) =>
+            entry.type === "expect_outbound" && entry.label === "thread/start"
+              ? {
+                  ...entry,
+                  frame: {
+                    id: 2,
+                    method: "thread/start",
+                    params: { modelProvider, config: CodexAdapterV2.CODEX_THREAD_CONFIG },
+                  },
+                }
+              : entry,
+          );
+        const harness = yield* makeCodexReplayHarness(
+          makeCodexReplayTranscript({
+            scenario: "proxy-resume",
+            entries: [
+              ...preamble,
+              {
+                type: "expect_outbound",
+                label: "resume through the proxy",
+                frame: {
+                  id: 3,
+                  method: "thread/resume",
+                  params: {
+                    threadId: nativeThreadId,
+                    excludeTurns: true,
+                    modelProvider,
+                    config: CodexAdapterV2.CODEX_THREAD_CONFIG,
+                  },
+                },
+              },
+              {
+                type: "emit_inbound",
+                label: "resume result",
+                frame: {
+                  id: 3,
+                  result: {
+                    thread: { id: nativeThreadId, updatedAt: 1782622450, turns: [] },
+                  },
+                },
+              },
+            ],
+          }),
+          undefined,
+          undefined,
+          undefined,
+          modelProvider,
+        );
+
+        const resumed = yield* harness.runtime.resumeThread({
+          providerThread: harness.providerThread,
+        });
+
+        assert.equal(resumed.nativeThreadRef?.nativeId, nativeThreadId);
+      }).pipe(
+        Effect.provide(
+          Layer.mergeAll(IdAllocator.layer, McpProviderSessions.layer, NodeServices.layer),
+        ),
+      ),
+    ),
+  );
+
   // regression: #15389 archived native Codex sessions resume via thread/unarchive
   it.effect.each(
     (
diff --git a/apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.ts b/apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.ts
index 51a686e270389..6adcecd8bd70f 100644
--- a/apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.ts
+++ b/apps/server/src/orchestration-v2/Adapters/CodexAdapterV2.ts
@@ -116,7 +116,12 @@ import {
   shouldPersistProviderEvent,
 } from "../../provider/EventNdjsonLogger.ts";
 import * as ProviderEventLoggers from "@t3tools/provider-core/server/ProviderEventLoggers";
-import { codexAppServerArgs, resolveCodexLaunchArgs } from "../../provider/codexLaunchArgs.ts";
+import {
+  applyCodexProxyRuntime,
+  CODEX_PROXY_MODEL_PROVIDER,
+  codexAppServerArgs,
+  resolveCodexLaunchArgs,
+} from "../../provider/codexLaunchArgs.ts";
 import { mergeProviderInstanceEnvironment } from "@t3tools/provider-core/server/instanceEnvironment";
 import * as McpProviderSession from "@t3tools/provider-core/server/mcpSession";
 import * as McpProviderSessions from "@t3tools/provider-core/server/McpProviderSessions";
@@ -1322,15 +1327,19 @@ function codexThreadRuntimeParams(input: {
   readonly mcpSession: McpProviderSession.McpProviderSessionConfig | undefined;
   readonly modelSelection?: { readonly model: string };
   readonly runtimePolicy?: ProviderAdapter.ProviderAdapterV2RuntimePolicy;
+  readonly modelProvider?: string | undefined;
 }): {
   readonly cwd?: string;
   readonly model?: string;
+  readonly modelProvider?: string;
   readonly config: Readonly<Record<string, Schema.Json>>;
 } {
   const { mcpSession } = input;
   return {
     ...(input.runtimePolicy?.cwd == null ? {} : { cwd: input.runtimePolicy.cwd }),
     ...(input.modelSelection === undefined ? {} : { model: input.modelSelection.model }),
+    // Without it, a resume reuses the provider stored in the rollout and bypasses the proxy.
+    ...(input.modelProvider === undefined ? {} : { modelProvider: input.modelProvider }),
     config: {
       ...CODEX_THREAD_CONFIG,
       ...(mcpSession === undefined
@@ -1547,7 +1556,13 @@ export type CodexAdapterV2DriverEnv =
   | ServerConfig;
 
 export const createCodexAdapterV2 = Effect.fn("CodexAdapterV2.createCodexAdapterV2")(function* (
-  { instanceId, environment, enabled, config }: ProviderAdapterDriverCreateInput<CodexSettings>,
+  {
+    instanceId,
+    environment,
+    enabled,
+    config,
+    proxy,
+  }: ProviderAdapterDriverCreateInput<CodexSettings>,
   hooks: Pick<CodexAdapterV2Options, "onUsageLimits" | "resolveRuntime"> = {},
 ) {
   const clientFactory = yield* CodexAppServerClientFactory;
@@ -1571,8 +1586,13 @@ export const createCodexAdapterV2 = Effect.fn("CodexAdapterV2.createCodexAdapter
     ),
   );
 
+  const routed = applyCodexProxyRuntime(
+    config,
+    yield* mergeProviderInstanceEnvironment(environment, hostEnvironment),
+    proxy,
+  );
   const settings = {
-    ...config,
+    ...routed.config,
     enabled,
     binaryPath: expandHomePath(config.binaryPath, yield* HostProcess.HomeDirectory),
     homePath: homeLayout.effectiveHomePath ?? "",
@@ -1581,7 +1601,8 @@ export const createCodexAdapterV2 = Effect.fn("CodexAdapterV2.createCodexAdapter
   return yield* makeCodexAdapterV2({
     instanceId,
     settings,
-    environment: yield* mergeProviderInstanceEnvironment(environment, hostEnvironment),
+    environment: routed.environment,
+    ...(proxy === undefined ? {} : { modelProvider: CODEX_PROXY_MODEL_PROVIDER }),
     clientFactory,
     crypto,
     fileSystem,
@@ -1598,6 +1619,8 @@ export interface CodexAdapterV2Options {
   readonly environment: NodeJS.ProcessEnv;
   readonly clientFactory: CodexAppServerClientFactoryShape;
   readonly onUsageLimits?: ManagedServerProvider["applyUsageLimits"];
+  /** Pins thread start and resume to this Codex model provider. */
+  readonly modelProvider?: string | undefined;
   readonly resolveRuntime?: Effect.Effect<CodexEffectiveRuntime, ProviderSetupError, Scope.Scope>;
   readonly crypto: Crypto.Crypto;
   readonly fileSystem: FileSystem.FileSystem;
@@ -2964,6 +2987,9 @@ export const makeCodexAdapterV2 = Effect.fn("makeCodexAdapterV2")(function* (
                         .request("thread/resume", {
                           threadId: input.nativeThreadId,
                           excludeTurns: true,
+                          ...(adapterOptions.modelProvider === undefined
+                            ? {}
+                            : { modelProvider: adapterOptions.modelProvider }),
                         })
                         .pipe(Effect.flatMap(decodeCodexChildModel)),
                   ),
@@ -6784,6 +6810,7 @@ export const makeCodexAdapterV2 = Effect.fn("makeCodexAdapterV2")(function* (
                 client.request(
                   "thread/start",
                   codexThreadRuntimeParams({
+                    modelProvider: adapterOptions.modelProvider,
                     mcpSession,
                     modelSelection: threadInput.modelSelection,
                     runtimePolicy: threadInput.runtimePolicy,
@@ -6816,6 +6843,7 @@ export const makeCodexAdapterV2 = Effect.fn("makeCodexAdapterV2")(function* (
                 threadId: nativeThreadId,
                 excludeTurns: true,
                 ...codexThreadRuntimeParams({
+                  modelProvider: adapterOptions.modelProvider,
                   mcpSession: yield* readMcpSession(
                     threadInput.threadId ?? threadInput.providerThread.appThreadId,
                   ),
@@ -7602,6 +7630,7 @@ export const makeCodexAdapterV2 = Effect.fn("makeCodexAdapterV2")(function* (
                   threadId,
                   excludeTurns: true,
                   ...codexThreadRuntimeParams({
+                    modelProvider: adapterOptions.modelProvider,
                     mcpSession: yield* readMcpSession(threadInput.providerThread.appThreadId),
                     modelSelection: input.modelSelection,
                     runtimePolicy: input.runtimePolicy,
@@ -7654,6 +7683,7 @@ export const makeCodexAdapterV2 = Effect.fn("makeCodexAdapterV2")(function* (
                       ? {}
                       : { lastTurnId: boundary.lastTurnId }),
                     ...codexThreadRuntimeParams({
+                      modelProvider: adapterOptions.modelProvider,
                       mcpSession: yield* mcpSessions.read(threadInput.targetThreadId),
                       ...(threadInput.modelSelection === undefined
                         ? {}
diff --git a/apps/server/src/provider/ClaudeProvider.ts b/apps/server/src/provider/ClaudeProvider.ts
index 5bc82a41d4eda..9ead818e886af 100644
--- a/apps/server/src/provider/ClaudeProvider.ts
+++ b/apps/server/src/provider/ClaudeProvider.ts
@@ -40,6 +40,10 @@ import { hasClaudeManagedMcpConfig, makeClaudeEnvironment } from "./Drivers/Clau
 import { discoverClaudeSkills } from "./Drivers/ClaudeSkills.ts";
 import type { ProviderWorkspaceSnapshot } from "@t3tools/provider-core/server/driver";
 import { makeUnavailableUsageLimits } from "@t3tools/provider-core/server/usageLimits";
+import {
+  PROXY_AUTH_METADATA,
+  PROXY_LIMITS_MESSAGE,
+} from "@t3tools/provider-core/server/providerProxy";
 import {
   type ClaudeScopedLimitNames,
   claudeUsageResponseToLimits,
@@ -461,6 +465,7 @@ export const checkClaudeProviderStatus = Effect.fn("checkClaudeProviderStatus")(
   /** Shared with the adapter so turn events reuse the scoped-bucket names this probe saw. */
   scopedLimitNames?: Ref.Ref<ClaudeScopedLimitNames>,
   resolveResetCredits?: (version: string) => Effect.Effect<ServerProviderResetCredits | undefined>,
+  routedThroughProxy = false,
 ): Effect.fn.Return<
   ServerProviderDraft,
   never,
@@ -626,25 +631,32 @@ export const checkClaudeProviderStatus = Effect.fn("checkClaudeProviderStatus")(
     });
   }
 
-  const authMetadata =
-    claudeAuthMetadata({
-      subscriptionType: capabilities.subscriptionType,
-      authMethod: capabilities.tokenSource,
-    }) ??
-    apiProviderAuthMetadata(capabilities.apiProvider) ??
-    (customApiEndpoint ? { type: "customEndpoint", label: "Custom API endpoint" } : undefined);
+  const authMetadata = routedThroughProxy
+    ? PROXY_AUTH_METADATA
+    : (claudeAuthMetadata({
+        subscriptionType: capabilities.subscriptionType,
+        authMethod: capabilities.tokenSource,
+      }) ??
+      apiProviderAuthMetadata(capabilities.apiProvider) ??
+      (customApiEndpoint ? { type: "customEndpoint", label: "Custom API endpoint" } : undefined));
   const usageCheckedAt = capabilities.usageCheckedAt ?? checkedAt;
-  const usageLimits = !capabilities.usage
-    ? makeUnavailableUsageLimits({ checkedAt, reason: "probeFailed" })
-    : scopedLimitNames
-      ? yield* recordClaudeUsageResponse(scopedLimitNames, {
-          response: capabilities.usage,
-          checkedAt: usageCheckedAt,
-        })
-      : claudeUsageResponseToLimits({
-          response: capabilities.usage,
-          checkedAt: usageCheckedAt,
-        }).limits;
+  const usageLimits = routedThroughProxy
+    ? makeUnavailableUsageLimits({
+        checkedAt,
+        reason: "unsupported",
+        message: PROXY_LIMITS_MESSAGE,
+      })
+    : !capabilities.usage
+      ? makeUnavailableUsageLimits({ checkedAt, reason: "probeFailed" })
+      : scopedLimitNames
+        ? yield* recordClaudeUsageResponse(scopedLimitNames, {
+            response: capabilities.usage,
+            checkedAt: usageCheckedAt,
+          })
+        : claudeUsageResponseToLimits({
+            response: capabilities.usage,
+            checkedAt: usageCheckedAt,
+          }).limits;
   const resetCredits =
     resolveResetCredits &&
     capabilities.subscriptionType &&
diff --git a/apps/server/src/provider/CodexProvider.ts b/apps/server/src/provider/CodexProvider.ts
index 2b2d5501881b4..7d69d7cd64489 100644
--- a/apps/server/src/provider/CodexProvider.ts
+++ b/apps/server/src/provider/CodexProvider.ts
@@ -44,6 +44,10 @@ import {
 } from "@t3tools/provider-core/server/snapshotProbe";
 import { expandHomePath } from "@t3tools/provider-core/server/pathExpansion";
 import { makeUnavailableUsageLimits } from "@t3tools/provider-core/server/usageLimits";
+import {
+  PROXY_AUTH_METADATA,
+  PROXY_LIMITS_MESSAGE,
+} from "@t3tools/provider-core/server/providerProxy";
 import {
   codexRateLimitsFailureMessage,
   codexRateLimitsToLimits,
@@ -696,6 +700,7 @@ export const checkCodexProviderStatus = Effect.fn("checkCodexProviderStatus")(fu
   > = probeCodexAppServerProvider,
   environment?: NodeJS.ProcessEnv,
   managedAuth?: ServerProvider["auth"],
+  routedThroughProxy = false,
 ): Effect.fn.Return<
   ServerProviderDraft,
   ServerSettingsError,
@@ -728,7 +733,7 @@ export const checkCodexProviderStatus = Effect.fn("checkCodexProviderStatus")(fu
     launchArgs: resolveCodexLaunchArgs(codexSettings.launchArgs, resolvedEnvironment),
     cwd: process.cwd(),
     environment: resolvedEnvironment,
-    ...(managedAuth ? { skipNativeUsage: true } : {}),
+    ...(managedAuth || routedThroughProxy ? { skipNativeUsage: true } : {}),
   }).pipe(
     // Process teardown can outlast the work budget without discarding a completed snapshot.
     Effect.timeoutOption(Duration.millis(CODEX_AUTH_PROBE_TIMEOUT_MS)),
@@ -780,9 +785,20 @@ export const checkCodexProviderStatus = Effect.fn("checkCodexProviderStatus")(fu
   const snapshot = probeResult.success.value;
   const accountStatus = managedAuth
     ? { status: "ready" as const, auth: managedAuth, message: undefined }
-    : accountProbeStatus(snapshot);
-  const usageLimits =
-    snapshot.account.account?.type === "apiKey"
+    : routedThroughProxy
+      ? {
+          status: "ready" as const,
+          auth: { status: "authenticated" as const, ...PROXY_AUTH_METADATA },
+          message: undefined,
+        }
+      : accountProbeStatus(snapshot);
+  const usageLimits = routedThroughProxy
+    ? makeUnavailableUsageLimits({
+        checkedAt,
+        reason: "unsupported",
+        message: PROXY_LIMITS_MESSAGE,
+      })
+    : snapshot.account.account?.type === "apiKey"
       ? makeUnavailableUsageLimits({ checkedAt, reason: "unsupported" })
       : snapshot.rateLimits === undefined || "failure" in snapshot.rateLimits
         ? makeUnavailableUsageLimits({
diff --git a/apps/server/src/provider/Drivers/ClaudeDriver.ts b/apps/server/src/provider/Drivers/ClaudeDriver.ts
index e1fbcd30080fd..53d56756b2be1 100644
--- a/apps/server/src/provider/Drivers/ClaudeDriver.ts
+++ b/apps/server/src/provider/Drivers/ClaudeDriver.ts
@@ -56,6 +56,7 @@ import {
   type ProviderSnapshotSettings,
 } from "@t3tools/provider-core/server/snapshotSettings";
 import {
+  applyClaudeProxyEnvironment,
   makeClaudeCapabilitiesCacheKey,
   makeClaudeContinuationGroupKey,
   resolveClaudeHomePath,
@@ -120,6 +121,7 @@ export const ClaudeDriver: ProviderDriver<ClaudeSettings, ClaudeDriverEnv, Path.
     environment,
     enabled,
     config,
+    proxy,
   }) {
     const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
     const fileSystem = yield* FileSystem.FileSystem;
@@ -134,7 +136,10 @@ export const ClaudeDriver: ProviderDriver<ClaudeSettings, ClaudeDriverEnv, Path.
     const modelCatalog = catalogService
       .current(DRIVER_KIND)
       .pipe(Effect.map(resolveClaudeModelCatalog));
-    const processEnv = yield* mergeProviderInstanceEnvironment(environment);
+    const processEnv = applyClaudeProxyEnvironment(
+      yield* mergeProviderInstanceEnvironment(environment),
+      proxy,
+    );
     const fallbackContinuationIdentity = defaultProviderContinuationIdentity({
       driverKind: DRIVER_KIND,
       instanceId,
@@ -178,6 +183,7 @@ export const ClaudeDriver: ProviderDriver<ClaudeSettings, ClaudeDriverEnv, Path.
         environment,
         enabled,
         config,
+        proxy,
       },
       { scopedLimitNames, onUsageLimits: (update) => snapshot.applyUsageLimits(update) },
     ).pipe(
@@ -272,6 +278,7 @@ export const ClaudeDriver: ProviderDriver<ClaudeSettings, ClaudeDriverEnv, Path.
                   Effect.provideService(FileSystem.FileSystem, fileSystem),
                   Effect.provideService(Path.Path, path),
                 ),
+              proxy !== undefined,
             ),
           ),
           Effect.tap((provider) =>
diff --git a/apps/server/src/provider/Drivers/ClaudeHome.test.ts b/apps/server/src/provider/Drivers/ClaudeHome.test.ts
index b9eb3b806ce0a..b9c2e96e081e2 100644
--- a/apps/server/src/provider/Drivers/ClaudeHome.test.ts
+++ b/apps/server/src/provider/Drivers/ClaudeHome.test.ts
@@ -6,12 +6,35 @@ import * as Effect from "effect/Effect";
 import * as Path from "effect/Path";
 
 import {
+  applyClaudeProxyEnvironment,
   makeClaudeCapabilitiesCacheKey,
   makeClaudeContinuationGroupKey,
   makeClaudeEnvironment,
   resolveClaudeHomePath,
 } from "./ClaudeHome.ts";
 
+describe("applyClaudeProxyEnvironment", () => {
+  it("replaces every ambient route with the proxy", () => {
+    expect(
+      applyClaudeProxyEnvironment(
+        {
+          PATH: "/bin",
+          ANTHROPIC_API_KEY: "sk-ant-direct",
+          ANTHROPIC_BASE_URL: "https://api.anthropic.com",
+          CLAUDE_CODE_OAUTH_TOKEN: "oauth",
+          CLAUDE_CODE_USE_BEDROCK: "1",
+        },
+        { url: "http://proxy:8317", apiKey: "sk-proxy" },
+      ),
+    ).toEqual({
+      PATH: "/bin",
+      ANTHROPIC_API_KEY: "",
+      ANTHROPIC_BASE_URL: "http://proxy:8317",
+      ANTHROPIC_AUTH_TOKEN: "sk-proxy",
+    });
+  });
+});
+
 it.layer(NodeServices.layer)("ClaudeHome", (it) => {
   describe("Claude home resolution", () => {
     it.effect("resolves configured Claude HOME and stamps continuation/cache keys with it", () =>
diff --git a/apps/server/src/provider/Drivers/ClaudeHome.ts b/apps/server/src/provider/Drivers/ClaudeHome.ts
index bd81aa10bce7a..1c083f5e7174a 100644
--- a/apps/server/src/provider/Drivers/ClaudeHome.ts
+++ b/apps/server/src/provider/Drivers/ClaudeHome.ts
@@ -5,6 +5,7 @@ import * as Path from "effect/Path";
 import * as Schema from "effect/Schema";
 
 import { expandHomePath } from "@t3tools/provider-core/server/pathExpansion";
+import type { ProviderProxyRoute } from "@t3tools/provider-core/server/providerProxy";
 import * as HostProcess from "@t3tools/shared/HostProcess";
 
 const quotePath = Schema.encodeSync(Schema.fromJsonString(Schema.String));
@@ -42,6 +43,30 @@ export const makeClaudeEnvironment = Effect.fn("makeClaudeEnvironment")(function
   };
 });
 
+// Ambient Bedrock, Vertex, or API-key settings would send requests around the proxy.
+const CLAUDE_ROUTE_OVERRIDE_VARIABLES = [
+  "CLAUDE_CODE_OAUTH_TOKEN",
+  "CLAUDE_CODE_USE_BEDROCK",
+  "CLAUDE_CODE_USE_VERTEX",
+  "CLAUDE_CODE_USE_FOUNDRY",
+] as const;
+
+export const applyClaudeProxyEnvironment = (
+  environment: NodeJS.ProcessEnv,
+  proxy: ProviderProxyRoute | undefined,
+): NodeJS.ProcessEnv => {
+  if (proxy === undefined) return environment;
+  const next: NodeJS.ProcessEnv = {
+    ...environment,
+    ANTHROPIC_BASE_URL: proxy.url,
+    ANTHROPIC_AUTH_TOKEN: proxy.apiKey,
+    // Empty, not removed: Claude Code otherwise falls back to a saved API key.
+    ANTHROPIC_API_KEY: "",
+  };
+  for (const name of CLAUDE_ROUTE_OVERRIDE_VARIABLES) delete next[name];
+  return next;
+};
+
 /** managed-mcp.json excludes other MCP config and forbids --strict-mcp-config; omit the flag when present. */
 export const hasClaudeManagedMcpConfig = Effect.fn("hasClaudeManagedMcpConfig")(function* () {
   const fileSystem = yield* FileSystem.FileSystem;
diff --git a/apps/server/src/provider/Drivers/CodexDriver.ts b/apps/server/src/provider/Drivers/CodexDriver.ts
index bbd910cf5d4a9..273306bcaa96c 100644
--- a/apps/server/src/provider/Drivers/CodexDriver.ts
+++ b/apps/server/src/provider/Drivers/CodexDriver.ts
@@ -26,7 +26,7 @@ import {
   probeCodexSkillsForCwd,
   withCodexAppServerClient,
 } from "../CodexProvider.ts";
-import { resolveCodexLaunchArgs } from "../codexLaunchArgs.ts";
+import { applyCodexProxyRuntime, resolveCodexLaunchArgs } from "../codexLaunchArgs.ts";
 import { makeManagedServerProvider } from "@t3tools/provider-core/server/managedProvider";
 import * as ModelCatalog from "@t3tools/provider-core/server/ModelCatalog";
 import { applyCodexModelCatalog } from "../codexModelCatalog.ts";
@@ -131,7 +131,15 @@ export const CodexDriver: ProviderDriver<
     environment,
     enabled,
     config,
+    proxy,
   }) {
+    if (config.setupMode === "managed" && proxy !== undefined) {
+      return yield* new ProviderDriverError({
+        driver: DRIVER_KIND,
+        instanceId,
+        detail: "T3-managed ChatGPT sign-in cannot route through a proxy. Turn off Use proxy.",
+      });
+    }
     if (config.setupMode === "managed")
       return yield* makeManagedCodexProvider({
         instanceId,
@@ -149,7 +157,12 @@ export const CodexDriver: ProviderDriver<
     const latestVersions = yield* ProviderLatestVersions.ProviderLatestVersions;
     const modelCatalog = yield* ModelCatalog.ModelCatalog;
     const currentCatalog = modelCatalog.current(DRIVER_KIND);
-    const processEnv = yield* mergeProviderInstanceEnvironment(environment);
+    const routed = applyCodexProxyRuntime(
+      config,
+      yield* mergeProviderInstanceEnvironment(environment),
+      proxy,
+    );
+    const processEnv = routed.environment;
     const homeLayout = yield* resolveCodexHomeLayout(config);
     const continuationIdentity = codexContinuationIdentity(homeLayout);
     const stampIdentity = withInstanceIdentity({
@@ -171,7 +184,7 @@ export const CodexDriver: ProviderDriver<
       ),
     );
     const effectiveConfig = {
-      ...config,
+      ...routed.config,
       enabled,
       binaryPath: expandHomePath(config.binaryPath, yield* HostProcess.HomeDirectory),
       homePath: homeLayout.effectiveHomePath ?? "",
@@ -198,6 +211,7 @@ export const CodexDriver: ProviderDriver<
         environment,
         enabled,
         config,
+        proxy,
       },
       { onUsageLimits: (update) => snapshot.applyUsageLimits(update) },
     ).pipe(
@@ -217,7 +231,13 @@ export const CodexDriver: ProviderDriver<
     const checkProvider = modelCatalog.refreshInBackground.pipe(
       Effect.andThen(
         Effect.zipWith(
-          checkCodexProviderStatus(effectiveConfig, undefined, processEnv),
+          checkCodexProviderStatus(
+            effectiveConfig,
+            undefined,
+            processEnv,
+            undefined,
+            proxy !== undefined,
+          ),
           currentCatalog,
           (draft, catalog) => stampIdentity(applyCodexModelCatalog(draft, catalog)),
           { concurrent: true },
diff --git a/apps/server/src/provider/ProviderInstanceRegistry.test.ts b/apps/server/src/provider/ProviderInstanceRegistry.test.ts
index de8fc1deae452..5d5e16a34ae4f 100644
--- a/apps/server/src/provider/ProviderInstanceRegistry.test.ts
+++ b/apps/server/src/provider/ProviderInstanceRegistry.test.ts
@@ -642,4 +642,37 @@ describe("ProviderInstanceRegistry — multi-instance codex slice", () => {
         expect(ghost.unavailableReason).toMatch(/ghostDriver/);
       }).pipe(Effect.provide(layerTest)),
   );
+
+  it.live(
+    "rebuilds a proxied instance when the proxy changes and refuses one without a proxy",
+    () =>
+      Effect.gen(function* () {
+        const codexId = ProviderInstanceId.make("codex_proxied");
+        const entry = {
+          driver: ProviderDriverKind.make("codex"),
+          useProxy: true,
+          config: makeCodexConfig({ enabled: false }),
+        };
+        const { registry, mutator } = yield* makeProviderInstanceRegistry<CodexDriverEnv>({
+          drivers: [CodexDriver],
+          configMap: { [codexId]: { ...entry, proxy: { url: "http://a:8317", apiKey: "k" } } },
+        });
+        const first = yield* registry.getInstance(codexId);
+        expect(first).toBeDefined();
+
+        yield* mutator.reconcile({
+          [codexId]: { ...entry, proxy: { url: "http://b:8317", apiKey: "k" } },
+        });
+        const second = yield* registry.getInstance(codexId);
+        expect(second).toBeDefined();
+        expect(second).not.toBe(first);
+
+        // Running on the instance's own login instead would spend a different account.
+        yield* mutator.reconcile({ [codexId]: entry });
+        expect(yield* registry.getInstance(codexId)).toBeUndefined();
+        const [unavailable] = yield* registry.listUnavailable;
+        expect(unavailable?.instanceId).toBe(codexId);
+        expect(unavailable?.unavailableReason).toMatch(/no proxy/);
+      }).pipe(Effect.provide(layerTest)),
+  );
 });
diff --git a/apps/server/src/provider/ProviderInstanceRegistry.ts b/apps/server/src/provider/ProviderInstanceRegistry.ts
index 3bbbe2900b9f2..56edd59107418 100644
--- a/apps/server/src/provider/ProviderInstanceRegistry.ts
+++ b/apps/server/src/provider/ProviderInstanceRegistry.ts
@@ -1,8 +1,8 @@
 import {
+  PROXY_ROUTED_DRIVERS,
   providerInstanceConfigEnabledFlag,
   ProviderInstanceId,
   type ProviderInstanceConfig,
-  type ProviderInstanceConfigMap,
   type ProviderDriverKind,
   type ServerProvider,
 } from "@t3tools/contracts";
@@ -38,7 +38,7 @@ export class ProviderInstanceRegistry extends Context.Service<
 interface LiveEntry {
   readonly instance: ProviderInstance;
   readonly scope: Scope.Closeable;
-  readonly entry: ProviderInstanceConfig;
+  readonly entry: ProviderInstanceRegistryMutator.ProviderInstanceRuntimeEntry;
 }
 
 interface RegistryState {
@@ -47,8 +47,24 @@ interface RegistryState {
   readonly changes: PubSub.PubSub<void>;
 }
 
-const entryEqual = (a: ProviderInstanceConfig, b: ProviderInstanceConfig): boolean =>
-  Equal.equals(a, b);
+const entryEqual = (
+  a: ProviderInstanceRegistryMutator.ProviderInstanceRuntimeEntry,
+  b: ProviderInstanceRegistryMutator.ProviderInstanceRuntimeEntry,
+): boolean => Equal.equals(a, b);
+
+const proxyUnavailableReason = (
+  entry: ProviderInstanceRegistryMutator.ProviderInstanceRuntimeEntry,
+): string | undefined => {
+  if (entry.useProxy !== true) return undefined;
+  if (!PROXY_ROUTED_DRIVERS.has(entry.driver)) {
+    return `Driver '${entry.driver}' cannot route through a proxy. Turn off Use proxy for this instance.`;
+  }
+  // Falling back to the instance's own login would silently spend a different account.
+  if (entry.proxy === undefined) {
+    return "Use proxy is on, but this environment has no proxy. Add one in Settings → Providers → Proxy, or turn off Use proxy.";
+  }
+  return undefined;
+};
 
 /** Conflicting saved flags must preserve any explicit disable. */
 const resolveEntryEnabled = (entry: ProviderInstanceConfig, typedConfig: unknown): boolean => {
@@ -64,7 +80,7 @@ const buildEntry = Effect.fn("ProviderInstanceRegistry.buildEntry")(function* <R
   readonly parentScope: Scope.Scope;
   readonly instanceId: ProviderInstanceId;
   readonly rawInstanceId: string;
-  readonly entry: ProviderInstanceConfig;
+  readonly entry: ProviderInstanceRegistryMutator.ProviderInstanceRuntimeEntry;
 }): Effect.fn.Return<
   | { readonly kind: "live"; readonly live: LiveEntry }
   | { readonly kind: "unavailable"; readonly snapshot: ServerProvider },
@@ -86,6 +102,20 @@ const buildEntry = Effect.fn("ProviderInstanceRegistry.buildEntry")(function* <R
     };
   }
 
+  const proxyReason = proxyUnavailableReason(entry);
+  if (proxyReason !== undefined) {
+    return {
+      kind: "unavailable" as const,
+      snapshot: yield* buildUnavailableProviderSnapshot({
+        driverKind: entry.driver,
+        instanceId,
+        displayName: entry.displayName,
+        accentColor: entry.accentColor,
+        reason: proxyReason,
+      }),
+    };
+  }
+
   const decoder = Schema.decodeUnknownEffect(driver.configSchema);
   const decodeResult = yield* decoder(entry.config ?? driver.defaultConfig()).pipe(Effect.result);
   if (decodeResult._tag === "Failure") {
@@ -120,6 +150,7 @@ const buildEntry = Effect.fn("ProviderInstanceRegistry.buildEntry")(function* <R
       environment: entry.environment ?? [],
       enabled: resolveEntryEnabled(entry, typedConfig),
       config: typedConfig,
+      proxy: entry.useProxy === true ? entry.proxy : undefined,
     })
     .pipe(Effect.provideService(Scope.Scope, childScope), Effect.result);
   if (createResult._tag === "Failure") {
@@ -155,9 +186,11 @@ const makeReconcile = <R>(input: {
   readonly state: RegistryState;
   readonly driversById: ReadonlyMap<ProviderDriverKind, AnyProviderDriver<R>>;
   readonly parentScope: Scope.Scope;
-}): ((configMap: ProviderInstanceConfigMap) => Effect.Effect<void, never, R>) => {
+}): ((
+  configMap: ProviderInstanceRegistryMutator.ProviderInstanceRuntimeMap,
+) => Effect.Effect<void, never, R>) => {
   const { state, driversById, parentScope } = input;
-  return (configMap: ProviderInstanceConfigMap) =>
+  return (configMap: ProviderInstanceRegistryMutator.ProviderInstanceRuntimeMap) =>
     Effect.gen(function* () {
       const previousEntries = yield* Ref.get(state.entries);
       const previousUnavailable = yield* Ref.get(state.unavailable);
@@ -253,7 +286,7 @@ export const makeProviderInstanceRegistry = Effect.fn(
   "ProviderInstanceRegistry.makeProviderInstanceRegistry",
 )(function* <R>(input: {
   readonly drivers: ReadonlyArray<AnyProviderDriver<R>>;
-  readonly configMap: ProviderInstanceConfigMap;
+  readonly configMap: ProviderInstanceRegistryMutator.ProviderInstanceRuntimeMap;
 }): Effect.fn.Return<
   {
     readonly registry: ProviderInstanceRegistry["Service"];
@@ -314,7 +347,7 @@ export const makeProviderInstanceRegistry = Effect.fn(
 
 export const layer = <R>(input: {
   readonly drivers: ReadonlyArray<AnyProviderDriver<R>>;
-  readonly configMap: ProviderInstanceConfigMap;
+  readonly configMap: ProviderInstanceRegistryMutator.ProviderInstanceRuntimeMap;
 }): Layer.Layer<
   ProviderInstanceRegistry | ProviderInstanceRegistryMutator.ProviderInstanceRegistryMutator,
   never,
diff --git a/apps/server/src/provider/ProviderInstanceRegistryHydration.test.ts b/apps/server/src/provider/ProviderInstanceRegistryHydration.test.ts
index c497e00ac17e9..fb16fa967d0e7 100644
--- a/apps/server/src/provider/ProviderInstanceRegistryHydration.test.ts
+++ b/apps/server/src/provider/ProviderInstanceRegistryHydration.test.ts
@@ -77,6 +77,28 @@ describe("deriveProviderInstanceConfigMap", () => {
     expect(merged[instanceId]).toBeUndefined();
   });
 
+  it("attaches the environment's proxy only to instances that use it", () => {
+    const claudeId = ProviderInstanceId.make("claude_direct");
+    const settings = settingsWith({
+      providerProxy: { url: " http://proxy:8317/v1/ ", apiKey: "sk-proxy", managementKey: "" },
+      providerInstances: {
+        [instanceId]: { driver: ProviderDriverKind.make("codex"), useProxy: true },
+        [claudeId]: { driver: ProviderDriverKind.make("claudeAgent") },
+      },
+    });
+
+    const merged = deriveProviderInstanceConfigMap(settings);
+
+    expect(merged[instanceId]?.proxy).toEqual({ url: "http://proxy:8317", apiKey: "sk-proxy" });
+    expect(merged[claudeId]).toBe(settings.providerInstances[claudeId]);
+    expect(
+      deriveProviderInstanceConfigMap({
+        ...settings,
+        providerProxy: { ...settings.providerProxy, url: "" },
+      })[instanceId]?.proxy,
+    ).toBeUndefined();
+  });
+
   it("ignores a project override that disables an instance, leaving the machine's config in charge", () => {
     const settings = settingsWith({
       providerInstances: {
diff --git a/apps/server/src/provider/ProviderInstanceRegistryHydration.ts b/apps/server/src/provider/ProviderInstanceRegistryHydration.ts
index cb778f1638a22..52560781213e6 100644
--- a/apps/server/src/provider/ProviderInstanceRegistryHydration.ts
+++ b/apps/server/src/provider/ProviderInstanceRegistryHydration.ts
@@ -5,9 +5,12 @@ import {
   providerInstanceConfigEnabledFlag,
   resolveProviderInstanceEnabled,
   type ProviderInstanceConfig,
-  type ProviderInstanceConfigMap,
   ServerSettings,
 } from "@t3tools/contracts";
+import {
+  normalizeProviderProxyUrl,
+  type ProviderProxyRoute,
+} from "@t3tools/provider-core/server/providerProxy";
 import * as HostProcess from "@t3tools/shared/HostProcess";
 import * as Effect from "effect/Effect";
 import * as FileSystem from "effect/FileSystem";
@@ -42,9 +45,14 @@ type ProviderInstanceRegistryHydrationEnv =
   // The Claude runner counts its CLIs as running agents for port discovery.
   | PortScanner.PortDiscovery;
 
+const resolveProviderProxyRoute = (settings: ServerSettings): ProviderProxyRoute | undefined => {
+  const url = normalizeProviderProxyUrl(settings.providerProxy.url);
+  return url === "" ? undefined : { url, apiKey: settings.providerProxy.apiKey };
+};
+
 export const deriveProviderInstanceConfigMap = (
   settings: ServerSettings,
-): ProviderInstanceConfigMap => {
+): ProviderInstanceRegistryMutator.ProviderInstanceRuntimeMap => {
   const merged: Record<string, ProviderInstanceConfig> = { ...settings.providerInstances };
 
   for (const driver of BUILT_IN_DRIVERS) {
@@ -73,7 +81,14 @@ export const deriveProviderInstanceConfigMap = (
     }
   }
 
-  return merged as ProviderInstanceConfigMap;
+  const proxy = resolveProviderProxyRoute(settings);
+  if (proxy === undefined) return merged;
+  return Object.fromEntries(
+    Object.entries(merged).map(([id, entry]) => [
+      id,
+      entry.useProxy === true ? { ...entry, proxy } : entry,
+    ]),
+  );
 };
 
 export const DEV_REPLAY_INSTANCE_ID = ProviderInstanceId.make("devReplay");
@@ -157,7 +172,7 @@ export const layer: Layer.Layer<
     );
     const initialConfigMap =
       initialSettings === undefined
-        ? ({} as ProviderInstanceConfigMap)
+        ? ({} as ProviderInstanceRegistryMutator.ProviderInstanceRuntimeMap)
         : deriveProviderInstanceConfigMap(initialSettings);
 
     const layerMutable = ProviderInstanceRegistry.layer({
diff --git a/apps/server/src/provider/ProviderInstanceRegistryMutator.ts b/apps/server/src/provider/ProviderInstanceRegistryMutator.ts
index 51322826230d8..66e3245dc2d28 100644
--- a/apps/server/src/provider/ProviderInstanceRegistryMutator.ts
+++ b/apps/server/src/provider/ProviderInstanceRegistryMutator.ts
@@ -1,10 +1,17 @@
 /** Reconcile closes removed/replaced scopes before creating replacements: at most one live instance per id. */
-import type { ProviderInstanceConfigMap } from "@t3tools/contracts";
+import type { ProviderInstanceConfig } from "@t3tools/contracts";
+import type { ProviderProxyRoute } from "@t3tools/provider-core/server/providerProxy";
 import * as Context from "effect/Context";
 import type * as Effect from "effect/Effect";
 
+/** Runtime-only inputs ride on the entry, so a change to them rebuilds the instance. */
+export type ProviderInstanceRuntimeEntry = ProviderInstanceConfig & {
+  readonly proxy?: ProviderProxyRoute;
+};
+export type ProviderInstanceRuntimeMap = Readonly<Record<string, ProviderInstanceRuntimeEntry>>;
+
 export interface ProviderInstanceRegistryMutatorShape {
-  readonly reconcile: (configMap: ProviderInstanceConfigMap) => Effect.Effect<void>;
+  readonly reconcile: (configMap: ProviderInstanceRuntimeMap) => Effect.Effect<void>;
 }
 
 export class ProviderInstanceRegistryMutator extends Context.Service<
diff --git a/apps/server/src/provider/codexLaunchArgs.test.ts b/apps/server/src/provider/codexLaunchArgs.test.ts
index ce18c8f3f1bd5..55d793cc97727 100644
--- a/apps/server/src/provider/codexLaunchArgs.test.ts
+++ b/apps/server/src/provider/codexLaunchArgs.test.ts
@@ -2,7 +2,11 @@ import * as NodeAssert from "node:assert/strict";
 
 import { describe, it } from "vite-plus/test";
 
-import { codexAppServerArgs, codexExecLaunchArgs } from "./codexLaunchArgs.ts";
+import {
+  applyCodexProxyRuntime,
+  codexAppServerArgs,
+  codexExecLaunchArgs,
+} from "./codexLaunchArgs.ts";
 
 describe("codexAppServerArgs", () => {
   it("preserves escaped TOML quotes in config values", () => {
@@ -27,3 +31,40 @@ describe("codexExecLaunchArgs", () => {
     ]);
   });
 });
+
+describe("applyCodexProxyRuntime", () => {
+  const proxyProvider = (keyField: string) =>
+    `model_providers.t3_proxy={name="T3 proxy",base_url="http://proxy:8317/v1",${keyField}wire_api="responses",requires_openai_auth=false,supports_websockets=false}`;
+
+  it("adds the proxy provider after env launch args and keeps the key out of argv", () => {
+    const { config, environment } = applyCodexProxyRuntime(
+      { launchArgs: "--ignored" },
+      { T3CODE_CODEX_LAUNCH_ARGS: "--strict-config", PATH: "/bin" },
+      { url: "http://proxy:8317", apiKey: "sk-proxy" },
+    );
+
+    NodeAssert.deepStrictEqual(codexAppServerArgs(config.launchArgs), [
+      "app-server",
+      "--strict-config",
+      "-c",
+      'model_provider="t3_proxy"',
+      "-c",
+      proxyProvider('env_key="T3_PROXY_KEY",'),
+    ]);
+    NodeAssert.deepStrictEqual(codexExecLaunchArgs(config.launchArgs).slice(-2), [
+      "-c",
+      proxyProvider('env_key="T3_PROXY_KEY",'),
+    ]);
+    NodeAssert.deepStrictEqual(environment, { PATH: "/bin", T3_PROXY_KEY: "sk-proxy" });
+  });
+
+  it("sends no key to a proxy that has none", () => {
+    const { config } = applyCodexProxyRuntime(
+      { launchArgs: "" },
+      {},
+      { url: "http://proxy:8317", apiKey: "" },
+    );
+
+    NodeAssert.deepStrictEqual(codexAppServerArgs(config.launchArgs).at(-1), proxyProvider(""));
+  });
+});
diff --git a/apps/server/src/provider/codexLaunchArgs.ts b/apps/server/src/provider/codexLaunchArgs.ts
index 33def5ce9a61a..cc67972341b5d 100644
--- a/apps/server/src/provider/codexLaunchArgs.ts
+++ b/apps/server/src/provider/codexLaunchArgs.ts
@@ -1,3 +1,7 @@
+import {
+  providerProxyApiUrl,
+  type ProviderProxyRoute,
+} from "@t3tools/provider-core/server/providerProxy";
 import { tokenizeCliArgs } from "@t3tools/shared/cliArgs";
 
 const T3CODE_CODEX_LAUNCH_ARGS_ENV = "T3CODE_CODEX_LAUNCH_ARGS";
@@ -7,6 +11,34 @@ export const resolveCodexLaunchArgs = (
   environment: NodeJS.ProcessEnv = process.env,
 ) => environment[T3CODE_CODEX_LAUNCH_ARGS_ENV]?.trim() || launchArgs?.trim() || "";
 
+// Codex stores this ID in each rollout and resumes through it; renaming it strands proxied threads.
+export const CODEX_PROXY_MODEL_PROVIDER = "t3_proxy";
+const CODEX_PROXY_KEY_ENV = "T3_PROXY_KEY";
+
+/** Appends the proxy provider after any configured launch arguments; the key stays out of argv. */
+export const applyCodexProxyRuntime = <Config extends { readonly launchArgs: string }>(
+  config: Config,
+  environment: NodeJS.ProcessEnv,
+  proxy: ProviderProxyRoute | undefined,
+): { readonly config: Config; readonly environment: NodeJS.ProcessEnv } => {
+  if (proxy === undefined) return { config, environment };
+  const keyField = proxy.apiKey === "" ? "" : `env_key="${CODEX_PROXY_KEY_ENV}",`;
+  const proxyArgs = [
+    `model_provider="${CODEX_PROXY_MODEL_PROVIDER}"`,
+    `model_providers.${CODEX_PROXY_MODEL_PROVIDER}={name="T3 proxy",base_url=${JSON.stringify(providerProxyApiUrl(proxy))},${keyField}wire_api="responses",requires_openai_auth=false,supports_websockets=false}`,
+  ]
+    .map((value) => `-c ${JSON.stringify(value)}`)
+    .join(" ");
+  const launchArgs = resolveCodexLaunchArgs(config.launchArgs, environment);
+  const next: NodeJS.ProcessEnv = { ...environment, [CODEX_PROXY_KEY_ENV]: proxy.apiKey };
+  // Folded into launchArgs above; left in place it would replace the proxy arguments.
+  delete next[T3CODE_CODEX_LAUNCH_ARGS_ENV];
+  return {
+    config: { ...config, launchArgs: launchArgs === "" ? proxyArgs : `${launchArgs} ${proxyArgs}` },
+    environment: next,
+  };
+};
+
 const codexLaunchArgv = (launchArgs?: string): ReadonlyArray<string> => tokenizeCliArgs(launchArgs);
 
 export const codexAppServerArgs = (launchArgs?: string) => [
diff --git a/apps/server/src/serverSettings.test.ts b/apps/server/src/serverSettings.test.ts
index 8b7d81859b70d..e863046af30ff 100644
--- a/apps/server/src/serverSettings.test.ts
+++ b/apps/server/src/serverSettings.test.ts
@@ -1246,7 +1246,7 @@ it.layer(NodeServices.layer)("server settings", (it) => {
   );
 
   it.effect(
-    "uses the same secret lifecycle for provider config, environment, host tokens, and quota keys",
+    "uses the same secret lifecycle for provider config, environment, host tokens, quota and proxy keys",
     () =>
       Effect.gen(function* () {
         const service = yield* ServerSettingsModule.ServerSettingsService;
@@ -1278,6 +1278,11 @@ it.layer(NodeServices.layer)("server settings", (it) => {
               enabled: true,
             },
           },
+          providerProxy: {
+            url: "http://proxy.example.test:8317",
+            apiKey: "proxy-client-secret",
+            managementKey: "proxy-management-secret",
+          },
           easDeviceHosts: [
             {
               kind: "eas",
@@ -1297,6 +1302,8 @@ it.layer(NodeServices.layer)("server settings", (it) => {
           "bitbucket-secret",
           "gitcafe-secret",
           "quota-secret",
+          "proxy-client-secret",
+          "proxy-management-secret",
           "expo-secret",
         ];
         const client = ServerSettingsModule.redactServerSettingsForClient(saved);
@@ -1312,6 +1319,7 @@ it.layer(NodeServices.layer)("server settings", (it) => {
           providerInstances: client.providerInstances,
           sourceControlHosts: client.sourceControlHosts,
           usageLimitSources: client.usageLimitSources,
+          providerProxy: client.providerProxy,
           easDeviceHosts: client.easDeviceHosts,
         });
         for (const value of values) assert.include(JSON.stringify(echoed), value);
@@ -1362,6 +1370,8 @@ it.layer(NodeServices.layer)("server settings", (it) => {
           }),
           sourceControlHostSecretName({ kind: "gitcafe", field: "token", serverHost: null }),
           "usage-limit-source-aHVi",
+          "provider-proxy-YXBpS2V5",
+          "provider-proxy-bWFuYWdlbWVudEtleQ",
         ];
         for (const name of secretNames) {
           assert.isTrue(Option.isSome(yield* store.get(name)), name);
@@ -1374,6 +1384,7 @@ it.layer(NodeServices.layer)("server settings", (it) => {
             gitcafe: { token: "" },
           },
           usageLimitSources: { [UsageLimitSourceId.make("hub")]: null },
+          providerProxy: { apiKey: "", managementKey: "" },
         });
         for (const name of secretNames) {
           assert.isTrue(Option.isNone(yield* store.get(name)));
diff --git a/apps/server/src/settingsSecrets.ts b/apps/server/src/settingsSecrets.ts
index dff6b96f52a1b..c08c44acbabfa 100644
--- a/apps/server/src/settingsSecrets.ts
+++ b/apps/server/src/settingsSecrets.ts
@@ -3,6 +3,7 @@ import {
   ClaudeSettings,
   CodexSettings,
   EasDeviceHostConfig,
+  ProviderProxySettings,
   type ServerSettings,
   SimlockDeviceHostConfig,
   UsageLimitSourceConfig,
@@ -33,6 +34,7 @@ const providerSecretFields = new Map([
   ),
 ]);
 const usageLimitSecretFields = secretSettingsFields(UsageLimitSourceConfig);
+const providerProxySecretFields = secretSettingsFields(ProviderProxySettings);
 const easDeviceHostSecretFields = secretSettingsFields(EasDeviceHostConfig);
 const simlockDeviceHostSecretFields = secretSettingsFields(SimlockDeviceHostConfig);
 const encode = (value: string) => Buffer.from(value, "utf8").toString("base64url");
@@ -146,6 +148,13 @@ export function mapSettingsSecrets(
     ]),
   ) as ServerSettings["usageLimitSources"];
 
+  const providerProxy = mapFields(
+    settings.providerProxy,
+    providerProxySecretFields,
+    (field, serverHost) =>
+      `provider-proxy-${encode(field)}` + (serverHost === null ? "" : `-${encode(serverHost)}`),
+  ) as ServerSettings["providerProxy"];
+
   const easDeviceHosts = settings.easDeviceHosts.map(
     (host) =>
       mapFields(
@@ -174,6 +183,7 @@ export function mapSettingsSecrets(
     providerInstances,
     sourceControlHosts,
     usageLimitSources,
+    providerProxy,
     easDeviceHosts,
     simlockDeviceHosts,
   };
diff --git a/apps/server/src/usage/UsageLimitSources.test.ts b/apps/server/src/usage/UsageLimitSources.test.ts
index b8976fca81e7d..56ca34f8e5d16 100644
--- a/apps/server/src/usage/UsageLimitSources.test.ts
+++ b/apps/server/src/usage/UsageLimitSources.test.ts
@@ -1,6 +1,10 @@
 import * as NodeCrypto from "@effect/platform-node/NodeCrypto";
 import { expect, it } from "@effect/vitest";
-import { ServerConfigStreamEvent, UsageLimitSourceId } from "@t3tools/contracts";
+import {
+  DEFAULT_SERVER_SETTINGS,
+  ServerConfigStreamEvent,
+  UsageLimitSourceId,
+} from "@t3tools/contracts";
 import * as Effect from "effect/Effect";
 import * as Layer from "effect/Layer";
 import * as Schema from "effect/Schema";
@@ -83,3 +87,30 @@ it.effect("keeps malformed source URLs encodable for config subscribers", () =>
     Effect.scoped,
   ),
 );
+
+it("reports the routing proxy's accounts unless a hub already points at it", () => {
+  const hub = {
+    kind: "cliproxy" as const,
+    url: "http://proxy:8317/",
+    managementKey: "hub-key",
+    enabled: true,
+  };
+  const settings = {
+    ...DEFAULT_SERVER_SETTINGS,
+    providerProxy: { url: "http://proxy:8317/v1", apiKey: "sk", managementKey: "mgmt" },
+  };
+
+  expect(UsageLimitSources.effectiveUsageLimitSources(settings)).toEqual({
+    [UsageLimitSources.PROVIDER_PROXY_SOURCE_ID]: {
+      kind: "cliproxy",
+      label: "Proxy",
+      url: "http://proxy:8317",
+      managementKey: "mgmt",
+      enabled: true,
+    },
+  });
+  const listed = { [UsageLimitSourceId.make("hub")]: hub };
+  expect(
+    UsageLimitSources.effectiveUsageLimitSources({ ...settings, usageLimitSources: listed }),
+  ).toBe(listed);
+});
diff --git a/apps/server/src/usage/UsageLimitSources.ts b/apps/server/src/usage/UsageLimitSources.ts
index 7a068cde85f6c..dc8d1853f3dc0 100644
--- a/apps/server/src/usage/UsageLimitSources.ts
+++ b/apps/server/src/usage/UsageLimitSources.ts
@@ -8,6 +8,7 @@ import {
   type UsageLimitSourceId,
   type UsageLimitSourceSnapshot,
 } from "@t3tools/contracts";
+import { normalizeProviderProxyUrl } from "@t3tools/provider-core/server/providerProxy";
 import { resolveServerBackgroundActivitySettings } from "@t3tools/shared/backgroundActivitySettings";
 import * as Context from "effect/Context";
 import * as DateTime from "effect/DateTime";
@@ -46,6 +47,31 @@ function sourceLabel(id: string, config: UsageLimitSourceConfig): string {
   }
 }
 
+export const PROVIDER_PROXY_SOURCE_ID = "provider-proxy" as UsageLimitSourceId;
+
+/** The routing proxy reports its accounts without a separate hub entry, unless one already points at it. */
+export function effectiveUsageLimitSources(
+  settings: ServerSettings,
+): Readonly<Record<string, UsageLimitSourceConfig>> {
+  const url = normalizeProviderProxyUrl(settings.providerProxy.url);
+  const { managementKey } = settings.providerProxy;
+  if (url === "" || managementKey === "") return settings.usageLimitSources;
+  const alreadyListed = Object.values(settings.usageLimitSources).some(
+    (source) => normalizeProviderProxyUrl(source.url) === url,
+  );
+  if (alreadyListed) return settings.usageLimitSources;
+  return {
+    ...settings.usageLimitSources,
+    [PROVIDER_PROXY_SOURCE_ID]: {
+      kind: "cliproxy",
+      label: "Proxy",
+      url,
+      managementKey,
+      enabled: true,
+    },
+  };
+}
+
 /** @public */
 export const make = Effect.gen(function* () {
   const api = yield* makeCliproxyApi;
@@ -89,9 +115,9 @@ export const make = Effect.gen(function* () {
     const settings = yield* settingsService.getSettings.pipe(
       Effect.orElseSucceed((): ServerSettings | null => null),
     );
-    const entries = Object.entries(settings?.usageLimitSources ?? {}).filter(
-      ([, config]) => config.enabled,
-    );
+    const entries = Object.entries(
+      settings === null ? {} : effectiveUsageLimitSources(settings),
+    ).filter(([, config]) => config.enabled);
     const snapshots = yield* Effect.forEach(
       entries,
       ([id, config]) => readSource(id as UsageLimitSourceId, config),
@@ -107,7 +133,7 @@ export const make = Effect.gen(function* () {
     const settings = yield* settingsService.getSettings.pipe(
       Effect.mapError(() => new UsageLimitSourceError({ detail: "Could not read hub settings." })),
     );
-    const config = settings.usageLimitSources[input.sourceId];
+    const config = effectiveUsageLimitSources(settings)[input.sourceId];
     if (!config?.enabled || !config.managementKey) {
       return yield* new UsageLimitSourceError({
         detail: "The usage limit source is missing or disabled.",
@@ -121,7 +147,7 @@ export const make = Effect.gen(function* () {
   }, refreshLock.withPermits(1));
 
   yield* settingsService.streamChanges.pipe(
-    Stream.map((settings) => settings.usageLimitSources),
+    Stream.map(effectiveUsageLimitSources),
     Stream.changes,
     Stream.runForEach(() => refresh),
     Effect.forkScoped,
diff --git a/apps/web/src/components/settings/ProviderInstanceCard.tsx b/apps/web/src/components/settings/ProviderInstanceCard.tsx
index 88361eac68bc8..c3af4e23eccdb 100644
--- a/apps/web/src/components/settings/ProviderInstanceCard.tsx
+++ b/apps/web/src/components/settings/ProviderInstanceCard.tsx
@@ -18,6 +18,7 @@ import * as Result from "effect/Result";
 import { useState, type ReactElement, type ReactNode } from "react";
 import {
   isProviderDriverKind,
+  PROXY_ROUTED_DRIVERS,
   resolveProviderInstanceEnabled,
   type ProviderInstanceConfig,
   type ProviderInstanceEnvironmentVariable,
@@ -247,6 +248,51 @@ export function nextProviderEnvironmentWithFieldValue(
   return next;
 }
 
+function proxyBlockedReason(instance: ProviderInstanceConfig): string | undefined {
+  if (instance.driver === "codex" && readCodexSetupMode(instance.config) === "managed") {
+    return "T3-managed ChatGPT sign-in can't use a proxy.";
+  }
+  const serverUrl = (instance.config as { readonly serverUrl?: unknown } | undefined)?.serverUrl;
+  if (instance.driver === "opencode" && typeof serverUrl === "string" && serverUrl.trim() !== "") {
+    return "An external OpenCode server can't use this environment's proxy.";
+  }
+  return undefined;
+}
+
+function ProviderProxyRow(props: {
+  readonly instanceId: ProviderInstanceId;
+  readonly instance: ProviderInstanceConfig;
+  readonly proxyConfigured: boolean;
+  readonly onUpdate: (nextInstance: ProviderInstanceConfig) => void;
+}) {
+  const enabled = props.instance.useProxy === true;
+  const blocked = proxyBlockedReason(props.instance);
+  const switchId = `provider-instance-${props.instanceId}-use-proxy`;
+  return (
+    <SettingsRow
+      title={<label htmlFor={switchId}>Use proxy</label>}
+      description={
+        blocked ??
+        (props.proxyConfigured
+          ? "Send this provider's requests through the proxy and its accounts."
+          : "Add a proxy URL under Proxy in these settings first.")
+      }
+      control={
+        <Switch
+          id={switchId}
+          checked={enabled}
+          // Turning it off stays possible so a blocked instance can recover.
+          disabled={!enabled && (blocked !== undefined || !props.proxyConfigured)}
+          onCheckedChange={(useProxy) => {
+            const { useProxy: _previous, ...rest } = props.instance;
+            props.onUpdate(useProxy ? { ...rest, useProxy: true } : rest);
+          }}
+        />
+      }
+    />
+  );
+}
+
 function ProviderEnvironmentFieldRow(props: {
   readonly field: ProviderEnvironmentField;
   readonly variable: ProviderInstanceEnvironmentVariable | undefined;
@@ -585,6 +631,8 @@ interface ProviderInstanceCardProps {
   readonly onAcceptUrlAuth?: ((action: AcpRegistryUrlAuthAction) => void) | undefined;
   readonly environmentId?: EnvironmentId | undefined;
   readonly projectOverride?: ProjectOverrideControl | undefined;
+  /** Whether this environment has a proxy URL for `useProxy` to route through. */
+  readonly proxyConfigured?: boolean | undefined;
   readonly acpProjects?:
     | ReadonlyArray<{
         readonly id: ProjectId;
@@ -602,6 +650,7 @@ const NO_CUSTOM_MODELS: ReadonlyArray<CustomModelDefinition> = [];
 export function ProviderInstanceCard({
   instanceId,
   instance,
+  proxyConfigured = false,
   driverOption,
   liveProvider,
   mode,
@@ -1216,6 +1265,22 @@ export function ProviderInstanceCard({
         </SettingsSection>
       ) : null}
 
+      {PROXY_ROUTED_DRIVERS.has(instance.driver) ? (
+        <SettingsSection
+          title="Proxy"
+          inert={readOnly}
+          aria-disabled={readOnly || undefined}
+          className={readOnly ? "opacity-50 select-none" : undefined}
+        >
+          <ProviderProxyRow
+            instanceId={instanceId}
+            instance={instance}
+            proxyConfigured={proxyConfigured}
+            onUpdate={onUpdate}
+          />
+        </SettingsSection>
+      ) : null}
+
       <SettingsSection
         title="Environment"
         inert={readOnly}
diff --git a/apps/web/src/components/settings/ProviderProxySettings.tsx b/apps/web/src/components/settings/ProviderProxySettings.tsx
new file mode 100644
index 0000000000000..e413ed6a1a6f9
--- /dev/null
+++ b/apps/web/src/components/settings/ProviderProxySettings.tsx
@@ -0,0 +1,93 @@
+import type { EnvironmentId, UnifiedSettings } from "@t3tools/contracts";
+
+import { useUpdateEnvironmentSettings } from "../../hooks/useSettings";
+import { Button } from "../ui/button";
+import { DraftInput } from "../ui/draft-input";
+import { SecretInput } from "./SecretInput";
+import { searchableSetting } from "./settingsSearch";
+import { SettingsRow, SettingsSection } from "./settingsLayout";
+
+const CONTROL_CLASS = "w-full min-w-0 @min-[32rem]/settings-row:w-56";
+
+/** Secrets arrive redacted: any non-empty value means one is stored. */
+export function ProviderProxySettings({
+  environmentId,
+  proxy,
+  readOnly,
+}: {
+  readonly environmentId: EnvironmentId;
+  readonly proxy: UnifiedSettings["providerProxy"];
+  readonly readOnly: boolean;
+}) {
+  const updateSettings = useUpdateEnvironmentSettings(environmentId);
+  const update = (patch: Partial<UnifiedSettings["providerProxy"]>) =>
+    updateSettings({ providerProxy: patch });
+
+  return (
+    <SettingsSection
+      {...searchableSetting("provider-proxy")}
+      headerAction={
+        proxy.url !== "" && !readOnly ? (
+          <Button
+            size="xs"
+            variant="ghost"
+            onClick={() => update({ url: "", apiKey: "", managementKey: "" })}
+          >
+            Remove proxy
+          </Button>
+        ) : null
+      }
+    >
+      <SettingsRow
+        id="provider-proxy-url"
+        title={<label htmlFor="provider-proxy-url-input">Proxy URL</label>}
+        description="A CLIProxyAPI server. Turn on Use proxy for a Claude, Codex, or OpenCode provider to send its requests here."
+        control={
+          <DraftInput
+            id="provider-proxy-url-input"
+            size="sm"
+            className={CONTROL_CLASS}
+            value={proxy.url}
+            placeholder="http://192.168.1.10:8317"
+            autoComplete="off"
+            spellCheck={false}
+            disabled={readOnly}
+            onCommit={(url) => update({ url: url.trim() })}
+          />
+        }
+      />
+      <SettingsRow
+        id="provider-proxy-api-key"
+        title={<label htmlFor="provider-proxy-api-key-input">API key</label>}
+        description="One of the proxy's API keys. Leave empty if the proxy has none."
+        control={
+          <SecretInput
+            id="provider-proxy-api-key-input"
+            size="sm"
+            className={CONTROL_CLASS}
+            value=""
+            configured={proxy.apiKey !== ""}
+            disabled={readOnly}
+            onCommit={(apiKey) => update({ apiKey: apiKey.trim() })}
+          />
+        }
+      />
+      <SettingsRow
+        id="provider-proxy-management-key"
+        title={<label htmlFor="provider-proxy-management-key-input">Management key</label>}
+        description="Optional. Shows the proxy's accounts under Usage → Limits."
+        control={
+          <SecretInput
+            id="provider-proxy-management-key-input"
+            size="sm"
+            className={CONTROL_CLASS}
+            value=""
+            configured={proxy.managementKey !== ""}
+            disabled={readOnly}
+            onCommit={(managementKey) => update({ managementKey: managementKey.trim() })}
+          />
+        }
+      />
+    </SettingsSection>
+  );
+}
diff --git a/apps/web/src/components/settings/ProviderSettingsPanel.tsx b/apps/web/src/components/settings/ProviderSettingsPanel.tsx
index 9dae72e98ff50..54fb84fa5bda2 100644
--- a/apps/web/src/components/settings/ProviderSettingsPanel.tsx
+++ b/apps/web/src/components/settings/ProviderSettingsPanel.tsx
@@ -98,6 +98,7 @@ import { stackedThreadToast, toastManager } from "../ui/toast";
 import { AddProviderInstanceDialog } from "./AddProviderInstanceDialog";
 import { ExpandableText } from "./ExpandableText";
 import { ProviderInstanceCard } from "./ProviderInstanceCard";
+import { ProviderProxySettings } from "./ProviderProxySettings";
 import { UsageProviderSettings } from "./UsageProviderSettings";
 import { ProviderSetupSection, readAntigravityAuthMethod } from "./ProviderSetupSection";
 import { ProviderAuthenticationSection } from "./ProviderAuthenticationSection";
@@ -931,6 +932,7 @@ export function EnvironmentProviderSettings({
         canWriteSettings={canWriteSettings}
         liveProvider={serverProviders.find((candidate) => candidate.instanceId === row.instanceId)}
         isUpdateDispatching={updatingProviderInstanceIds.has(row.instanceId)}
+        proxyConfigured={settings.providerProxy.url !== ""}
         showProjectOverride={showProjectOverride}
         projectOverrideValue={
           showProjectOverride
@@ -1069,6 +1071,13 @@ export function EnvironmentProviderSettings({
         </SettingsGroup>
       </SettingsSection>
 
+      <ProviderProxySettings
+        key={`proxy-${environmentId}`}
+        environmentId={environmentId}
+        proxy={settings.providerProxy}
+        readOnly={readOnly}
+      />
+
       <UsageProviderSettings
         key={environmentId}
         environmentId={environmentId}
@@ -1217,6 +1226,7 @@ function ProviderInstanceRow({
   canWriteSettings,
   liveProvider,
   isUpdateDispatching,
+  proxyConfigured,
   showProjectOverride,
   projectOverrideValue,
   projectOverrideEffectiveEnabled,
@@ -1237,6 +1247,7 @@ function ProviderInstanceRow({
   readonly canWriteSettings: boolean;
   readonly liveProvider: ServerProvider | undefined;
   readonly isUpdateDispatching: boolean;
+  readonly proxyConfigured: boolean;
   readonly showProjectOverride: boolean;
   readonly projectOverrideValue: boolean | undefined;
   readonly projectOverrideEffectiveEnabled: boolean;
@@ -1292,6 +1303,7 @@ function ProviderInstanceRow({
       }
       instanceId={instanceId}
       instance={instance}
+      proxyConfigured={proxyConfigured}
       driverOption={driverOption}
       liveProvider={liveProvider}
       mode={mode}
diff --git a/apps/web/src/components/settings/settingsSearch.ts b/apps/web/src/components/settings/settingsSearch.ts
index dc494caf5344d..1a86d42574e8f 100644
--- a/apps/web/src/components/settings/settingsSearch.ts
+++ b/apps/web/src/components/settings/settingsSearch.ts
@@ -799,6 +799,15 @@ export const SETTINGS_SEARCH_ITEMS = [
       "agents cli codex claude cursor grok fx opencode antigravity google sign in sign out install subscription instances authentication api key models configuration binary path config directory endpoint arguments environment variables display name accent color custom favorite hidden auto compact",
     ],
   },
+  {
+    id: "provider-proxy",
+    title: "Proxy",
+    to: "/settings/providers",
+    searchTerms: [
+      "proxy CLIProxyAPI CLI proxy route account pool load balance api key management key base url",
+    ],
+    providerSettingsOnly: true,
+  },
   {
     id: "usage-providers",
     title: "Usage providers",
diff --git a/docs/user/install.md b/docs/user/install.md
index 1e1693d0b32ee..28558e1ea73d4 100644
--- a/docs/user/install.md
+++ b/docs/user/install.md
@@ -194,6 +194,19 @@ instance can have its own environment variables, such as API keys or a custom
 base URL. Mark secret values as sensitive; after saving, T3 Code does not display
 their original values.
 
+### Route providers through a proxy
+
+A [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) server can serve Claude, Codex,
+and OpenCode from accounts it holds, and spread requests across several accounts. To use one,
+open **Settings → Providers → Proxy** on the environment that runs the agents. Enter the proxy's
+URL and one of its API keys. Add its management key to see its accounts under **Usage → Limits**.
+Then turn on **Use proxy** for each Claude, Codex, or OpenCode provider that should use it.
+
+A provider with **Use proxy** on never falls back to its own login. If the proxy is removed, the
+provider shows as unavailable until you add a proxy again or turn the switch off. Codex threads
+started through the proxy need it to continue. T3-managed ChatGPT sign-in and external OpenCode
+servers cannot use a proxy.
+
 For provider-specific setup and accounts, see [Codex](./providers-codex.md),
 [Claude](./providers-claude.md), [OpenCode](./providers-opencode.md),
 [Antigravity](./providers-antigravity.md), [Pi](./providers-pi.md),
diff --git a/docs/user/usage.md b/docs/user/usage.md
index af1fc02352f83..86b2828aa96cd 100644
--- a/docs/user/usage.md
+++ b/docs/user/usage.md
@@ -152,8 +152,9 @@ environment that will connect to the hub and enter its URL and management key.
 The accounts appear under **Usage → Limits**. Codex accounts show banked reset credits; select an
 account and choose **Use reset** to redeem one. No hub plugin is required.
 
-This connection supplies usage information; configure
-the provider separately to send agent requests through the hub. Remove the hub from the same
+This connection supplies usage information only. To send agent requests through the hub, set it
+as the environment's [proxy](./install.md#route-providers-through-a-proxy); with its management
+key there, its accounts appear here without a separate hub. Remove the hub from the same
 settings section when you no longer need it.
 
 ## Subscription usage widget
diff --git a/packages/contracts/src/providerInstance.ts b/packages/contracts/src/providerInstance.ts
index 9cc0a3f52375d..169164a0d5937 100644
--- a/packages/contracts/src/providerInstance.ts
+++ b/packages/contracts/src/providerInstance.ts
@@ -45,10 +45,19 @@ export const ProviderInstanceConfig = Schema.Struct({
   accentColor: Schema.optional(TrimmedNonEmptyString),
   environment: Schema.optionalKey(ProviderInstanceEnvironment),
   enabled: Schema.optionalKey(Schema.Boolean),
+  /** Sends model traffic through `ServerSettings.providerProxy`; see PROXY_ROUTED_DRIVERS. */
+  useProxy: Schema.optionalKey(Schema.Boolean),
   config: Schema.optionalKey(Schema.Unknown),
 });
 export type ProviderInstanceConfig = typeof ProviderInstanceConfig.Type;
 
+/** Drivers whose harness can send model traffic to a CLIProxyAPI endpoint. */
+export const PROXY_ROUTED_DRIVERS: ReadonlySet<string> = new Set([
+  "claudeAgent",
+  "codex",
+  "opencode",
+]);
+
 export const ProviderInstanceMutation = Schema.Union([
   Schema.Struct({
     operation: Schema.Literal("create"),
diff --git a/packages/contracts/src/settings.ts b/packages/contracts/src/settings.ts
index 179e58b7a0b56..8188aa1ffc466 100644
--- a/packages/contracts/src/settings.ts
+++ b/packages/contracts/src/settings.ts
@@ -928,6 +928,14 @@ const SecretProviderConfigWrite = Schema.Struct({
       : `Invalid ${entry.kind} secret provider config.`;
   }),
 );
+/** A CLIProxyAPI server that `useProxy` provider instances send model traffic to. Empty `url` turns it off. */
+export const ProviderProxySettings = Schema.Struct({
+  url: TrimmedString.pipe(Schema.withDecodingDefault(Effect.succeed(""))),
+  apiKey: TrimmedString.pipe(Schema.withDecodingDefault(Effect.succeed("")), secretSetting),
+  // Optional; when set, the proxy's accounts also feed Usage -> Limits.
+  managementKey: TrimmedString.pipe(Schema.withDecodingDefault(Effect.succeed("")), secretSetting),
+});
+export type ProviderProxySettings = typeof ProviderProxySettings.Type;
 
 export const SourceControlHostSettings = Schema.Record(Schema.String, Schema.Unknown);
 export type SourceControlHostSettings = typeof SourceControlHostSettings.Type;
@@ -1397,6 +1405,7 @@ export const ServerSettings = Schema.Struct({
   secretProviders: Schema.Record(SecretProviderId, SecretProviderConfig).pipe(
     Schema.withDecodingDefault(Effect.succeed({})),
   ),
+  providerProxy: ProviderProxySettings.pipe(Schema.withDecodingDefault(Effect.succeed({}))),
   cursorKeychainUsageEnabled: Schema.Boolean.pipe(
     Schema.withDecodingDefault(Effect.succeed(false)),
   ),
@@ -1715,6 +1724,14 @@ export const ServerSettingsPatch = Schema.Struct({
   secretProviders: Schema.optionalKey(
     Schema.Record(SecretProviderId, Schema.NullOr(SecretProviderConfigWrite)),
   ),
+  /** Redaction markers retain secrets; empty secrets remove them. */
+  providerProxy: Schema.optionalKey(
+    Schema.Struct({
+      url: Schema.optionalKey(TrimmedString),
+      apiKey: Schema.optionalKey(TrimmedString),
+      managementKey: Schema.optionalKey(TrimmedString),
+    }),
+  ),
   cursorKeychainUsageEnabled: Schema.optionalKey(Schema.Boolean),
 
   usagePriceOverrides: Schema.optionalKey(
@@ -1738,7 +1755,8 @@ export function requiredScopesForServerSettingsPatch(
       key === "providers" ||
       key === "providerInstances" ||
       key === "usageLimitSources" ||
-      key === "secretProviders"
+      key === "secretProviders" ||
+      key === "providerProxy"
     ) {
       changesProviders = true;
     } else {
diff --git a/packages/provider-core/package.json b/packages/provider-core/package.json
index ab93310316ac4..bdb3b8991de9d 100644
--- a/packages/provider-core/package.json
+++ b/packages/provider-core/package.json
@@ -127,6 +127,10 @@
       "types": "./src/server/ProviderLatestVersions.ts",
       "import": "./src/server/ProviderLatestVersions.ts"
     },
+    "./server/providerProxy": {
+      "types": "./src/server/providerProxy.ts",
+      "import": "./src/server/providerProxy.ts"
+    },
     "./server/randomUuid": {
       "types": "./src/server/randomUuid.ts",
       "import": "./src/server/randomUuid.ts"
diff --git a/packages/provider-core/src/server/driver.ts b/packages/provider-core/src/server/driver.ts
index d236a98fdcba2..343ff66f8353a 100644
--- a/packages/provider-core/src/server/driver.ts
+++ b/packages/provider-core/src/server/driver.ts
@@ -17,6 +17,7 @@ import type * as Scope from "effect/Scope";
 
 import type * as ProviderAdapter from "./ProviderAdapter.ts";
 import type { ProviderAuthController } from "./auth.ts";
+import type { ProviderProxyRoute } from "./providerProxy.ts";
 import type { ProviderDriverError } from "./errors.ts";
 import type { ManagedServerProvider } from "./snapshot.ts";
 import type { ProviderTextGeneration } from "./textGeneration.ts";
@@ -99,6 +100,8 @@ export interface ProviderDriverCreateInput<Config> {
   readonly environment: ProviderInstanceEnvironment;
   readonly enabled: boolean;
   readonly config: Config;
+  /** Set when the instance routes through the environment's proxy; only PROXY_ROUTED_DRIVERS receive it. */
+  readonly proxy?: ProviderProxyRoute | undefined;
 }
 
 /** create calls with different instanceId/config must share no mutable state. */
diff --git a/packages/provider-core/src/server/providerProxy.ts b/packages/provider-core/src/server/providerProxy.ts
new file mode 100644
index 0000000000000..b7c67cb602870
--- /dev/null
+++ b/packages/provider-core/src/server/providerProxy.ts
@@ -0,0 +1,19 @@
+/** A resolved CLIProxyAPI endpoint for one provider instance. Secrets are already filled in. */
+export interface ProviderProxyRoute {
+  /** Origin plus any base path, without a trailing slash or `/v1`. */
+  readonly url: string;
+  readonly apiKey: string;
+}
+
+/** Accepts the forms users paste: with or without a trailing slash or `/v1`. */
+export const normalizeProviderProxyUrl = (url: string): string =>
+  url.trim().replace(/\/+$/, "").replace(/\/v1$/, "");
+
+/** The OpenAI- and Anthropic-compatible API root. */
+export const providerProxyApiUrl = (route: ProviderProxyRoute): string => `${route.url}/v1`;
+
+export const PROXY_AUTH_METADATA = { type: "proxy", label: "Via proxy" } as const;
+
+// The harness never sees which pooled account served a request, so it cannot report limits.
+export const PROXY_LIMITS_MESSAGE =
+  "This instance uses the proxy's accounts. Add the proxy's management key to see them under Limits.";
diff --git a/packages/provider-opencode/src/server/OpenCodeRuntime.environment.test.ts b/packages/provider-opencode/src/server/OpenCodeRuntime.environment.test.ts
index 8e4663e416511..4be267d2655d6 100644
--- a/packages/provider-opencode/src/server/OpenCodeRuntime.environment.test.ts
+++ b/packages/provider-opencode/src/server/OpenCodeRuntime.environment.test.ts
@@ -5,6 +5,33 @@ import { describe, expect, it } from "vite-plus/test";
 
 import * as OpenCodeRuntime from "./OpenCodeRuntime.ts";
 
+describe("applyOpenCodeProxyEnvironment", () => {
+  it("points the built-in Anthropic and OpenAI providers at the proxy and keeps user config", () => {
+    const environment = OpenCodeRuntime.applyOpenCodeProxyEnvironment(
+      {
+        OPENCODE_CONFIG_CONTENT: JSON.stringify({
+          theme: "t3",
+          provider: {
+            anthropic: { options: { timeout: 60_000, apiKey: "sk-ant-direct" } },
+            openrouter: { options: { apiKey: "or" } },
+          },
+        }),
+      },
+      { url: "http://proxy:8317", apiKey: "" },
+    );
+
+    const proxied = { baseURL: "http://proxy:8317/v1", apiKey: "t3-proxy" };
+    expect(JSON.parse(environment.OPENCODE_CONFIG_CONTENT ?? "")).toEqual({
+      theme: "t3",
+      provider: {
+        anthropic: { options: { timeout: 60_000, ...proxied } },
+        openai: { options: proxied },
+        openrouter: { options: { apiKey: "or" } },
+      },
+    });
+  });
+});
+
 describe("resolveOpenCodeServerPassword", () => {
   it("uses the settings password when local settings and environment differ", () => {
     expect(
diff --git a/packages/provider-opencode/src/server/OpenCodeRuntime.ts b/packages/provider-opencode/src/server/OpenCodeRuntime.ts
index f18ab07bbe19f..45be3ff94e9ca 100644
--- a/packages/provider-opencode/src/server/OpenCodeRuntime.ts
+++ b/packages/provider-opencode/src/server/OpenCodeRuntime.ts
@@ -31,6 +31,10 @@ import * as ChildProcess from "effect/process/ChildProcess";
 import * as ChildProcessSpawner from "effect/process/ChildProcessSpawner";
 
 import { signalProcessGroup } from "@t3tools/provider-core/server/processGroup";
+import {
+  providerProxyApiUrl,
+  type ProviderProxyRoute,
+} from "@t3tools/provider-core/server/providerProxy";
 import { isWindowsCommandNotFound } from "@t3tools/provider-core/server/snapshotProbe";
 import * as OpenCodeServerLedger from "./OpenCodeServerLedger.ts";
 import { collectStreamAsString } from "@t3tools/provider-core/server/snapshotProbe";
@@ -62,6 +66,49 @@ function resolveOpenCodeConfigContent(
   );
 }
 
+const decodeOpenCodeConfigObject = Schema.decodeUnknownOption(
+  Schema.fromJsonString(Schema.Record(Schema.String, Schema.Unknown)),
+);
+const asRecord = (value: unknown): Readonly<Record<string, unknown>> =>
+  typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+
+/**
+ * Points OpenCode's built-in Anthropic and OpenAI providers at the proxy. Their model catalogs
+ * stay intact, and the user's own config content survives around the override.
+ */
+export function applyOpenCodeProxyEnvironment(
+  environment: NodeJS.ProcessEnv,
+  proxy: ProviderProxyRoute | undefined,
+): NodeJS.ProcessEnv {
+  if (proxy === undefined) return environment;
+  const base: Readonly<Record<string, unknown>> = Option.getOrElse(
+    decodeOpenCodeConfigObject(resolveOpenCodeConfigContent(environment, {})),
+    () => ({}),
+  );
+  const providers = asRecord(base.provider);
+  const routed = (id: string) => {
+    const provider = asRecord(providers[id]);
+    return {
+      ...provider,
+      options: {
+        ...asRecord(provider.options),
+        baseURL: providerProxyApiUrl(proxy),
+        // OpenCode treats a provider without a key as disconnected; a keyless proxy ignores it.
+        apiKey: proxy.apiKey === "" ? "t3-proxy" : proxy.apiKey,
+      },
+    };
+  };
+  const content = encodeUnknownJsonStringExit({
+    ...base,
+    provider: { ...providers, anthropic: routed("anthropic"), openai: routed("openai") },
+  });
+  return Exit.isSuccess(content)
+    ? { ...environment, OPENCODE_CONFIG_CONTENT: content.value }
+    : environment;
+}
+
 export function resolveOpenCodeServerPassword(
   input: {
     readonly external: boolean;
diff --git a/packages/provider-opencode/src/server/adapter.ts b/packages/provider-opencode/src/server/adapter.ts
index 7762c3b64503d..1d18ef6d02de6 100644
--- a/packages/provider-opencode/src/server/adapter.ts
+++ b/packages/provider-opencode/src/server/adapter.ts
@@ -3759,7 +3759,10 @@ export const OpenCodeAdapterV2Driver: ProviderAdapterDriver<
       return yield* makeOpenCodeAdapterV2({
         instanceId: input.instanceId,
         settings: { ...input.config, enabled: input.enabled },
-        environment: yield* mergeProviderInstanceEnvironment(input.environment, hostEnvironment),
+        environment: OpenCodeRuntime.applyOpenCodeProxyEnvironment(
+          yield* mergeProviderInstanceEnvironment(input.environment, hostEnvironment),
+          input.proxy,
+        ),
         ...(providerEventLoggers.native === undefined
           ? {}
           : { nativeEventLogger: providerEventLoggers.native }),
diff --git a/packages/provider-opencode/src/server/driver.ts b/packages/provider-opencode/src/server/driver.ts
index 713bc3f05ad27..6f1e27f0baf35 100644
--- a/packages/provider-opencode/src/server/driver.ts
+++ b/packages/provider-opencode/src/server/driver.ts
@@ -185,6 +185,7 @@ export const OpenCodeDriver: ProviderDriver<
     environment,
     enabled,
     config,
+    proxy,
   }) {
     const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
     const fileSystem = yield* FileSystem.FileSystem;
@@ -194,7 +195,18 @@ export const OpenCodeDriver: ProviderDriver<
     const latestVersions = yield* ProviderLatestVersions.ProviderLatestVersions;
     const crypto = yield* Crypto.Crypto;
     const host = yield* ProviderHost.ProviderHost;
-    const processEnv = yield* mergeProviderInstanceEnvironment(environment);
+    // An external server owns its own provider config, so the proxy cannot apply there.
+    if (proxy !== undefined && config.serverUrl.trim() !== "") {
+      return yield* new ProviderDriverError({
+        driver: DRIVER_KIND,
+        instanceId,
+        detail: "An external OpenCode server cannot route through this environment's proxy.",
+      });
+    }
+    const processEnv = OpenCodeRuntime.applyOpenCodeProxyEnvironment(
+      yield* mergeProviderInstanceEnvironment(environment),
+      proxy,
+    );
     const continuationIdentity = defaultProviderContinuationIdentity({
       driverKind: DRIVER_KIND,
       instanceId,
@@ -252,6 +264,7 @@ export const OpenCodeDriver: ProviderDriver<
       environment,
       enabled,
       config,
+      proxy,
     }).pipe(
       Effect.mapError(
         (cause) =>

From 37a7ca4f99e027b2c3a873f1b6a0fd6505e10676 Mon Sep 17 00:00:00 2001
From: saphid <saphid@users.noreply.github.com>
Date: Fri, 30 Oct 2026 14:26:15 +1100
Subject: [PATCH 02/26] fix(server): keyless proxies reach Claude and Codex;
 OpenCode plugins can't bypass the proxy

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../src/provider/Drivers/ClaudeHome.test.ts    |  5 +++++
 apps/server/src/provider/Drivers/ClaudeHome.ts |  7 +++++--
 .../src/provider/codexLaunchArgs.test.ts       | 18 ++++--------------
 apps/server/src/provider/codexLaunchArgs.ts    |  9 ++++++---
 docs/user/install.md                           |  3 ++-
 .../provider-core/src/server/providerProxy.ts  |  7 +++++++
 .../server/OpenCodeRuntime.environment.test.ts |  3 +++
 .../src/server/OpenCodeRuntime.ts              | 18 ++++++++++++------
 8 files changed, 44 insertions(+), 26 deletions(-)

diff --git a/apps/server/src/provider/Drivers/ClaudeHome.test.ts b/apps/server/src/provider/Drivers/ClaudeHome.test.ts
index b9c2e96e081e2..cf850d499122c 100644
--- a/apps/server/src/provider/Drivers/ClaudeHome.test.ts
+++ b/apps/server/src/provider/Drivers/ClaudeHome.test.ts
@@ -32,6 +32,11 @@ describe("applyClaudeProxyEnvironment", () => {
       ANTHROPIC_BASE_URL: "http://proxy:8317",
       ANTHROPIC_AUTH_TOKEN: "sk-proxy",
     });
+    // Claude Code reports "Not logged in" without contacting a proxy when no credential is set.
+    expect(
+      applyClaudeProxyEnvironment({}, { url: "http://proxy:8317", apiKey: "" })
+        .ANTHROPIC_AUTH_TOKEN,
+    ).toBe("t3-proxy");
   });
 });
 
diff --git a/apps/server/src/provider/Drivers/ClaudeHome.ts b/apps/server/src/provider/Drivers/ClaudeHome.ts
index 1c083f5e7174a..47f5506db6202 100644
--- a/apps/server/src/provider/Drivers/ClaudeHome.ts
+++ b/apps/server/src/provider/Drivers/ClaudeHome.ts
@@ -5,7 +5,10 @@ import * as Path from "effect/Path";
 import * as Schema from "effect/Schema";
 
 import { expandHomePath } from "@t3tools/provider-core/server/pathExpansion";
-import type { ProviderProxyRoute } from "@t3tools/provider-core/server/providerProxy";
+import {
+  providerProxyToken,
+  type ProviderProxyRoute,
+} from "@t3tools/provider-core/server/providerProxy";
 import * as HostProcess from "@t3tools/shared/HostProcess";
 
 const quotePath = Schema.encodeSync(Schema.fromJsonString(Schema.String));
@@ -59,7 +62,7 @@ export const applyClaudeProxyEnvironment = (
   const next: NodeJS.ProcessEnv = {
     ...environment,
     ANTHROPIC_BASE_URL: proxy.url,
-    ANTHROPIC_AUTH_TOKEN: proxy.apiKey,
+    ANTHROPIC_AUTH_TOKEN: providerProxyToken(proxy),
     // Empty, not removed: Claude Code otherwise falls back to a saved API key.
     ANTHROPIC_API_KEY: "",
   };
diff --git a/apps/server/src/provider/codexLaunchArgs.test.ts b/apps/server/src/provider/codexLaunchArgs.test.ts
index 55d793cc97727..cb62bceedfa72 100644
--- a/apps/server/src/provider/codexLaunchArgs.test.ts
+++ b/apps/server/src/provider/codexLaunchArgs.test.ts
@@ -33,8 +33,8 @@ describe("codexExecLaunchArgs", () => {
 });
 
 describe("applyCodexProxyRuntime", () => {
-  const proxyProvider = (keyField: string) =>
-    `model_providers.t3_proxy={name="T3 proxy",base_url="http://proxy:8317/v1",${keyField}wire_api="responses",requires_openai_auth=false,supports_websockets=false}`;
+  const proxyProvider =
+    'model_providers.t3_proxy={name="T3 proxy",base_url="http://proxy:8317/v1",env_key="T3_PROXY_KEY",wire_api="responses",requires_openai_auth=false,supports_websockets=false}';
 
   it("adds the proxy provider after env launch args and keeps the key out of argv", () => {
     const { config, environment } = applyCodexProxyRuntime(
@@ -49,22 +49,12 @@ describe("applyCodexProxyRuntime", () => {
       "-c",
       'model_provider="t3_proxy"',
       "-c",
-      proxyProvider('env_key="T3_PROXY_KEY",'),
+      proxyProvider,
     ]);
     NodeAssert.deepStrictEqual(codexExecLaunchArgs(config.launchArgs).slice(-2), [
       "-c",
-      proxyProvider('env_key="T3_PROXY_KEY",'),
+      proxyProvider,
     ]);
     NodeAssert.deepStrictEqual(environment, { PATH: "/bin", T3_PROXY_KEY: "sk-proxy" });
   });
-
-  it("sends no key to a proxy that has none", () => {
-    const { config } = applyCodexProxyRuntime(
-      { launchArgs: "" },
-      {},
-      { url: "http://proxy:8317", apiKey: "" },
-    );
-
-    NodeAssert.deepStrictEqual(codexAppServerArgs(config.launchArgs).at(-1), proxyProvider(""));
-  });
 });
diff --git a/apps/server/src/provider/codexLaunchArgs.ts b/apps/server/src/provider/codexLaunchArgs.ts
index cc67972341b5d..7a182197bef18 100644
--- a/apps/server/src/provider/codexLaunchArgs.ts
+++ b/apps/server/src/provider/codexLaunchArgs.ts
@@ -1,5 +1,6 @@
 import {
   providerProxyApiUrl,
+  providerProxyToken,
   type ProviderProxyRoute,
 } from "@t3tools/provider-core/server/providerProxy";
 import { tokenizeCliArgs } from "@t3tools/shared/cliArgs";
@@ -22,15 +23,17 @@ export const applyCodexProxyRuntime = <Config extends { readonly launchArgs: str
   proxy: ProviderProxyRoute | undefined,
 ): { readonly config: Config; readonly environment: NodeJS.ProcessEnv } => {
   if (proxy === undefined) return { config, environment };
-  const keyField = proxy.apiKey === "" ? "" : `env_key="${CODEX_PROXY_KEY_ENV}",`;
   const proxyArgs = [
     `model_provider="${CODEX_PROXY_MODEL_PROVIDER}"`,
-    `model_providers.${CODEX_PROXY_MODEL_PROVIDER}={name="T3 proxy",base_url=${JSON.stringify(providerProxyApiUrl(proxy))},${keyField}wire_api="responses",requires_openai_auth=false,supports_websockets=false}`,
+    `model_providers.${CODEX_PROXY_MODEL_PROVIDER}={name="T3 proxy",base_url=${JSON.stringify(providerProxyApiUrl(proxy))},env_key="${CODEX_PROXY_KEY_ENV}",wire_api="responses",requires_openai_auth=false,supports_websockets=false}`,
   ]
     .map((value) => `-c ${JSON.stringify(value)}`)
     .join(" ");
   const launchArgs = resolveCodexLaunchArgs(config.launchArgs, environment);
-  const next: NodeJS.ProcessEnv = { ...environment, [CODEX_PROXY_KEY_ENV]: proxy.apiKey };
+  const next: NodeJS.ProcessEnv = {
+    ...environment,
+    [CODEX_PROXY_KEY_ENV]: providerProxyToken(proxy),
+  };
   // Folded into launchArgs above; left in place it would replace the proxy arguments.
   delete next[T3CODE_CODEX_LAUNCH_ARGS_ENV];
   return {
diff --git a/docs/user/install.md b/docs/user/install.md
index 28558e1ea73d4..bca71e5fc0eeb 100644
--- a/docs/user/install.md
+++ b/docs/user/install.md
@@ -205,7 +205,8 @@ Then turn on **Use proxy** for each Claude, Codex, or OpenCode provider that sho
 A provider with **Use proxy** on never falls back to its own login. If the proxy is removed, the
 provider shows as unavailable until you add a proxy again or turn the switch off. Codex threads
 started through the proxy need it to continue. T3-managed ChatGPT sign-in and external OpenCode
-servers cannot use a proxy.
+servers cannot use a proxy. While OpenCode uses the proxy, it runs without its plugins, because
+plugin logins such as ChatGPT would send requests around the proxy.
 
 For provider-specific setup and accounts, see [Codex](./providers-codex.md),
 [Claude](./providers-claude.md), [OpenCode](./providers-opencode.md),
diff --git a/packages/provider-core/src/server/providerProxy.ts b/packages/provider-core/src/server/providerProxy.ts
index b7c67cb602870..bdd05e4c54376 100644
--- a/packages/provider-core/src/server/providerProxy.ts
+++ b/packages/provider-core/src/server/providerProxy.ts
@@ -9,6 +9,13 @@ export interface ProviderProxyRoute {
 export const normalizeProviderProxyUrl = (url: string): string =>
   url.trim().replace(/\/+$/, "").replace(/\/v1$/, "");
 
+// Harnesses refuse to send requests without a credential; a proxy with no API keys ignores it.
+const KEYLESS_PROXY_TOKEN = "t3-proxy";
+
+/** The credential to send: the proxy's key, or a placeholder for a keyless proxy. */
+export const providerProxyToken = (route: ProviderProxyRoute): string =>
+  route.apiKey === "" ? KEYLESS_PROXY_TOKEN : route.apiKey;
+
 /** The OpenAI- and Anthropic-compatible API root. */
 export const providerProxyApiUrl = (route: ProviderProxyRoute): string => `${route.url}/v1`;
 
diff --git a/packages/provider-opencode/src/server/OpenCodeRuntime.environment.test.ts b/packages/provider-opencode/src/server/OpenCodeRuntime.environment.test.ts
index 4be267d2655d6..3284c088045b5 100644
--- a/packages/provider-opencode/src/server/OpenCodeRuntime.environment.test.ts
+++ b/packages/provider-opencode/src/server/OpenCodeRuntime.environment.test.ts
@@ -21,6 +21,9 @@ describe("applyOpenCodeProxyEnvironment", () => {
     );
 
     const proxied = { baseURL: "http://proxy:8317/v1", apiKey: "t3-proxy" };
+    // Plugins such as Codex's ChatGPT login replace fetch and would bypass the proxy.
+    expect(environment.OPENCODE_DISABLE_DEFAULT_PLUGINS).toBe("1");
+    expect(environment.OPENCODE_PURE).toBe("1");
     expect(JSON.parse(environment.OPENCODE_CONFIG_CONTENT ?? "")).toEqual({
       theme: "t3",
       provider: {
diff --git a/packages/provider-opencode/src/server/OpenCodeRuntime.ts b/packages/provider-opencode/src/server/OpenCodeRuntime.ts
index 45be3ff94e9ca..35faf95f2d2bd 100644
--- a/packages/provider-opencode/src/server/OpenCodeRuntime.ts
+++ b/packages/provider-opencode/src/server/OpenCodeRuntime.ts
@@ -33,6 +33,7 @@ import * as ChildProcessSpawner from "effect/process/ChildProcessSpawner";
 import { signalProcessGroup } from "@t3tools/provider-core/server/processGroup";
 import {
   providerProxyApiUrl,
+  providerProxyToken,
   type ProviderProxyRoute,
 } from "@t3tools/provider-core/server/providerProxy";
 import { isWindowsCommandNotFound } from "@t3tools/provider-core/server/snapshotProbe";
@@ -44,6 +45,7 @@ import * as HostProcess from "@t3tools/shared/HostProcess";
 import { compareSemverVersions, parseSemver } from "@t3tools/shared/semver";
 import { resolveSpawnCommand } from "@t3tools/shared/shell";
 const encodeUnknownJsonStringExit = Schema.encodeUnknownExit(Schema.fromJsonString(Schema.Unknown));
+const encodeUnknownJsonString = Schema.encodeUnknownSync(Schema.fromJsonString(Schema.Unknown));
 const OPENCODE_EMPTY_CONFIG_CONTENT = "{}";
 
 export const MINIMUM_OPENCODE_VERSION = "1.14.19";
@@ -95,18 +97,22 @@ export function applyOpenCodeProxyEnvironment(
       options: {
         ...asRecord(provider.options),
         baseURL: providerProxyApiUrl(proxy),
-        // OpenCode treats a provider without a key as disconnected; a keyless proxy ignores it.
-        apiKey: proxy.apiKey === "" ? "t3-proxy" : proxy.apiKey,
+        apiKey: providerProxyToken(proxy),
       },
     };
   };
-  const content = encodeUnknownJsonStringExit({
+  const content = encodeUnknownJsonString({
     ...base,
     provider: { ...providers, anthropic: routed("anthropic"), openai: routed("openai") },
   });
-  return Exit.isSuccess(content)
-    ? { ...environment, OPENCODE_CONFIG_CONTENT: content.value }
-    : environment;
+  // A stored ChatGPT login attaches the built-in Codex plugin, whose fetch rewrites requests to
+  // chatgpt.com after any config override; user plugins such as Claude OAuth do the same.
+  return {
+    ...environment,
+    OPENCODE_CONFIG_CONTENT: content,
+    OPENCODE_DISABLE_DEFAULT_PLUGINS: "1",
+    OPENCODE_PURE: "1",
+  };
 }
 
 export function resolveOpenCodeServerPassword(

From d6ba85f6e889ee7a964f3a9fc588eb3bee548cd8 Mon Sep 17 00:00:00 2001
From: saphid <saphid@users.noreply.github.com>
Date: Fri, 30 Oct 2026 14:30:37 +1100
Subject: [PATCH 03/26] fix(opencode): proxied servers older than 1.14.49
 refuse to start

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/user/install.md                              |  3 ++-
 .../server/OpenCodeRuntime.environment.test.ts    | 15 +++++++++++++++
 .../src/server/OpenCodeRuntime.ts                 | 15 +++++++++++++--
 3 files changed, 30 insertions(+), 3 deletions(-)

diff --git a/docs/user/install.md b/docs/user/install.md
index bca71e5fc0eeb..dbfa73f05f934 100644
--- a/docs/user/install.md
+++ b/docs/user/install.md
@@ -206,7 +206,8 @@ A provider with **Use proxy** on never falls back to its own login. If the proxy
 provider shows as unavailable until you add a proxy again or turn the switch off. Codex threads
 started through the proxy need it to continue. T3-managed ChatGPT sign-in and external OpenCode
 servers cannot use a proxy. While OpenCode uses the proxy, it runs without its plugins, because
-plugin logins such as ChatGPT would send requests around the proxy.
+plugin logins such as ChatGPT would send requests around the proxy. This needs OpenCode 1.14.49 or
+newer.
 
 For provider-specific setup and accounts, see [Codex](./providers-codex.md),
 [Claude](./providers-claude.md), [OpenCode](./providers-opencode.md),
diff --git a/packages/provider-opencode/src/server/OpenCodeRuntime.environment.test.ts b/packages/provider-opencode/src/server/OpenCodeRuntime.environment.test.ts
index 3284c088045b5..11cddf0665fe5 100644
--- a/packages/provider-opencode/src/server/OpenCodeRuntime.environment.test.ts
+++ b/packages/provider-opencode/src/server/OpenCodeRuntime.environment.test.ts
@@ -79,4 +79,19 @@ describe("verifyOpenCodeServerVersion", () => {
       expect(error.detail).toContain("v1.14.18 is too old");
     }),
   );
+
+  effectIt.effect("rejects a proxied server that cannot suppress its built-in plugins", () =>
+    Effect.gen(function* () {
+      const proxied = OpenCodeRuntime.applyOpenCodeProxyEnvironment(
+        {},
+        { url: "http://proxy:8317", apiKey: "sk" },
+      );
+      const error = yield* OpenCodeRuntime.verifyOpenCodeServerVersion(
+        makeHealthClient(() => Promise.resolve({ data: { healthy: true, version: "1.14.48" } })),
+        OpenCodeRuntime.minimumOpenCodeVersionFor(proxied),
+      ).pipe(Effect.flip);
+      expect(error.detail).toBe("OpenCode v1.14.48 is too old. Upgrade to v1.14.49 or newer.");
+      expect(OpenCodeRuntime.minimumOpenCodeVersionFor({})).toBe("1.14.19");
+    }),
+  );
 });
diff --git a/packages/provider-opencode/src/server/OpenCodeRuntime.ts b/packages/provider-opencode/src/server/OpenCodeRuntime.ts
index 35faf95f2d2bd..b7290018617bf 100644
--- a/packages/provider-opencode/src/server/OpenCodeRuntime.ts
+++ b/packages/provider-opencode/src/server/OpenCodeRuntime.ts
@@ -49,6 +49,15 @@ const encodeUnknownJsonString = Schema.encodeUnknownSync(Schema.fromJsonString(S
 const OPENCODE_EMPTY_CONFIG_CONTENT = "{}";
 
 export const MINIMUM_OPENCODE_VERSION = "1.14.19";
+// Older servers load built-in plugins despite OPENCODE_DISABLE_DEFAULT_PLUGINS, and a stored ChatGPT
+// login's plugin would send requests around the proxy.
+const MINIMUM_PROXIED_OPENCODE_VERSION = "1.14.49";
+
+/** The oldest server a spawn may accept, given its environment. */
+export const minimumOpenCodeVersionFor = (environment: NodeJS.ProcessEnv | undefined): string =>
+  environment?.OPENCODE_DISABLE_DEFAULT_PLUGINS === "1"
+    ? MINIMUM_PROXIED_OPENCODE_VERSION
+    : MINIMUM_OPENCODE_VERSION;
 const OPENCODE_HEALTH_TIMEOUT = "5 seconds";
 
 const OpenCodeHealthSchema = Schema.Struct({
@@ -212,6 +221,7 @@ export const runOpenCodeSdk = <A>(
 
 export const verifyOpenCodeServerVersion = Effect.fn("verifyOpenCodeServerVersion")(function* (
   client: OpencodeClient,
+  minimumVersion: string = MINIMUM_OPENCODE_VERSION,
 ) {
   const healthOption = yield* runOpenCodeSdk("global.health", (signal) =>
     client.global.health({ signal }),
@@ -239,10 +249,10 @@ export const verifyOpenCodeServerVersion = Effect.fn("verifyOpenCodeServerVersio
       detail: `OpenCode server returned an invalid version. T3 Code requires OpenCode v${MINIMUM_OPENCODE_VERSION} or newer.`,
     });
   }
-  if (compareSemverVersions(health.version, MINIMUM_OPENCODE_VERSION) < 0) {
+  if (compareSemverVersions(health.version, minimumVersion) < 0) {
     return yield* new OpenCodeRuntimeError({
       operation: "global.health",
-      detail: `OpenCode v${health.version} is too old. Upgrade to v${MINIMUM_OPENCODE_VERSION} or newer.`,
+      detail: `OpenCode v${health.version} is too old. Upgrade to v${minimumVersion} or newer.`,
     });
   }
   return health.version;
@@ -738,6 +748,7 @@ const makeOpenCodeRuntime = Effect.gen(function* () {
             directory: input.directory,
             ...(serverPassword !== undefined ? { serverPassword } : {}),
           }),
+          minimumOpenCodeVersionFor(input.environment),
         )
     );
 

From fe561e30bcbaa15513b79fefb9974e28fd0e3f74 Mon Sep 17 00:00:00 2001
From: saphid <saphid@users.noreply.github.com>
Date: Fri, 30 Oct 2026 14:51:46 +1100
Subject: [PATCH 04/26] fix: address review on proxy routing

- a hand-written provider-proxy usage source keeps its id
- proxied OpenCode skips Go limits, offers only routed providers, and refuses JSONC config
- each proxy key can be cleared on its own

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../src/usage/UsageLimitSources.test.ts       | 19 ++++--
 apps/server/src/usage/UsageLimitSources.ts    |  5 +-
 .../settings/ProviderProxySettings.tsx        | 63 +++++++++++++------
 docs/user/install.md                          |  7 ++-
 .../OpenCodeRuntime.environment.test.ts       |  6 ++
 .../src/server/OpenCodeRuntime.ts             |  6 ++
 .../provider-opencode/src/server/driver.ts    | 16 +++--
 .../src/server/usageLimits.ts                 |  9 +++
 8 files changed, 100 insertions(+), 31 deletions(-)

diff --git a/apps/server/src/usage/UsageLimitSources.test.ts b/apps/server/src/usage/UsageLimitSources.test.ts
index 56ca34f8e5d16..6b3ecc533f1a5 100644
--- a/apps/server/src/usage/UsageLimitSources.test.ts
+++ b/apps/server/src/usage/UsageLimitSources.test.ts
@@ -88,7 +88,7 @@ it.effect("keeps malformed source URLs encodable for config subscribers", () =>
   ),
 );
 
-it("reports the routing proxy's accounts unless a hub already points at it", () => {
+it("reports the routing proxy's accounts unless a hub already points at it or owns its id", () => {
   const hub = {
     kind: "cliproxy" as const,
     url: "http://proxy:8317/",
@@ -109,8 +109,17 @@ it("reports the routing proxy's accounts unless a hub already points at it", ()
       enabled: true,
     },
   });
-  const listed = { [UsageLimitSourceId.make("hub")]: hub };
-  expect(
-    UsageLimitSources.effectiveUsageLimitSources({ ...settings, usageLimitSources: listed }),
-  ).toBe(listed);
+  for (const listed of [
+    { [UsageLimitSourceId.make("hub")]: hub },
+    {
+      [UsageLimitSources.PROVIDER_PROXY_SOURCE_ID]: {
+        ...hub,
+        url: "https://other.example.test",
+      },
+    },
+  ]) {
+    expect(
+      UsageLimitSources.effectiveUsageLimitSources({ ...settings, usageLimitSources: listed }),
+    ).toBe(listed);
+  }
 });
diff --git a/apps/server/src/usage/UsageLimitSources.ts b/apps/server/src/usage/UsageLimitSources.ts
index dc8d1853f3dc0..4be81853c08b6 100644
--- a/apps/server/src/usage/UsageLimitSources.ts
+++ b/apps/server/src/usage/UsageLimitSources.ts
@@ -59,7 +59,10 @@ export function effectiveUsageLimitSources(
   const alreadyListed = Object.values(settings.usageLimitSources).some(
     (source) => normalizeProviderProxyUrl(source.url) === url,
   );
-  if (alreadyListed) return settings.usageLimitSources;
+  // A hand-written source may already use the synthetic id; it keeps the slot.
+  if (alreadyListed || PROVIDER_PROXY_SOURCE_ID in settings.usageLimitSources) {
+    return settings.usageLimitSources;
+  }
   return {
     ...settings.usageLimitSources,
     [PROVIDER_PROXY_SOURCE_ID]: {
diff --git a/apps/web/src/components/settings/ProviderProxySettings.tsx b/apps/web/src/components/settings/ProviderProxySettings.tsx
index e413ed6a1a6f9..227a8366ad434 100644
--- a/apps/web/src/components/settings/ProviderProxySettings.tsx
+++ b/apps/web/src/components/settings/ProviderProxySettings.tsx
@@ -1,4 +1,5 @@
 import type { EnvironmentId, UnifiedSettings } from "@t3tools/contracts";
+import { XIcon } from "lucide-react";
 
 import { useUpdateEnvironmentSettings } from "../../hooks/useSettings";
 import { Button } from "../ui/button";
@@ -61,15 +62,28 @@ export function ProviderProxySettings({
         title={<label htmlFor="provider-proxy-api-key-input">API key</label>}
         description="One of the proxy's API keys. Leave empty if the proxy has none."
         control={
-          <SecretInput
-            id="provider-proxy-api-key-input"
-            size="sm"
-            className={CONTROL_CLASS}
-            value=""
-            configured={proxy.apiKey !== ""}
-            disabled={readOnly}
-            onCommit={(apiKey) => update({ apiKey: apiKey.trim() })}
-          />
+          <div className="flex w-full min-w-0 items-center gap-2 @min-[32rem]/settings-row:w-56">
+            <SecretInput
+              id="provider-proxy-api-key-input"
+              size="sm"
+              className="min-w-0 flex-1"
+              value=""
+              configured={proxy.apiKey !== ""}
+              disabled={readOnly}
+              onCommit={(apiKey) => update({ apiKey: apiKey.trim() })}
+            />
+            {proxy.apiKey !== "" && !readOnly ? (
+              <Button
+                type="button"
+                size="icon-sm"
+                variant="ghost-destructive"
+                onClick={() => update({ apiKey: "" })}
+                aria-label="Clear API key"
+              >
+                <XIcon className="size-3.5" />
+              </Button>
+            ) : null}
+          </div>
         }
       />
       <SettingsRow
@@ -77,15 +91,28 @@ export function ProviderProxySettings({
         title={<label htmlFor="provider-proxy-management-key-input">Management key</label>}
         description="Optional. Shows the proxy's accounts under Usage → Limits."
         control={
-          <SecretInput
-            id="provider-proxy-management-key-input"
-            size="sm"
-            className={CONTROL_CLASS}
-            value=""
-            configured={proxy.managementKey !== ""}
-            disabled={readOnly}
-            onCommit={(managementKey) => update({ managementKey: managementKey.trim() })}
-          />
+          <div className="flex w-full min-w-0 items-center gap-2 @min-[32rem]/settings-row:w-56">
+            <SecretInput
+              id="provider-proxy-management-key-input"
+              size="sm"
+              className="min-w-0 flex-1"
+              value=""
+              configured={proxy.managementKey !== ""}
+              disabled={readOnly}
+              onCommit={(managementKey) => update({ managementKey: managementKey.trim() })}
+            />
+            {proxy.managementKey !== "" && !readOnly ? (
+              <Button
+                type="button"
+                size="icon-sm"
+                variant="ghost-destructive"
+                onClick={() => update({ managementKey: "" })}
+                aria-label="Clear management key"
+              >
+                <XIcon className="size-3.5" />
+              </Button>
+            ) : null}
+          </div>
         }
       />
     </SettingsSection>
diff --git a/docs/user/install.md b/docs/user/install.md
index dbfa73f05f934..1fc11bbc20ae1 100644
--- a/docs/user/install.md
+++ b/docs/user/install.md
@@ -205,9 +205,10 @@ Then turn on **Use proxy** for each Claude, Codex, or OpenCode provider that sho
 A provider with **Use proxy** on never falls back to its own login. If the proxy is removed, the
 provider shows as unavailable until you add a proxy again or turn the switch off. Codex threads
 started through the proxy need it to continue. T3-managed ChatGPT sign-in and external OpenCode
-servers cannot use a proxy. While OpenCode uses the proxy, it runs without its plugins, because
-plugin logins such as ChatGPT would send requests around the proxy. This needs OpenCode 1.14.49 or
-newer.
+servers cannot use a proxy. While OpenCode uses the proxy, it offers only Anthropic and OpenAI
+models and runs without its plugins, because other providers and plugin logins such as ChatGPT
+would send requests around the proxy. This needs OpenCode 1.14.49 or newer, and any
+`OPENCODE_CONFIG_CONTENT` must be plain JSON.
 
 For provider-specific setup and accounts, see [Codex](./providers-codex.md),
 [Claude](./providers-claude.md), [OpenCode](./providers-opencode.md),
diff --git a/packages/provider-opencode/src/server/OpenCodeRuntime.environment.test.ts b/packages/provider-opencode/src/server/OpenCodeRuntime.environment.test.ts
index 11cddf0665fe5..f4cef9192d0a5 100644
--- a/packages/provider-opencode/src/server/OpenCodeRuntime.environment.test.ts
+++ b/packages/provider-opencode/src/server/OpenCodeRuntime.environment.test.ts
@@ -24,8 +24,14 @@ describe("applyOpenCodeProxyEnvironment", () => {
     // Plugins such as Codex's ChatGPT login replace fetch and would bypass the proxy.
     expect(environment.OPENCODE_DISABLE_DEFAULT_PLUGINS).toBe("1");
     expect(environment.OPENCODE_PURE).toBe("1");
+    expect(
+      OpenCodeRuntime.isPlainJsonOpenCodeConfig({
+        OPENCODE_CONFIG_CONTENT: '{ "theme": "t3", // comment\n }',
+      }),
+    ).toBe(false);
     expect(JSON.parse(environment.OPENCODE_CONFIG_CONTENT ?? "")).toEqual({
       theme: "t3",
+      enabled_providers: ["anthropic", "openai"],
       provider: {
         anthropic: { options: { timeout: 60_000, ...proxied } },
         openai: { options: proxied },
diff --git a/packages/provider-opencode/src/server/OpenCodeRuntime.ts b/packages/provider-opencode/src/server/OpenCodeRuntime.ts
index b7290018617bf..ca05329159ee1 100644
--- a/packages/provider-opencode/src/server/OpenCodeRuntime.ts
+++ b/packages/provider-opencode/src/server/OpenCodeRuntime.ts
@@ -85,6 +85,10 @@ const asRecord = (value: unknown): Readonly<Record<string, unknown>> =>
     ? (value as Record<string, unknown>)
     : {};
 
+/** OpenCode accepts JSONC here, but the proxy override can only merge into plain JSON. */
+export const isPlainJsonOpenCodeConfig = (environment: NodeJS.ProcessEnv): boolean =>
+  Option.isSome(decodeOpenCodeConfigObject(resolveOpenCodeConfigContent(environment, {})));
+
 /**
  * Points OpenCode's built-in Anthropic and OpenAI providers at the proxy. Their model catalogs
  * stay intact, and the user's own config content survives around the override.
@@ -112,6 +116,8 @@ export function applyOpenCodeProxyEnvironment(
   };
   const content = encodeUnknownJsonString({
     ...base,
+    // Any other configured provider would send turns, and spend, around the proxy.
+    enabled_providers: ["anthropic", "openai"],
     provider: { ...providers, anthropic: routed("anthropic"), openai: routed("openai") },
   });
   // A stored ChatGPT login attaches the built-in Codex plugin, whose fetch rewrites requests to
diff --git a/packages/provider-opencode/src/server/driver.ts b/packages/provider-opencode/src/server/driver.ts
index 6f1e27f0baf35..dbaf3079c22fd 100644
--- a/packages/provider-opencode/src/server/driver.ts
+++ b/packages/provider-opencode/src/server/driver.ts
@@ -203,10 +203,17 @@ export const OpenCodeDriver: ProviderDriver<
         detail: "An external OpenCode server cannot route through this environment's proxy.",
       });
     }
-    const processEnv = OpenCodeRuntime.applyOpenCodeProxyEnvironment(
-      yield* mergeProviderInstanceEnvironment(environment),
-      proxy,
-    );
+    const mergedEnv = yield* mergeProviderInstanceEnvironment(environment);
+    // Dropping undecodable content would silently discard the user's agents and MCP servers.
+    if (proxy !== undefined && !OpenCodeRuntime.isPlainJsonOpenCodeConfig(mergedEnv)) {
+      return yield* new ProviderDriverError({
+        driver: DRIVER_KIND,
+        instanceId,
+        detail:
+          "OPENCODE_CONFIG_CONTENT must be plain JSON, without comments or trailing commas, to use the proxy.",
+      });
+    }
+    const processEnv = OpenCodeRuntime.applyOpenCodeProxyEnvironment(mergedEnv, proxy);
     const continuationIdentity = defaultProviderContinuationIdentity({
       driverKind: DRIVER_KIND,
       instanceId,
@@ -363,6 +370,7 @@ export const OpenCodeDriver: ProviderDriver<
           enabled: effectiveConfig.enabled,
           serverUrl: effectiveConfig.serverUrl,
           environment: processEnv,
+          proxied: proxy !== undefined,
         }),
       },
       { concurrency: "unbounded" },
diff --git a/packages/provider-opencode/src/server/usageLimits.ts b/packages/provider-opencode/src/server/usageLimits.ts
index b3df6b9cd0767..9301b82f015ac 100644
--- a/packages/provider-opencode/src/server/usageLimits.ts
+++ b/packages/provider-opencode/src/server/usageLimits.ts
@@ -18,6 +18,7 @@ import {
   makeUnavailableUsageLimits,
   makeUsageLimits,
 } from "@t3tools/provider-core/server/usageLimits";
+import { PROXY_LIMITS_MESSAGE } from "@t3tools/provider-core/server/providerProxy";
 import * as HostProcess from "@t3tools/shared/HostProcess";
 
 const AuthFile = Schema.Struct({ "opencode-go": Schema.optionalKey(Schema.Unknown) });
@@ -76,8 +77,16 @@ export const readOpenCodeGoUsageLimits = Effect.fn("readOpenCodeGoUsageLimits")(
   readonly enabled: boolean;
   readonly serverUrl: string;
   readonly environment: NodeJS.ProcessEnv;
+  readonly proxied?: boolean;
 }) {
   const checkedAt = DateTime.formatIso(yield* DateTime.now);
+  if (input.proxied) {
+    return makeUnavailableUsageLimits({
+      checkedAt,
+      reason: "unsupported",
+      message: PROXY_LIMITS_MESSAGE,
+    });
+  }
   const unsupported = makeUnavailableUsageLimits({ checkedAt, reason: "unsupported" });
   if (!input.enabled || input.serverUrl.trim()) return unsupported;
 

From 2d5daf1b4d4eaccda33488013e91561c6157480b Mon Sep 17 00:00:00 2001
From: saphid <saphid@users.noreply.github.com>
Date: Fri, 30 Oct 2026 14:59:23 +1100
Subject: [PATCH 05/26] fix(opencode): a proxied server refuses org or managed
 configs that redirect routed providers

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 docs/user/install.md                          |  3 +-
 .../OpenCodeRuntime.environment.test.ts       | 27 ++++++++++++
 .../src/server/OpenCodeRuntime.ts             | 42 +++++++++++++++++++
 3 files changed, 71 insertions(+), 1 deletion(-)

diff --git a/docs/user/install.md b/docs/user/install.md
index 1fc11bbc20ae1..771cc8ab9dc94 100644
--- a/docs/user/install.md
+++ b/docs/user/install.md
@@ -208,7 +208,8 @@ started through the proxy need it to continue. T3-managed ChatGPT sign-in and ex
 servers cannot use a proxy. While OpenCode uses the proxy, it offers only Anthropic and OpenAI
 models and runs without its plugins, because other providers and plugin logins such as ChatGPT
 would send requests around the proxy. This needs OpenCode 1.14.49 or newer, and any
-`OPENCODE_CONFIG_CONTENT` must be plain JSON.
+`OPENCODE_CONFIG_CONTENT` must be plain JSON. An OpenCode organization or managed config that
+points Anthropic or OpenAI elsewhere makes the provider unavailable.
 
 For provider-specific setup and accounts, see [Codex](./providers-codex.md),
 [Claude](./providers-claude.md), [OpenCode](./providers-opencode.md),
diff --git a/packages/provider-opencode/src/server/OpenCodeRuntime.environment.test.ts b/packages/provider-opencode/src/server/OpenCodeRuntime.environment.test.ts
index f4cef9192d0a5..745935efbc91c 100644
--- a/packages/provider-opencode/src/server/OpenCodeRuntime.environment.test.ts
+++ b/packages/provider-opencode/src/server/OpenCodeRuntime.environment.test.ts
@@ -41,6 +41,33 @@ describe("applyOpenCodeProxyEnvironment", () => {
   });
 });
 
+describe("verifyOpenCodeProxyRouting", () => {
+  effectIt.effect("rejects a proxied server whose later config redirects a routed provider", () =>
+    Effect.gen(function* () {
+      const environment = OpenCodeRuntime.applyOpenCodeProxyEnvironment(
+        {},
+        { url: "http://proxy:8317", apiKey: "sk" },
+      );
+      const requested = JSON.parse(environment.OPENCODE_CONFIG_CONTENT ?? "{}");
+      const clientWith = (config: unknown) =>
+        ({ config: { get: () => Promise.resolve({ data: config }) } }) as unknown as OpencodeClient;
+
+      yield* OpenCodeRuntime.verifyOpenCodeProxyRouting(clientWith(requested), environment);
+      const error = yield* OpenCodeRuntime.verifyOpenCodeProxyRouting(
+        clientWith({
+          ...requested,
+          provider: {
+            ...requested.provider,
+            openai: { options: { baseURL: "https://org-gateway.example.test/v1" } },
+          },
+        }),
+        environment,
+      ).pipe(Effect.flip);
+      expect(error.detail).toContain("openai provider points somewhere other than the proxy");
+    }),
+  );
+});
+
 describe("resolveOpenCodeServerPassword", () => {
   it("uses the settings password when local settings and environment differ", () => {
     expect(
diff --git a/packages/provider-opencode/src/server/OpenCodeRuntime.ts b/packages/provider-opencode/src/server/OpenCodeRuntime.ts
index ca05329159ee1..50c9f39ec0363 100644
--- a/packages/provider-opencode/src/server/OpenCodeRuntime.ts
+++ b/packages/provider-opencode/src/server/OpenCodeRuntime.ts
@@ -264,6 +264,37 @@ export const verifyOpenCodeServerVersion = Effect.fn("verifyOpenCodeServerVersio
   return health.version;
 });
 
+const PROXY_ROUTED_OPENCODE_PROVIDERS = ["anthropic", "openai"] as const;
+
+const providerBaseUrl = (config: unknown, providerId: string): unknown =>
+  asRecord(asRecord(asRecord(asRecord(config).provider)[providerId]).options).baseURL;
+
+/**
+ * Organization and managed configs merge after OPENCODE_CONFIG_CONTENT and can point a routed
+ * provider elsewhere, so a proxied server must prove its effective endpoints before use.
+ */
+export const verifyOpenCodeProxyRouting = Effect.fn("verifyOpenCodeProxyRouting")(function* (
+  client: OpencodeClient,
+  environment: NodeJS.ProcessEnv | undefined,
+) {
+  if (environment?.OPENCODE_DISABLE_DEFAULT_PLUGINS !== "1") return;
+  const requested = Option.getOrElse(
+    decodeOpenCodeConfigObject(resolveOpenCodeConfigContent(environment, {})),
+    () => ({}),
+  );
+  const effective = yield* runOpenCodeSdk("config.get", (signal) =>
+    client.config.get(undefined, { signal }),
+  );
+  for (const providerId of PROXY_ROUTED_OPENCODE_PROVIDERS) {
+    if (providerBaseUrl(effective.data, providerId) !== providerBaseUrl(requested, providerId)) {
+      return yield* new OpenCodeRuntimeError({
+        operation: "config.get",
+        detail: `OpenCode's ${providerId} provider points somewhere other than the proxy, likely from an organization or managed config. Remove that override or turn off Use proxy.`,
+      });
+    }
+  }
+});
+
 export interface OpenCodeCommandResult {
   readonly stdout: string;
   readonly stderr: string;
@@ -755,6 +786,17 @@ const makeOpenCodeRuntime = Effect.gen(function* () {
             ...(serverPassword !== undefined ? { serverPassword } : {}),
           }),
           minimumOpenCodeVersionFor(input.environment),
+        ).pipe(
+          Effect.tap(() =>
+            verifyOpenCodeProxyRouting(
+              createOpenCodeSdkClient({
+                baseUrl: url,
+                directory: input.directory,
+                ...(serverPassword !== undefined ? { serverPassword } : {}),
+              }),
+              input.environment,
+            ),
+          ),
         )
     );
 

From 6ed782b4cfa6db2ab84537118575bd9f349c5d08 Mon Sep 17 00:00:00 2001
From: saphid <saphid@users.noreply.github.com>
Date: Fri, 30 Oct 2026 15:03:06 +1100
Subject: [PATCH 06/26] fix: proxied OpenCode 2 fails closed; keyless hubs
 don't hide the proxy's accounts

- OpenCode 2 reads providers.*.settings, which the override does not write yet
- a hub at the proxy URL without a management key no longer suppresses the proxy source
- the Proxy search result redirects to an environment that can render it
- docs: the API key is only needed when the proxy requires one

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 apps/server/src/usage/UsageLimitSources.test.ts   |  7 +++++++
 apps/server/src/usage/UsageLimitSources.ts        |  2 +-
 .../components/settings/ProviderSettingsPanel.tsx |  3 ++-
 docs/user/install.md                              | 14 ++++++++------
 .../src/server/OpenCodeRuntime.ts                 | 10 ++++++----
 .../src/server/v2/OpenCode2Server.test.ts         | 15 +++++++++++++++
 .../src/server/v2/OpenCode2Server.ts              | 11 +++++++++++
 7 files changed, 50 insertions(+), 12 deletions(-)

diff --git a/apps/server/src/usage/UsageLimitSources.test.ts b/apps/server/src/usage/UsageLimitSources.test.ts
index 6b3ecc533f1a5..abeecc001685b 100644
--- a/apps/server/src/usage/UsageLimitSources.test.ts
+++ b/apps/server/src/usage/UsageLimitSources.test.ts
@@ -109,6 +109,13 @@ it("reports the routing proxy's accounts unless a hub already points at it or ow
       enabled: true,
     },
   });
+  // A keyless hub at the same URL can't read accounts, so the proxy's key still applies.
+  expect(
+    UsageLimitSources.effectiveUsageLimitSources({
+      ...settings,
+      usageLimitSources: { [UsageLimitSourceId.make("hub")]: { ...hub, managementKey: "" } },
+    })[UsageLimitSources.PROVIDER_PROXY_SOURCE_ID]?.managementKey,
+  ).toBe("mgmt");
   for (const listed of [
     { [UsageLimitSourceId.make("hub")]: hub },
     {
diff --git a/apps/server/src/usage/UsageLimitSources.ts b/apps/server/src/usage/UsageLimitSources.ts
index 4be81853c08b6..e9510f7f4755a 100644
--- a/apps/server/src/usage/UsageLimitSources.ts
+++ b/apps/server/src/usage/UsageLimitSources.ts
@@ -57,7 +57,7 @@ export function effectiveUsageLimitSources(
   const { managementKey } = settings.providerProxy;
   if (url === "" || managementKey === "") return settings.usageLimitSources;
   const alreadyListed = Object.values(settings.usageLimitSources).some(
-    (source) => normalizeProviderProxyUrl(source.url) === url,
+    (source) => source.managementKey !== "" && normalizeProviderProxyUrl(source.url) === url,
   );
   // A hand-written source may already use the synthetic id; it keeps the slot.
   if (alreadyListed || PROVIDER_PROXY_SOURCE_ID in settings.usageLimitSources) {
diff --git a/apps/web/src/components/settings/ProviderSettingsPanel.tsx b/apps/web/src/components/settings/ProviderSettingsPanel.tsx
index 54fb84fa5bda2..b456187fd9a47 100644
--- a/apps/web/src/components/settings/ProviderSettingsPanel.tsx
+++ b/apps/web/src/components/settings/ProviderSettingsPanel.tsx
@@ -357,7 +357,8 @@ function ProviderSettingsPanelContent(target: ProviderSettingsTarget) {
     } else if (
       !target.scoped &&
       (searchTargetId === searchableSetting("provider-health-check-interval").id ||
-        searchTargetId === searchableSetting("usage-providers").id) &&
+        searchTargetId === searchableSetting("usage-providers").id ||
+        searchTargetId === searchableSetting("provider-proxy").id) &&
       !selectedEnvironmentCanRenderSettings &&
       searchableEnvironmentId !== undefined
     ) {
diff --git a/docs/user/install.md b/docs/user/install.md
index 771cc8ab9dc94..b0a21122de4a6 100644
--- a/docs/user/install.md
+++ b/docs/user/install.md
@@ -196,11 +196,12 @@ their original values.
 
 ### Route providers through a proxy
 
-A [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) server can serve Claude, Codex,
-and OpenCode from accounts it holds, and spread requests across several accounts. To use one,
-open **Settings → Providers → Proxy** on the environment that runs the agents. Enter the proxy's
-URL and one of its API keys. Add its management key to see its accounts under **Usage → Limits**.
-Then turn on **Use proxy** for each Claude, Codex, or OpenCode provider that should use it.
+A [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) server can serve Claude, Codex, and
+OpenCode from accounts it holds, and spread requests across several accounts. To use one, open
+**Settings → Providers → Proxy** on the environment that runs the agents. Enter the proxy's URL,
+and one of its API keys if it requires one. Add its management key to see its accounts under
+**Usage → Limits**. Then turn on **Use proxy** for each Claude, Codex, or OpenCode provider that
+should use it.
 
 A provider with **Use proxy** on never falls back to its own login. If the proxy is removed, the
 provider shows as unavailable until you add a proxy again or turn the switch off. Codex threads
@@ -209,7 +210,8 @@ servers cannot use a proxy. While OpenCode uses the proxy, it offers only Anthro
 models and runs without its plugins, because other providers and plugin logins such as ChatGPT
 would send requests around the proxy. This needs OpenCode 1.14.49 or newer, and any
 `OPENCODE_CONFIG_CONTENT` must be plain JSON. An OpenCode organization or managed config that
-points Anthropic or OpenAI elsewhere makes the provider unavailable.
+points Anthropic or OpenAI elsewhere makes the provider unavailable. OpenCode 2 cannot use the
+proxy yet.
 
 For provider-specific setup and accounts, see [Codex](./providers-codex.md),
 [Claude](./providers-claude.md), [OpenCode](./providers-opencode.md),
diff --git a/packages/provider-opencode/src/server/OpenCodeRuntime.ts b/packages/provider-opencode/src/server/OpenCodeRuntime.ts
index 50c9f39ec0363..25090b60cefed 100644
--- a/packages/provider-opencode/src/server/OpenCodeRuntime.ts
+++ b/packages/provider-opencode/src/server/OpenCodeRuntime.ts
@@ -53,11 +53,13 @@ export const MINIMUM_OPENCODE_VERSION = "1.14.19";
 // login's plugin would send requests around the proxy.
 const MINIMUM_PROXIED_OPENCODE_VERSION = "1.14.49";
 
+/** Set only by applyOpenCodeProxyEnvironment. */
+export const isOpenCodeProxied = (environment: NodeJS.ProcessEnv | undefined): boolean =>
+  environment?.OPENCODE_DISABLE_DEFAULT_PLUGINS === "1";
+
 /** The oldest server a spawn may accept, given its environment. */
 export const minimumOpenCodeVersionFor = (environment: NodeJS.ProcessEnv | undefined): string =>
-  environment?.OPENCODE_DISABLE_DEFAULT_PLUGINS === "1"
-    ? MINIMUM_PROXIED_OPENCODE_VERSION
-    : MINIMUM_OPENCODE_VERSION;
+  isOpenCodeProxied(environment) ? MINIMUM_PROXIED_OPENCODE_VERSION : MINIMUM_OPENCODE_VERSION;
 const OPENCODE_HEALTH_TIMEOUT = "5 seconds";
 
 const OpenCodeHealthSchema = Schema.Struct({
@@ -277,7 +279,7 @@ export const verifyOpenCodeProxyRouting = Effect.fn("verifyOpenCodeProxyRouting"
   client: OpencodeClient,
   environment: NodeJS.ProcessEnv | undefined,
 ) {
-  if (environment?.OPENCODE_DISABLE_DEFAULT_PLUGINS !== "1") return;
+  if (!isOpenCodeProxied(environment)) return;
   const requested = Option.getOrElse(
     decodeOpenCodeConfigObject(resolveOpenCodeConfigContent(environment, {})),
     () => ({}),
diff --git a/packages/provider-opencode/src/server/v2/OpenCode2Server.test.ts b/packages/provider-opencode/src/server/v2/OpenCode2Server.test.ts
index d1e9693fb67b7..dbd047bcf47b4 100644
--- a/packages/provider-opencode/src/server/v2/OpenCode2Server.test.ts
+++ b/packages/provider-opencode/src/server/v2/OpenCode2Server.test.ts
@@ -207,6 +207,21 @@ describe("OpenCode2Server spawned server", () => {
       assert.strictEqual(first.version, "2.0.18");
       assert.strictEqual(first.external, false);
       assert.strictEqual(second.client, first.client);
+
+      const proxied = yield* OpenCode2Server.make({
+        binaryPath,
+        serverUrl: "",
+        serverPassword: "",
+        directory,
+        environment: OpenCodeRuntime.applyOpenCodeProxyEnvironment(yield* HostProcess.Environment, {
+          url: "http://proxy:8317",
+          apiKey: "sk",
+        }),
+      });
+      const refused = yield* proxied
+        .withConnection((connection) => Effect.succeed(connection))
+        .pipe(Effect.flip);
+      assert.include(refused.detail, "OpenCode 2 cannot use the proxy");
     }).pipe(
       Effect.scoped,
       Effect.provide(
diff --git a/packages/provider-opencode/src/server/v2/OpenCode2Server.ts b/packages/provider-opencode/src/server/v2/OpenCode2Server.ts
index c8c5dd7b70b64..9eeb952f772d2 100644
--- a/packages/provider-opencode/src/server/v2/OpenCode2Server.ts
+++ b/packages/provider-opencode/src/server/v2/OpenCode2Server.ts
@@ -154,8 +154,19 @@ export const make = Effect.fn("OpenCode2Server.make")(function* (input: {
     environment: serverEnvironment(input.environment, password),
     verify: (url) => connectTo(url, password, false).pipe(Effect.flatMap(remember)),
   });
+  // OpenCode 2 reads provider endpoints from `providers.*.settings`, which the proxy override
+  // does not write yet; running would send turns around the proxy.
+  const proxied = OpenCodeRuntime.isOpenCodeProxied(input.environment);
   return OpenCode2Server.of({
     withConnection: Effect.fn("OpenCode2Server.withConnection")(function (use) {
+      if (proxied) {
+        return Effect.fail(
+          new OpenCodeRuntime.OpenCodeRuntimeError({
+            operation: "server.start",
+            detail: "OpenCode 2 cannot use the proxy yet. Turn off Use proxy for this provider.",
+          }),
+        );
+      }
       return owner.withServer((server) =>
         latest?.url === server.url
           ? use(latest)

From 6a3957ba68b0d026db8e2604b431767793d1493d Mon Sep 17 00:00:00 2001
From: saphid <saphid@users.noreply.github.com>
Date: Fri, 30 Oct 2026 15:07:53 +1100
Subject: [PATCH 07/26] fix(opencode): proxy checks key off T3's own state, not
 OpenCode's plugin flag

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../src/server/OpenCodeRuntime.environment.test.ts     |  4 +++-
 .../provider-opencode/src/server/OpenCodeRuntime.ts    | 10 +++++++---
 packages/provider-opencode/src/server/driver.ts        |  1 +
 .../src/server/v2/OpenCode2Server.test.ts              | 10 +++++++++-
 .../provider-opencode/src/server/v2/OpenCode2Server.ts |  4 ++--
 5 files changed, 22 insertions(+), 7 deletions(-)

diff --git a/packages/provider-opencode/src/server/OpenCodeRuntime.environment.test.ts b/packages/provider-opencode/src/server/OpenCodeRuntime.environment.test.ts
index 745935efbc91c..d970fa807342e 100644
--- a/packages/provider-opencode/src/server/OpenCodeRuntime.environment.test.ts
+++ b/packages/provider-opencode/src/server/OpenCodeRuntime.environment.test.ts
@@ -124,7 +124,9 @@ describe("verifyOpenCodeServerVersion", () => {
         OpenCodeRuntime.minimumOpenCodeVersionFor(proxied),
       ).pipe(Effect.flip);
       expect(error.detail).toBe("OpenCode v1.14.48 is too old. Upgrade to v1.14.49 or newer.");
-      expect(OpenCodeRuntime.minimumOpenCodeVersionFor({})).toBe("1.14.19");
+      expect(
+        OpenCodeRuntime.minimumOpenCodeVersionFor({ OPENCODE_DISABLE_DEFAULT_PLUGINS: "1" }),
+      ).toBe("1.14.19");
     }),
   );
 });
diff --git a/packages/provider-opencode/src/server/OpenCodeRuntime.ts b/packages/provider-opencode/src/server/OpenCodeRuntime.ts
index 25090b60cefed..b2b08838ebb4e 100644
--- a/packages/provider-opencode/src/server/OpenCodeRuntime.ts
+++ b/packages/provider-opencode/src/server/OpenCodeRuntime.ts
@@ -53,9 +53,12 @@ export const MINIMUM_OPENCODE_VERSION = "1.14.19";
 // login's plugin would send requests around the proxy.
 const MINIMUM_PROXIED_OPENCODE_VERSION = "1.14.49";
 
-/** Set only by applyOpenCodeProxyEnvironment. */
-export const isOpenCodeProxied = (environment: NodeJS.ProcessEnv | undefined): boolean =>
-  environment?.OPENCODE_DISABLE_DEFAULT_PLUGINS === "1";
+// T3's own marker: OpenCode's flags may already be set by the user without a proxy.
+const PROXIED_MARKER = "T3CODE_OPENCODE_PROXIED";
+
+/** True only for an environment built by applyOpenCodeProxyEnvironment. */
+const isOpenCodeProxied = (environment: NodeJS.ProcessEnv | undefined): boolean =>
+  environment?.[PROXIED_MARKER] === "1";
 
 /** The oldest server a spawn may accept, given its environment. */
 export const minimumOpenCodeVersionFor = (environment: NodeJS.ProcessEnv | undefined): string =>
@@ -128,6 +131,7 @@ export function applyOpenCodeProxyEnvironment(
     ...environment,
     OPENCODE_CONFIG_CONTENT: content,
     OPENCODE_DISABLE_DEFAULT_PLUGINS: "1",
+    [PROXIED_MARKER]: "1",
     OPENCODE_PURE: "1",
   };
 }
diff --git a/packages/provider-opencode/src/server/driver.ts b/packages/provider-opencode/src/server/driver.ts
index dbaf3079c22fd..5a742cf5ab20b 100644
--- a/packages/provider-opencode/src/server/driver.ts
+++ b/packages/provider-opencode/src/server/driver.ts
@@ -289,6 +289,7 @@ export const OpenCodeDriver: ProviderDriver<
       serverPassword: effectiveConfig.serverPassword,
       directory: host.paths.cwd,
       environment: processEnv,
+      proxied: proxy !== undefined,
     }).pipe(
       Effect.provideService(OpenCodeRuntime.OpenCodeRuntime, openCodeRuntime),
       Effect.provideService(
diff --git a/packages/provider-opencode/src/server/v2/OpenCode2Server.test.ts b/packages/provider-opencode/src/server/v2/OpenCode2Server.test.ts
index dbd047bcf47b4..f4f3b111b094a 100644
--- a/packages/provider-opencode/src/server/v2/OpenCode2Server.test.ts
+++ b/packages/provider-opencode/src/server/v2/OpenCode2Server.test.ts
@@ -103,6 +103,7 @@ describe("OpenCode2Server error details", () => {
         serverPassword: "secret",
         directory: "/project",
         environment: {},
+        proxied: false,
       });
       const error = yield* server.withConnection(() => Effect.void).pipe(Effect.flip);
       return error.detail;
@@ -200,7 +201,13 @@ describe("OpenCode2Server spawned server", () => {
         serverUrl: "",
         serverPassword: "",
         directory,
-        environment: { ...(yield* HostProcess.Environment), OPENCODE_SERVER_PASSWORD: "ambient" },
+        // OpenCode's own flag may be set without a proxy; only `proxied` refuses OpenCode 2.
+        environment: {
+          ...(yield* HostProcess.Environment),
+          OPENCODE_SERVER_PASSWORD: "ambient",
+          OPENCODE_DISABLE_DEFAULT_PLUGINS: "1",
+        },
+        proxied: false,
       });
       const first = yield* server.withConnection((connection) => Effect.succeed(connection));
       const second = yield* server.withConnection((connection) => Effect.succeed(connection));
@@ -217,6 +224,7 @@ describe("OpenCode2Server spawned server", () => {
           url: "http://proxy:8317",
           apiKey: "sk",
         }),
+        proxied: true,
       });
       const refused = yield* proxied
         .withConnection((connection) => Effect.succeed(connection))
diff --git a/packages/provider-opencode/src/server/v2/OpenCode2Server.ts b/packages/provider-opencode/src/server/v2/OpenCode2Server.ts
index 9eeb952f772d2..a604c0da5785a 100644
--- a/packages/provider-opencode/src/server/v2/OpenCode2Server.ts
+++ b/packages/provider-opencode/src/server/v2/OpenCode2Server.ts
@@ -115,6 +115,7 @@ export const make = Effect.fn("OpenCode2Server.make")(function* (input: {
   readonly serverPassword: string;
   readonly directory: string;
   readonly environment: NodeJS.ProcessEnv;
+  readonly proxied: boolean;
 }) {
   const opencode = yield* OpenCode2Client.OpenCode2Client;
   const connectTo = Effect.fn("OpenCode2Server.connectTo")(function* (
@@ -156,10 +157,9 @@ export const make = Effect.fn("OpenCode2Server.make")(function* (input: {
   });
   // OpenCode 2 reads provider endpoints from `providers.*.settings`, which the proxy override
   // does not write yet; running would send turns around the proxy.
-  const proxied = OpenCodeRuntime.isOpenCodeProxied(input.environment);
   return OpenCode2Server.of({
     withConnection: Effect.fn("OpenCode2Server.withConnection")(function (use) {
-      if (proxied) {
+      if (input.proxied) {
         return Effect.fail(
           new OpenCodeRuntime.OpenCodeRuntimeError({
             operation: "server.start",

From 23714fc25d1dc3af8600ae28d577413c017af1a3 Mon Sep 17 00:00:00 2001
From: saphid <saphid@users.noreply.github.com>
Date: Fri, 30 Oct 2026 15:14:56 +1100
Subject: [PATCH 08/26] fix(opencode): proxied servers reject widened provider
 lists and accept empty config

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../OpenCodeRuntime.environment.test.ts       |  8 ++++++
 .../src/server/OpenCodeRuntime.ts             | 28 +++++++++++++++----
 2 files changed, 30 insertions(+), 6 deletions(-)

diff --git a/packages/provider-opencode/src/server/OpenCodeRuntime.environment.test.ts b/packages/provider-opencode/src/server/OpenCodeRuntime.environment.test.ts
index d970fa807342e..b0021e2473ac4 100644
--- a/packages/provider-opencode/src/server/OpenCodeRuntime.environment.test.ts
+++ b/packages/provider-opencode/src/server/OpenCodeRuntime.environment.test.ts
@@ -24,6 +24,8 @@ describe("applyOpenCodeProxyEnvironment", () => {
     // Plugins such as Codex's ChatGPT login replace fetch and would bypass the proxy.
     expect(environment.OPENCODE_DISABLE_DEFAULT_PLUGINS).toBe("1");
     expect(environment.OPENCODE_PURE).toBe("1");
+    // OpenCode treats empty content as unset.
+    expect(OpenCodeRuntime.isPlainJsonOpenCodeConfig({ OPENCODE_CONFIG_CONTENT: "" })).toBe(true);
     expect(
       OpenCodeRuntime.isPlainJsonOpenCodeConfig({
         OPENCODE_CONFIG_CONTENT: '{ "theme": "t3", // comment\n }',
@@ -64,6 +66,12 @@ describe("verifyOpenCodeProxyRouting", () => {
         environment,
       ).pipe(Effect.flip);
       expect(error.detail).toContain("openai provider points somewhere other than the proxy");
+
+      const widened = yield* OpenCodeRuntime.verifyOpenCodeProxyRouting(
+        clientWith({ ...requested, enabled_providers: ["anthropic", "openai", "openrouter"] }),
+        environment,
+      ).pipe(Effect.flip);
+      expect(widened.detail).toContain("enables providers the proxy does not route");
     }),
   );
 });
diff --git a/packages/provider-opencode/src/server/OpenCodeRuntime.ts b/packages/provider-opencode/src/server/OpenCodeRuntime.ts
index b2b08838ebb4e..76f12b4492682 100644
--- a/packages/provider-opencode/src/server/OpenCodeRuntime.ts
+++ b/packages/provider-opencode/src/server/OpenCodeRuntime.ts
@@ -85,6 +85,13 @@ function resolveOpenCodeConfigContent(
 const decodeOpenCodeConfigObject = Schema.decodeUnknownOption(
   Schema.fromJsonString(Schema.Record(Schema.String, Schema.Unknown)),
 );
+// OpenCode treats empty content as unset.
+const decodeRequestedOpenCodeConfig = (environment: NodeJS.ProcessEnv | undefined) => {
+  const content = resolveOpenCodeConfigContent(environment, {});
+  return decodeOpenCodeConfigObject(
+    content.trim() === "" ? OPENCODE_EMPTY_CONFIG_CONTENT : content,
+  );
+};
 const asRecord = (value: unknown): Readonly<Record<string, unknown>> =>
   typeof value === "object" && value !== null && !Array.isArray(value)
     ? (value as Record<string, unknown>)
@@ -92,7 +99,7 @@ const asRecord = (value: unknown): Readonly<Record<string, unknown>> =>
 
 /** OpenCode accepts JSONC here, but the proxy override can only merge into plain JSON. */
 export const isPlainJsonOpenCodeConfig = (environment: NodeJS.ProcessEnv): boolean =>
-  Option.isSome(decodeOpenCodeConfigObject(resolveOpenCodeConfigContent(environment, {})));
+  Option.isSome(decodeRequestedOpenCodeConfig(environment));
 
 /**
  * Points OpenCode's built-in Anthropic and OpenAI providers at the proxy. Their model catalogs
@@ -104,7 +111,7 @@ export function applyOpenCodeProxyEnvironment(
 ): NodeJS.ProcessEnv {
   if (proxy === undefined) return environment;
   const base: Readonly<Record<string, unknown>> = Option.getOrElse(
-    decodeOpenCodeConfigObject(resolveOpenCodeConfigContent(environment, {})),
+    decodeRequestedOpenCodeConfig(environment),
     () => ({}),
   );
   const providers = asRecord(base.provider);
@@ -284,13 +291,22 @@ export const verifyOpenCodeProxyRouting = Effect.fn("verifyOpenCodeProxyRouting"
   environment: NodeJS.ProcessEnv | undefined,
 ) {
   if (!isOpenCodeProxied(environment)) return;
-  const requested = Option.getOrElse(
-    decodeOpenCodeConfigObject(resolveOpenCodeConfigContent(environment, {})),
-    () => ({}),
-  );
+  const requested = Option.getOrElse(decodeRequestedOpenCodeConfig(environment), () => ({}));
   const effective = yield* runOpenCodeSdk("config.get", (signal) =>
     client.config.get(undefined, { signal }),
   );
+  const enabled = asRecord(effective.data).enabled_providers;
+  const routedOnly =
+    Array.isArray(enabled) &&
+    enabled.length > 0 &&
+    enabled.every((id) => (PROXY_ROUTED_OPENCODE_PROVIDERS as ReadonlyArray<unknown>).includes(id));
+  if (!routedOnly) {
+    return yield* new OpenCodeRuntimeError({
+      operation: "config.get",
+      detail:
+        "OpenCode enables providers the proxy does not route, likely from an organization or managed config. Remove that override or turn off Use proxy.",
+    });
+  }
   for (const providerId of PROXY_ROUTED_OPENCODE_PROVIDERS) {
     if (providerBaseUrl(effective.data, providerId) !== providerBaseUrl(requested, providerId)) {
       return yield* new OpenCodeRuntimeError({

From 5e56d1681076ec750291bf97786295e1cce9d0c8 Mon Sep 17 00:00:00 2001
From: saphid <saphid@users.noreply.github.com>
Date: Fri, 30 Oct 2026 15:23:22 +1100
Subject: [PATCH 09/26] fix(opencode): configured auth headers can't send a
 direct key to the proxy

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../OpenCodeRuntime.environment.test.ts       | 14 ++++++++--
 .../src/server/OpenCodeRuntime.ts             | 26 ++++++++++++++++++-
 2 files changed, 37 insertions(+), 3 deletions(-)

diff --git a/packages/provider-opencode/src/server/OpenCodeRuntime.environment.test.ts b/packages/provider-opencode/src/server/OpenCodeRuntime.environment.test.ts
index b0021e2473ac4..6b938bf07e8ee 100644
--- a/packages/provider-opencode/src/server/OpenCodeRuntime.environment.test.ts
+++ b/packages/provider-opencode/src/server/OpenCodeRuntime.environment.test.ts
@@ -12,7 +12,14 @@ describe("applyOpenCodeProxyEnvironment", () => {
         OPENCODE_CONFIG_CONTENT: JSON.stringify({
           theme: "t3",
           provider: {
-            anthropic: { options: { timeout: 60_000, apiKey: "sk-ant-direct" } },
+            anthropic: {
+              options: {
+                timeout: 60_000,
+                apiKey: "sk-ant-direct",
+                headers: { Authorization: "Bearer direct", "X-Trace": "1" },
+              },
+              models: { "claude-x": { headers: { "x-api-key": "sk-ant-direct", "X-Tier": "a" } } },
+            },
             openrouter: { options: { apiKey: "or" } },
           },
         }),
@@ -35,7 +42,10 @@ describe("applyOpenCodeProxyEnvironment", () => {
       theme: "t3",
       enabled_providers: ["anthropic", "openai"],
       provider: {
-        anthropic: { options: { timeout: 60_000, ...proxied } },
+        anthropic: {
+          options: { timeout: 60_000, headers: { "X-Trace": "1" }, ...proxied },
+          models: { "claude-x": { headers: { "X-Tier": "a" } } },
+        },
         openai: { options: proxied },
         openrouter: { options: { apiKey: "or" } },
       },
diff --git a/packages/provider-opencode/src/server/OpenCodeRuntime.ts b/packages/provider-opencode/src/server/OpenCodeRuntime.ts
index 76f12b4492682..a0490ca0ac819 100644
--- a/packages/provider-opencode/src/server/OpenCodeRuntime.ts
+++ b/packages/provider-opencode/src/server/OpenCodeRuntime.ts
@@ -97,6 +97,13 @@ const asRecord = (value: unknown): Readonly<Record<string, unknown>> =>
     ? (value as Record<string, unknown>)
     : {};
 
+// The SDKs apply configured headers after the key, so a direct credential would reach the proxy.
+const AUTH_HEADER_PATTERN = /^(authorization|proxy-authorization|x-api-key|api-key)$/i;
+const withoutAuthHeaders = (headers: unknown) =>
+  Object.fromEntries(
+    Object.entries(asRecord(headers)).filter(([name]) => !AUTH_HEADER_PATTERN.test(name)),
+  );
+
 /** OpenCode accepts JSONC here, but the proxy override can only merge into plain JSON. */
 export const isPlainJsonOpenCodeConfig = (environment: NodeJS.ProcessEnv): boolean =>
   Option.isSome(decodeRequestedOpenCodeConfig(environment));
@@ -117,13 +124,30 @@ export function applyOpenCodeProxyEnvironment(
   const providers = asRecord(base.provider);
   const routed = (id: string) => {
     const provider = asRecord(providers[id]);
+    const options = asRecord(provider.options);
     return {
       ...provider,
       options: {
-        ...asRecord(provider.options),
+        ...options,
+        ...("headers" in options ? { headers: withoutAuthHeaders(options.headers) } : {}),
         baseURL: providerProxyApiUrl(proxy),
         apiKey: providerProxyToken(proxy),
       },
+      ...("models" in provider
+        ? {
+            models: Object.fromEntries(
+              Object.entries(asRecord(provider.models)).map(([modelId, model]) => {
+                const entry = asRecord(model);
+                return [
+                  modelId,
+                  "headers" in entry
+                    ? { ...entry, headers: withoutAuthHeaders(entry.headers) }
+                    : model,
+                ];
+              }),
+            ),
+          }
+        : {}),
     };
   };
   const content = encodeUnknownJsonString({

From 762bfd847b4efbfdf86dc2a363a77e871b2099ef Mon Sep 17 00:00:00 2001
From: saphid <saphid@users.noreply.github.com>
Date: Fri, 30 Oct 2026 15:29:35 +1100
Subject: [PATCH 10/26] fix(opencode): bound the proxy routing check with the
 health timeout

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../src/server/OpenCodeRuntime.environment.test.ts    |  9 +++++++++
 .../provider-opencode/src/server/OpenCodeRuntime.ts   | 11 +++++++++--
 2 files changed, 18 insertions(+), 2 deletions(-)

diff --git a/packages/provider-opencode/src/server/OpenCodeRuntime.environment.test.ts b/packages/provider-opencode/src/server/OpenCodeRuntime.environment.test.ts
index 6b938bf07e8ee..467c40918da2e 100644
--- a/packages/provider-opencode/src/server/OpenCodeRuntime.environment.test.ts
+++ b/packages/provider-opencode/src/server/OpenCodeRuntime.environment.test.ts
@@ -1,6 +1,8 @@
 import type { OpencodeClient } from "@opencode-ai/sdk/v2";
 import { it as effectIt } from "@effect/vitest";
 import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
+import * as TestClock from "effect/testing/TestClock";
 import { describe, expect, it } from "vite-plus/test";
 
 import * as OpenCodeRuntime from "./OpenCodeRuntime.ts";
@@ -82,6 +84,13 @@ describe("verifyOpenCodeProxyRouting", () => {
         environment,
       ).pipe(Effect.flip);
       expect(widened.detail).toContain("enables providers the proxy does not route");
+
+      const stalled = yield* OpenCodeRuntime.verifyOpenCodeProxyRouting(
+        { config: { get: () => new Promise(() => {}) } } as unknown as OpencodeClient,
+        environment,
+      ).pipe(Effect.flip, Effect.forkChild);
+      yield* TestClock.adjust("5 seconds");
+      expect((yield* Fiber.join(stalled)).detail).toContain("Timed out");
     }),
   );
 });
diff --git a/packages/provider-opencode/src/server/OpenCodeRuntime.ts b/packages/provider-opencode/src/server/OpenCodeRuntime.ts
index a0490ca0ac819..163287dfc17b8 100644
--- a/packages/provider-opencode/src/server/OpenCodeRuntime.ts
+++ b/packages/provider-opencode/src/server/OpenCodeRuntime.ts
@@ -316,9 +316,16 @@ export const verifyOpenCodeProxyRouting = Effect.fn("verifyOpenCodeProxyRouting"
 ) {
   if (!isOpenCodeProxied(environment)) return;
   const requested = Option.getOrElse(decodeRequestedOpenCodeConfig(environment), () => ({}));
-  const effective = yield* runOpenCodeSdk("config.get", (signal) =>
+  const effectiveOption = yield* runOpenCodeSdk("config.get", (signal) =>
     client.config.get(undefined, { signal }),
-  );
+  ).pipe(Effect.timeoutOption(OPENCODE_HEALTH_TIMEOUT));
+  if (Option.isNone(effectiveOption)) {
+    return yield* new OpenCodeRuntimeError({
+      operation: "config.get",
+      detail: "Timed out while checking that OpenCode routes through the proxy.",
+    });
+  }
+  const effective = effectiveOption.value;
   const enabled = asRecord(effective.data).enabled_providers;
   const routedOnly =
     Array.isArray(enabled) &&

From 87c5cf2568bcbe6db6bcb81922aef2ad6d0b9a70 Mon Sep 17 00:00:00 2001
From: saphid <saphid@users.noreply.github.com>
Date: Fri, 30 Oct 2026 15:31:20 +1100
Subject: [PATCH 11/26] fix(opencode): a configured Anthropic authToken can't
 block or bypass the proxy

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../src/server/OpenCodeRuntime.environment.test.ts             | 1 +
 packages/provider-opencode/src/server/OpenCodeRuntime.ts       | 3 ++-
 2 files changed, 3 insertions(+), 1 deletion(-)

diff --git a/packages/provider-opencode/src/server/OpenCodeRuntime.environment.test.ts b/packages/provider-opencode/src/server/OpenCodeRuntime.environment.test.ts
index 467c40918da2e..8dbfd5c40fc30 100644
--- a/packages/provider-opencode/src/server/OpenCodeRuntime.environment.test.ts
+++ b/packages/provider-opencode/src/server/OpenCodeRuntime.environment.test.ts
@@ -18,6 +18,7 @@ describe("applyOpenCodeProxyEnvironment", () => {
               options: {
                 timeout: 60_000,
                 apiKey: "sk-ant-direct",
+                authToken: "direct-oauth-token",
                 headers: { Authorization: "Bearer direct", "X-Trace": "1" },
               },
               models: { "claude-x": { headers: { "x-api-key": "sk-ant-direct", "X-Tier": "a" } } },
diff --git a/packages/provider-opencode/src/server/OpenCodeRuntime.ts b/packages/provider-opencode/src/server/OpenCodeRuntime.ts
index 163287dfc17b8..41b202062a46d 100644
--- a/packages/provider-opencode/src/server/OpenCodeRuntime.ts
+++ b/packages/provider-opencode/src/server/OpenCodeRuntime.ts
@@ -124,7 +124,8 @@ export function applyOpenCodeProxyEnvironment(
   const providers = asRecord(base.provider);
   const routed = (id: string) => {
     const provider = asRecord(providers[id]);
-    const options = asRecord(provider.options);
+    // A configured authToken is a direct credential, and the Anthropic SDK rejects it next to apiKey.
+    const { authToken: _authToken, ...options } = asRecord(provider.options);
     return {
       ...provider,
       options: {

From 62d4294bd98d61b1af3c38a1b3a4c98780ef8aef Mon Sep 17 00:00:00 2001
From: saphid <saphid@users.noreply.github.com>
Date: Fri, 30 Oct 2026 15:40:28 +1100
Subject: [PATCH 12/26] fix(opencode): the routing check also rejects restored
 direct credentials

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../OpenCodeRuntime.environment.test.ts       | 22 ++++++++++++++-
 .../src/server/OpenCodeRuntime.ts             | 27 ++++++++++++++++---
 2 files changed, 44 insertions(+), 5 deletions(-)

diff --git a/packages/provider-opencode/src/server/OpenCodeRuntime.environment.test.ts b/packages/provider-opencode/src/server/OpenCodeRuntime.environment.test.ts
index 8dbfd5c40fc30..854d44cf224ef 100644
--- a/packages/provider-opencode/src/server/OpenCodeRuntime.environment.test.ts
+++ b/packages/provider-opencode/src/server/OpenCodeRuntime.environment.test.ts
@@ -78,7 +78,27 @@ describe("verifyOpenCodeProxyRouting", () => {
         }),
         environment,
       ).pipe(Effect.flip);
-      expect(error.detail).toContain("openai provider points somewhere other than the proxy");
+      expect(error.detail).toContain("openai provider uses an endpoint or credential other");
+
+      // A later config can keep the proxy URL but restore a direct credential.
+      for (const override of [
+        { apiKey: "sk-ant-direct" },
+        { authToken: "direct" },
+        { headers: { "X-Api-Key": "sk-ant-direct" } },
+      ]) {
+        const anthropic = requested.provider.anthropic;
+        const restored = yield* OpenCodeRuntime.verifyOpenCodeProxyRouting(
+          clientWith({
+            ...requested,
+            provider: {
+              ...requested.provider,
+              anthropic: { ...anthropic, options: { ...anthropic.options, ...override } },
+            },
+          }),
+          environment,
+        ).pipe(Effect.flip);
+        expect(restored.detail).toContain("anthropic provider uses an endpoint or credential");
+      }
 
       const widened = yield* OpenCodeRuntime.verifyOpenCodeProxyRouting(
         clientWith({ ...requested, enabled_providers: ["anthropic", "openai", "openrouter"] }),
diff --git a/packages/provider-opencode/src/server/OpenCodeRuntime.ts b/packages/provider-opencode/src/server/OpenCodeRuntime.ts
index 41b202062a46d..c35a74bad71e4 100644
--- a/packages/provider-opencode/src/server/OpenCodeRuntime.ts
+++ b/packages/provider-opencode/src/server/OpenCodeRuntime.ts
@@ -304,8 +304,27 @@ export const verifyOpenCodeServerVersion = Effect.fn("verifyOpenCodeServerVersio
 
 const PROXY_ROUTED_OPENCODE_PROVIDERS = ["anthropic", "openai"] as const;
 
-const providerBaseUrl = (config: unknown, providerId: string): unknown =>
-  asRecord(asRecord(asRecord(asRecord(config).provider)[providerId]).options).baseURL;
+const routedProvider = (config: unknown, providerId: string) =>
+  asRecord(asRecord(asRecord(config).provider)[providerId]);
+
+const hasAuthHeader = (headers: unknown) =>
+  Object.keys(asRecord(headers)).some((name) => AUTH_HEADER_PATTERN.test(name));
+
+/** The provider sends exactly the proxy's endpoint and token, with no other credential. */
+const routesOnlyToProxy = (effective: unknown, requested: unknown, providerId: string) => {
+  const provider = routedProvider(effective, providerId);
+  const options = asRecord(provider.options);
+  const wanted = asRecord(routedProvider(requested, providerId).options);
+  return (
+    options.baseURL === wanted.baseURL &&
+    options.apiKey === wanted.apiKey &&
+    !("authToken" in options) &&
+    !hasAuthHeader(options.headers) &&
+    Object.values(asRecord(provider.models)).every(
+      (model) => !hasAuthHeader(asRecord(model).headers),
+    )
+  );
+};
 
 /**
  * Organization and managed configs merge after OPENCODE_CONFIG_CONTENT and can point a routed
@@ -340,10 +359,10 @@ export const verifyOpenCodeProxyRouting = Effect.fn("verifyOpenCodeProxyRouting"
     });
   }
   for (const providerId of PROXY_ROUTED_OPENCODE_PROVIDERS) {
-    if (providerBaseUrl(effective.data, providerId) !== providerBaseUrl(requested, providerId)) {
+    if (!routesOnlyToProxy(effective.data, requested, providerId)) {
       return yield* new OpenCodeRuntimeError({
         operation: "config.get",
-        detail: `OpenCode's ${providerId} provider points somewhere other than the proxy, likely from an organization or managed config. Remove that override or turn off Use proxy.`,
+        detail: `OpenCode's ${providerId} provider uses an endpoint or credential other than the proxy's, likely from an organization or managed config. Remove that override or turn off Use proxy.`,
       });
     }
   }

From b3f06048d64e80ab1ac3f39ae5b0686a62aee1ac Mon Sep 17 00:00:00 2001
From: "github-actions[bot]"
 <41898282+github-actions[bot]@users.noreply.github.com>
Date: Fri, 30 Oct 2026 15:21:17 +1100
Subject: [PATCH 13/26] feat(server): run CLIProxyAPI on this environment and
 manage its accounts in Settings
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The provider proxy needed a CLIProxyAPI server someone ran by hand, and its
accounts were managed outside T3 Code.

Settings → Providers → Proxy now picks the host: Off, This environment, or
External URL. "This environment" downloads the pinned CLIProxyAPI 8.0.47
release (per-platform SHA-256, staged extract, version check) into T3 home,
writes its config (loopback only, one generated client key, a generated
management key, session affinity) and keeps both keys in the secret store,
then supervises it with restart backoff. Use proxy instances route to it with
no further setup, and it feeds Usage → Limits like an external proxy with a
management key.

A ProxyAccounts service wraps the /v0/management API: list, disable/enable,
remove, and Claude/Codex sign-in with paste-back of the localhost redirect.
It is exposed as provider.proxy.* RPCs behind providers:manage, and the Proxy
section lists accounts by provider.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 apps/server/src/auth/RpcAuthorization.test.ts |  13 +
 apps/server/src/auth/RpcAuthorization.ts      |   3 +
 .../src/observability/RpcInstrumentation.ts   |   6 +
 .../src/provider/ProviderInstanceRegistry.ts  |   2 +-
 .../ProviderInstanceRegistryHydration.test.ts |  21 +
 .../ProviderInstanceRegistryHydration.ts      |  32 +-
 .../src/provider/ProviderRegistry.test.ts     |   2 +
 .../src/providerProxy/CliProxyApiBinary.ts    | 295 ++++++++++
 .../ManagedProviderProxy.test.ts              |  42 ++
 .../src/providerProxy/ManagedProviderProxy.ts | 311 ++++++++++
 .../src/providerProxy/ProxyAccounts.test.ts   | 234 ++++++++
 .../server/src/providerProxy/ProxyAccounts.ts | 320 +++++++++++
 .../src/providerProxy/effectiveProxy.ts       |  54 ++
 apps/server/src/server.ts                     |  11 +
 .../src/usage/UsageLimitSources.test.ts       |  21 +
 apps/server/src/usage/UsageLimitSources.ts    |  31 +-
 apps/server/src/ws.test.ts                    |   2 +
 apps/server/src/ws.ts                         |  10 +
 .../settings/ProviderInstanceCard.tsx         |   4 +-
 .../settings/ProviderProxySettings.tsx        | 537 +++++++++++++++---
 .../settings/ProviderSettingsPanel.tsx        |   3 +-
 .../src/components/settings/settingsSearch.ts |   2 +-
 apps/web/src/state/providerProxy.ts           |   5 +
 docs/user/install.md                          |  36 +-
 docs/user/usage.md                            |   3 +-
 packages/client-runtime/package.json          |   4 +
 .../src/state/commandPermissions.test.ts      |  18 +-
 .../client-runtime/src/state/providerProxy.ts |  59 ++
 .../contracts/src/clientRpcPermissions.ts     |   6 +
 packages/contracts/src/index.ts               |   1 +
 packages/contracts/src/providerProxy.ts       |  92 +++
 packages/contracts/src/rpc.ts                 |  58 ++
 packages/contracts/src/settings.ts            |   8 +-
 33 files changed, 2129 insertions(+), 117 deletions(-)
 create mode 100644 apps/server/src/providerProxy/CliProxyApiBinary.ts
 create mode 100644 apps/server/src/providerProxy/ManagedProviderProxy.test.ts
 create mode 100644 apps/server/src/providerProxy/ManagedProviderProxy.ts
 create mode 100644 apps/server/src/providerProxy/ProxyAccounts.test.ts
 create mode 100644 apps/server/src/providerProxy/ProxyAccounts.ts
 create mode 100644 apps/server/src/providerProxy/effectiveProxy.ts
 create mode 100644 apps/web/src/state/providerProxy.ts
 create mode 100644 packages/client-runtime/src/state/providerProxy.ts
 create mode 100644 packages/contracts/src/providerProxy.ts

diff --git a/apps/server/src/auth/RpcAuthorization.test.ts b/apps/server/src/auth/RpcAuthorization.test.ts
index 24c22280175cc..9ea93fed3180b 100644
--- a/apps/server/src/auth/RpcAuthorization.test.ts
+++ b/apps/server/src/auth/RpcAuthorization.test.ts
@@ -67,6 +67,19 @@ describe("RPC authorization scopes", () => {
     }
   });
 
+  it("keeps proxy accounts, which read and spend pooled subscriptions, behind provider management", () => {
+    for (const method of [
+      WS_METHODS.providerProxyGetState,
+      WS_METHODS.providerProxyStartLogin,
+      WS_METHODS.providerProxyGetLoginStatus,
+      WS_METHODS.providerProxyCompleteLogin,
+      WS_METHODS.providerProxySetAccountDisabled,
+      WS_METHODS.providerProxyRemoveAccount,
+    ]) {
+      expect(requiredScopeForRpcMethod(method)).toBe(AuthProvidersManageScope);
+    }
+  });
+
   it("rejects unknown RPC method names", () => {
     for (const method of ["server.notRegistered", "toString", "constructor"]) {
       expect(() => requiredScopeForRpcMethod(method)).toThrow(
diff --git a/apps/server/src/auth/RpcAuthorization.ts b/apps/server/src/auth/RpcAuthorization.ts
index a1b05c32a0027..65a206c5e5bca 100644
--- a/apps/server/src/auth/RpcAuthorization.ts
+++ b/apps/server/src/auth/RpcAuthorization.ts
@@ -64,6 +64,9 @@ export const RPC_REQUIRED_SCOPES = {
   [WS_METHODS.serverUpdateProvider]: AuthProvidersManageScope,
   [WS_METHODS.providerAuthStart]: AuthProvidersManageScope,
   [WS_METHODS.providerConsumeResetCredit]: AuthProvidersManageScope,
+  // Account emails and login status come from the management key.
+  [WS_METHODS.providerProxyGetState]: AuthProvidersManageScope,
+  [WS_METHODS.providerProxyGetLoginStatus]: AuthProvidersManageScope,
   [WS_METHODS.providerAuthComplete]: AuthProvidersManageScope,
   [WS_METHODS.chatGptReconnectProfile]: AuthProvidersManageScope,
   [WS_METHODS.chatGptImportProfile]: AuthProvidersManageScope,
diff --git a/apps/server/src/observability/RpcInstrumentation.ts b/apps/server/src/observability/RpcInstrumentation.ts
index 259fa92a66023..e5c4353917e7c 100644
--- a/apps/server/src/observability/RpcInstrumentation.ts
+++ b/apps/server/src/observability/RpcInstrumentation.ts
@@ -36,6 +36,12 @@ const RPC_AGGREGATES = {
   [WS_METHODS.serverUpdateProvider]: "server",
   [WS_METHODS.providerAuthStart]: "provider",
   [WS_METHODS.providerConsumeResetCredit]: "provider",
+  [WS_METHODS.providerProxyGetState]: "provider",
+  [WS_METHODS.providerProxyStartLogin]: "provider",
+  [WS_METHODS.providerProxyGetLoginStatus]: "provider",
+  [WS_METHODS.providerProxyCompleteLogin]: "provider",
+  [WS_METHODS.providerProxySetAccountDisabled]: "provider",
+  [WS_METHODS.providerProxyRemoveAccount]: "provider",
   [WS_METHODS.providerAuthComplete]: "provider",
   [WS_METHODS.chatGptReconnectProfile]: "provider",
   [WS_METHODS.chatGptImportProfile]: "provider",
diff --git a/apps/server/src/provider/ProviderInstanceRegistry.ts b/apps/server/src/provider/ProviderInstanceRegistry.ts
index 56edd59107418..e0bbed6466b7b 100644
--- a/apps/server/src/provider/ProviderInstanceRegistry.ts
+++ b/apps/server/src/provider/ProviderInstanceRegistry.ts
@@ -61,7 +61,7 @@ const proxyUnavailableReason = (
   }
   // Falling back to the instance's own login would silently spend a different account.
   if (entry.proxy === undefined) {
-    return "Use proxy is on, but this environment has no proxy. Add one in Settings → Providers → Proxy, or turn off Use proxy.";
+    return "Use proxy is on, but this environment has no proxy. Choose one in Settings → Providers → Proxy, or turn off Use proxy.";
   }
   return undefined;
 };
diff --git a/apps/server/src/provider/ProviderInstanceRegistryHydration.test.ts b/apps/server/src/provider/ProviderInstanceRegistryHydration.test.ts
index fb16fa967d0e7..c5fddd35e30f4 100644
--- a/apps/server/src/provider/ProviderInstanceRegistryHydration.test.ts
+++ b/apps/server/src/provider/ProviderInstanceRegistryHydration.test.ts
@@ -97,6 +97,27 @@ describe("deriveProviderInstanceConfigMap", () => {
         providerProxy: { ...settings.providerProxy, url: "" },
       })[instanceId]?.proxy,
     ).toBeUndefined();
+
+    // The host decides which proxy applies; a managed one carries its own loopback route and key.
+    const managed = {
+      url: "http://127.0.0.1:41234",
+      apiKey: "sk-managed",
+      managementKey: "mgmt-managed",
+    };
+    const withHost = (host: "off" | "managed" | "external") => ({
+      ...settings,
+      providerProxy: { ...settings.providerProxy, host },
+    });
+    expect(
+      deriveProviderInstanceConfigMap(withHost("managed"), managed)[instanceId]?.proxy,
+    ).toEqual({ url: "http://127.0.0.1:41234", apiKey: "sk-managed" });
+    expect(deriveProviderInstanceConfigMap(withHost("managed"))[instanceId]?.proxy).toBeUndefined();
+    expect(
+      deriveProviderInstanceConfigMap(withHost("off"), managed)[instanceId]?.proxy,
+    ).toBeUndefined();
+    expect(
+      deriveProviderInstanceConfigMap(withHost("external"), managed)[instanceId]?.proxy,
+    ).toEqual({ url: "http://proxy:8317", apiKey: "sk-proxy" });
   });
 
   it("ignores a project override that disables an instance, leaving the machine's config in charge", () => {
diff --git a/apps/server/src/provider/ProviderInstanceRegistryHydration.ts b/apps/server/src/provider/ProviderInstanceRegistryHydration.ts
index 52560781213e6..a6ab8ee565327 100644
--- a/apps/server/src/provider/ProviderInstanceRegistryHydration.ts
+++ b/apps/server/src/provider/ProviderInstanceRegistryHydration.ts
@@ -7,10 +7,6 @@ import {
   type ProviderInstanceConfig,
   ServerSettings,
 } from "@t3tools/contracts";
-import {
-  normalizeProviderProxyUrl,
-  type ProviderProxyRoute,
-} from "@t3tools/provider-core/server/providerProxy";
 import * as HostProcess from "@t3tools/shared/HostProcess";
 import * as Effect from "effect/Effect";
 import * as FileSystem from "effect/FileSystem";
@@ -19,6 +15,11 @@ import * as Path from "effect/Path";
 import * as Stream from "effect/Stream";
 
 import * as Settings from "../serverSettings.ts";
+import {
+  resolveProviderProxyRoute,
+  type ManagedProxyEndpoint,
+} from "../providerProxy/effectiveProxy.ts";
+import * as ManagedProviderProxy from "../providerProxy/ManagedProviderProxy.ts";
 import { BUILT_IN_DRIVERS, type BuiltInDriversEnv } from "./builtInDrivers.ts";
 import * as ProviderInstanceRegistry from "./ProviderInstanceRegistry.ts";
 import * as ProviderInstanceRegistryMutator from "./ProviderInstanceRegistryMutator.ts";
@@ -38,6 +39,7 @@ type ProviderInstanceRegistryHydrationEnv =
       | ProviderHost.ProviderHost
     >
   | Settings.ServerSettingsService
+  | ManagedProviderProxy.ManagedProviderProxy
   | BackgroundPolicy.BackgroundPolicy
   | ServerConfig.ServerConfig
   | Path.Path
@@ -45,13 +47,9 @@ type ProviderInstanceRegistryHydrationEnv =
   // The Claude runner counts its CLIs as running agents for port discovery.
   | PortScanner.PortDiscovery;
 
-const resolveProviderProxyRoute = (settings: ServerSettings): ProviderProxyRoute | undefined => {
-  const url = normalizeProviderProxyUrl(settings.providerProxy.url);
-  return url === "" ? undefined : { url, apiKey: settings.providerProxy.apiKey };
-};
-
 export const deriveProviderInstanceConfigMap = (
   settings: ServerSettings,
+  managedProxy?: ManagedProxyEndpoint,
 ): ProviderInstanceRegistryMutator.ProviderInstanceRuntimeMap => {
   const merged: Record<string, ProviderInstanceConfig> = { ...settings.providerInstances };
 
@@ -81,7 +79,7 @@ export const deriveProviderInstanceConfigMap = (
     }
   }
 
-  const proxy = resolveProviderProxyRoute(settings);
+  const proxy = resolveProviderProxyRoute(settings, managedProxy);
   if (proxy === undefined) return merged;
   return Object.fromEntries(
     Object.entries(merged).map(([id, entry]) => [
@@ -137,13 +135,16 @@ const layerSettingsWatcher = (settingsChanges: Stream.Stream<ServerSettings>) =>
     Effect.gen(function* () {
       const mutator = yield* ProviderInstanceRegistryMutator.ProviderInstanceRegistryMutator;
       const serverSettings = yield* Settings.ServerSettingsService;
-      yield* settingsChanges.pipe(
+      const managedProxy = yield* ManagedProviderProxy.ManagedProviderProxy;
+      // The managed proxy's endpoint appears once it first starts and moves if its port is taken.
+      // Its stream replays the current value; reconciling unchanged entries rebuilds nothing.
+      yield* Stream.merge(settingsChanges, managedProxy.endpointChanges).pipe(
         Stream.runForEach(() =>
           // The subscription predates the seed read, so a queued change can be
           // older than the seed. A failed current read must leave the registry intact.
-          serverSettings.getSettings.pipe(
-            Effect.flatMap((current) =>
-              mutator.reconcile(deriveProviderInstanceConfigMap(current)),
+          Effect.all([serverSettings.getSettings, managedProxy.endpoint]).pipe(
+            Effect.flatMap(([current, endpoint]) =>
+              mutator.reconcile(deriveProviderInstanceConfigMap(current, endpoint)),
             ),
             Effect.catchCause((cause) =>
               Effect.logError("ProviderInstanceRegistry reconcile failed", cause),
@@ -170,10 +171,11 @@ export const layer: Layer.Layer<
     const initialSettings: ServerSettings | undefined = yield* serverSettings.getSettings.pipe(
       Effect.orElseSucceed(() => undefined),
     );
+    const managedProxy = yield* ManagedProviderProxy.ManagedProviderProxy;
     const initialConfigMap =
       initialSettings === undefined
         ? ({} as ProviderInstanceRegistryMutator.ProviderInstanceRuntimeMap)
-        : deriveProviderInstanceConfigMap(initialSettings);
+        : deriveProviderInstanceConfigMap(initialSettings, yield* managedProxy.endpoint);
 
     const layerMutable = ProviderInstanceRegistry.layer({
       drivers: BUILT_IN_DRIVERS,
diff --git a/apps/server/src/provider/ProviderRegistry.test.ts b/apps/server/src/provider/ProviderRegistry.test.ts
index 14b8dfb2ca150..9ffa52c40b7e8 100644
--- a/apps/server/src/provider/ProviderRegistry.test.ts
+++ b/apps/server/src/provider/ProviderRegistry.test.ts
@@ -1,5 +1,6 @@
 import { vi } from "vite-plus/test";
 import * as ServerSecretStore from "../auth/ServerSecretStore.ts";
+import * as ManagedProviderProxy from "../providerProxy/ManagedProviderProxy.ts";
 import * as CodexInstallation from "./CodexInstallation.ts";
 import * as CodexManagedTokenBroker from "./CodexManagedTokenBroker.ts";
 import * as ServerEnvironment from "../environment/ServerEnvironment.ts";
@@ -313,6 +314,7 @@ const layerTestNodeServices = Layer.mergeAll(
     managedDirectory: "unused-managed-installation",
   }),
   Layer.mock(ServerSecretStore.ServerSecretStore)({}),
+  ManagedProviderProxy.ManagedProviderProxy.layerTest(),
   Layer.succeed(ServerEnvironment.ServerEnvironmentIdentity, {
     getEnvironmentId: Effect.succeed(EnvironmentId.make("00000000-0000-4000-8000-000000000001")),
   }),
diff --git a/apps/server/src/providerProxy/CliProxyApiBinary.ts b/apps/server/src/providerProxy/CliProxyApiBinary.ts
new file mode 100644
index 0000000000000..495f74c311aee
--- /dev/null
+++ b/apps/server/src/providerProxy/CliProxyApiBinary.ts
@@ -0,0 +1,295 @@
+/** The pinned CLIProxyAPI release T3 downloads into T3 home, following the cloudflared pattern. */
+import * as HostProcess from "@t3tools/shared/HostProcess";
+import { isWindowsRenameLock } from "@t3tools/shared/atomicWrite";
+import * as Context from "effect/Context";
+import * as Crypto from "effect/Crypto";
+import * as Effect from "effect/Effect";
+import * as Hex from "effect/encoding/Hex";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as Schedule from "effect/Schedule";
+import * as Schema from "effect/Schema";
+import * as Semaphore from "effect/Semaphore";
+import { HttpClient, HttpClientRequest, HttpClientResponse } from "effect/http";
+import { ChildProcess, ChildProcessSpawner } from "effect/process";
+
+import * as ServerConfig from "../config.ts";
+
+const CLIPROXYAPI_VERSION = "8.0.47";
+const CLIPROXYAPI_PATH_ENV_NAME = "T3CODE_CLIPROXYAPI_PATH";
+const DOWNLOAD_TIMEOUT = "10 minutes";
+const VERSION_PROBE_TIMEOUT = "10 seconds";
+const ACTIVATE_RETRY_COUNT = 40;
+const ACTIVATE_RETRY_DELAY = "250 millis";
+
+interface ReleaseAsset {
+  readonly url: string;
+  readonly sha256: string;
+  readonly archive: "tgz" | "zip";
+}
+
+const releaseAsset = (name: string, sha256: string): ReleaseAsset => ({
+  url: `https://github.com/router-for-me/CLIProxyAPI/releases/download/v${CLIPROXYAPI_VERSION}/CLIProxyAPI_${CLIPROXYAPI_VERSION}_${name}`,
+  sha256,
+  archive: name.endsWith(".zip") ? "zip" : "tgz",
+});
+
+// From the release's checksums.txt, which matches GitHub's asset digests.
+const RELEASE_ASSETS: Readonly<Partial<Record<`${NodeJS.Platform}-${string}`, ReleaseAsset>>> = {
+  "darwin-arm64": releaseAsset(
+    "darwin_aarch64.tar.gz",
+    "a5b260ec0f843d2291488acd76e5595232da8f3b8ec2d334154f1570f5f3ca08",
+  ),
+  "darwin-x64": releaseAsset(
+    "darwin_amd64.tar.gz",
+    "2e72cb7b28905b9135563e4fc01af00009ce72a444729eb95bdb634543ce7d41",
+  ),
+  "linux-arm64": releaseAsset(
+    "linux_aarch64.tar.gz",
+    "da1326ed4434fb6c9609927f317c093f9a4bb482a61e5451e9bea99a0dc7c4bf",
+  ),
+  "linux-x64": releaseAsset(
+    "linux_amd64.tar.gz",
+    "2b5111dc6a0dfe0d607457787f794330d1b477bc9daa6337c26b0cd032a7827e",
+  ),
+  "win32-arm64": releaseAsset(
+    "windows_aarch64.zip",
+    "9a947eec7234e5a2e2ce57a9fe55c82328fc823ffd2f41cca85f9da41d11eae0",
+  ),
+  "win32-x64": releaseAsset(
+    "windows_amd64.zip",
+    "8e23cbb2f9f695411b7df46320855820b352fb886c3c3bdf45ab4634f2f14632",
+  ),
+};
+
+export type CliProxyApiBinaryStatus =
+  | {
+      readonly status: "available";
+      readonly executablePath: string;
+      readonly source: "override" | "managed";
+      readonly version: string;
+    }
+  | { readonly status: "missing" }
+  | { readonly status: "unsupported"; readonly platform: string; readonly arch: string };
+export type AvailableCliProxyApiBinary = Extract<
+  CliProxyApiBinaryStatus,
+  { readonly status: "available" }
+>;
+
+export class CliProxyApiInstallError extends Schema.TaggedError<CliProxyApiInstallError>()(
+  "CliProxyApiInstallError",
+  {
+    reason: Schema.Literals([
+      "download_failed",
+      "invalid_checksum",
+      "override_invalid",
+      "unsupported_platform",
+      "validation_failed",
+      "write_failed",
+    ]),
+    cause: Schema.optional(Schema.Defect()),
+  },
+) {
+  override get message(): string {
+    switch (this.reason) {
+      case "download_failed":
+        return "Could not download CLIProxyAPI.";
+      case "invalid_checksum":
+        return "The CLIProxyAPI download did not match the pinned checksum.";
+      case "override_invalid":
+        return `${CLIPROXYAPI_PATH_ENV_NAME} does not point to a working CLIProxyAPI.`;
+      case "unsupported_platform":
+        return "CLIProxyAPI has no build for this platform.";
+      case "validation_failed":
+        return `The downloaded CLIProxyAPI did not report version ${CLIPROXYAPI_VERSION}.`;
+      case "write_failed":
+        return "Could not install CLIProxyAPI into T3 home.";
+    }
+  }
+}
+
+/** `-help` prints `CLIProxyAPI Version: 8.0.47, Commit: ...` before the usage text. */
+export function parseCliProxyApiVersionOutput(output: string): string | null {
+  return /\bCLIProxyAPI Version: v?(\d+\.\d+\.\d+)\b/u.exec(output)?.[1] ?? null;
+}
+
+export class CliProxyApiBinary extends Context.Service<
+  CliProxyApiBinary,
+  {
+    readonly resolve: Effect.Effect<CliProxyApiBinaryStatus>;
+    /** Downloads the pinned release. Callers own consent: only a user choosing a managed proxy. */
+    readonly install: Effect.Effect<AvailableCliProxyApiBinary, CliProxyApiInstallError>;
+  }
+>()("t3/providerProxy/CliProxyApiBinary") {}
+
+const make = Effect.gen(function* () {
+  const crypto = yield* Crypto.Crypto;
+  const fileSystem = yield* FileSystem.FileSystem;
+  const httpClient = yield* HttpClient.HttpClient;
+  const path = yield* Path.Path;
+  const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+  const config = yield* ServerConfig.ServerConfig;
+  const platform = yield* HostProcess.Platform;
+  const arch = yield* HostProcess.Architecture;
+  const installSemaphore = yield* Semaphore.make(1);
+  const asset = RELEASE_ASSETS[`${platform}-${arch}`];
+  const executableName = platform === "win32" ? "cli-proxy-api.exe" : "cli-proxy-api";
+  const managedPath = path.join(
+    config.baseDir,
+    "tools",
+    "cliproxyapi",
+    CLIPROXYAPI_VERSION,
+    `${platform}-${arch}`,
+    executableName,
+  );
+
+  const probeVersion = Effect.fn("CliProxyApiBinary.probeVersion")(function* (
+    executablePath: string,
+  ) {
+    const info = yield* fileSystem.stat(executablePath).pipe(Effect.option);
+    if (Option.isNone(info) || info.value.type !== "File") return null;
+    if (platform !== "win32" && (info.value.mode & 0o111) === 0) return null;
+    return yield* spawner
+      .string(ChildProcess.make(executablePath, ["-help"], { stdin: "ignore", stderr: "ignore" }))
+      .pipe(
+        Effect.map(parseCliProxyApiVersionOutput),
+        Effect.timeoutOption(VERSION_PROBE_TIMEOUT),
+        Effect.map(Option.getOrNull),
+        Effect.orElseSucceed(() => null),
+      );
+  });
+
+  const override = Effect.gen(function* () {
+    const value = (yield* HostProcess.Environment)[CLIPROXYAPI_PATH_ENV_NAME]?.trim();
+    return value === undefined || value === "" ? null : value;
+  });
+
+  const resolve: CliProxyApiBinary["Service"]["resolve"] = Effect.gen(function* () {
+    const overridePath = yield* override;
+    if (overridePath !== null) {
+      const version = yield* probeVersion(overridePath);
+      if (version !== null) {
+        return {
+          status: "available",
+          executablePath: overridePath,
+          source: "override",
+          version,
+        } satisfies CliProxyApiBinaryStatus;
+      }
+      yield* Effect.logWarning(`${CLIPROXYAPI_PATH_ENV_NAME} does not point to CLIProxyAPI`);
+      return { status: "missing" } satisfies CliProxyApiBinaryStatus;
+    }
+    if ((yield* probeVersion(managedPath)) === CLIPROXYAPI_VERSION) {
+      return {
+        status: "available",
+        executablePath: managedPath,
+        source: "managed",
+        version: CLIPROXYAPI_VERSION,
+      } satisfies CliProxyApiBinaryStatus;
+    }
+    return asset === undefined
+      ? ({ status: "unsupported", platform, arch } satisfies CliProxyApiBinaryStatus)
+      : ({ status: "missing" } satisfies CliProxyApiBinaryStatus);
+  }).pipe(Effect.withSpan("CliProxyApiBinary.resolve"));
+
+  const failWith =
+    (reason: CliProxyApiInstallError["reason"]) =>
+    <A, E, R>(effect: Effect.Effect<A, E, R>) =>
+      effect.pipe(Effect.mapError((cause) => new CliProxyApiInstallError({ reason, cause })));
+
+  const download = Effect.fn("CliProxyApiBinary.download")(function* (release: ReleaseAsset) {
+    const bytes = yield* httpClient.execute(HttpClientRequest.get(release.url)).pipe(
+      Effect.flatMap(HttpClientResponse.filterStatusOk),
+      Effect.flatMap((response) => response.arrayBuffer),
+      Effect.timeout(DOWNLOAD_TIMEOUT),
+      failWith("download_failed"),
+    );
+    const data = new Uint8Array(bytes);
+    const digest = yield* crypto.digest("SHA-256", data).pipe(failWith("validation_failed"));
+    if (Hex.encode(digest) !== release.sha256) {
+      return yield* new CliProxyApiInstallError({ reason: "invalid_checksum" });
+    }
+    return data;
+  });
+
+  const extract = Effect.fn("CliProxyApiBinary.extract")(function* (
+    archivePath: string,
+    directory: string,
+    archive: ReleaseAsset["archive"],
+  ) {
+    // bsdtar, which Windows ships, also reads zip archives.
+    const child = yield* spawner.spawn(
+      ChildProcess.make(
+        "tar",
+        [archive === "tgz" ? "-xzf" : "-xf", archivePath, "-C", directory, executableName],
+        { shell: false, stdin: "ignore", stdout: "ignore", stderr: "ignore" },
+      ),
+    );
+    const exitCode = Number(yield* child.exitCode);
+    if (exitCode !== 0) {
+      return yield* new CliProxyApiInstallError({ reason: "write_failed" });
+    }
+  });
+
+  const renameWhenUnlocked = (from: string, to: string) =>
+    fileSystem.rename(from, to).pipe(
+      Effect.retry({
+        times: ACTIVATE_RETRY_COUNT,
+        schedule: Schedule.spaced(ACTIVATE_RETRY_DELAY),
+        while: (error) => platform === "win32" && isWindowsRenameLock(error),
+      }),
+    );
+
+  const installUnlocked = Effect.gen(function* () {
+    const current = yield* resolve;
+    if (current.status === "available") return current;
+    if ((yield* override) !== null) {
+      return yield* new CliProxyApiInstallError({ reason: "override_invalid" });
+    }
+    if (asset === undefined) {
+      return yield* new CliProxyApiInstallError({ reason: "unsupported_platform" });
+    }
+    const managedDirectory = path.dirname(managedPath);
+    yield* fileSystem
+      .makeDirectory(managedDirectory, { recursive: true })
+      .pipe(failWith("write_failed"));
+    const staging = yield* fileSystem
+      .makeTempDirectoryScoped({ directory: managedDirectory, prefix: ".install-" })
+      .pipe(failWith("write_failed"));
+    const archivePath = path.join(staging, asset.archive === "tgz" ? "release.tgz" : "release.zip");
+    yield* Effect.logInfo("Downloading CLIProxyAPI", { version: CLIPROXYAPI_VERSION });
+    const bytes = yield* download(asset);
+    yield* fileSystem.writeFile(archivePath, bytes).pipe(failWith("write_failed"));
+    yield* extract(archivePath, staging, asset.archive).pipe(
+      Effect.catchTags({
+        PlatformError: (cause) =>
+          Effect.fail(new CliProxyApiInstallError({ reason: "write_failed", cause })),
+      }),
+    );
+    const stagedExecutable = path.join(staging, executableName);
+    if (platform !== "win32") {
+      yield* fileSystem.chmod(stagedExecutable, 0o755).pipe(failWith("write_failed"));
+    }
+    // A mislabeled asset would otherwise be redownloaded on every start.
+    if ((yield* probeVersion(stagedExecutable)) !== CLIPROXYAPI_VERSION) {
+      return yield* new CliProxyApiInstallError({ reason: "validation_failed" });
+    }
+    yield* renameWhenUnlocked(stagedExecutable, managedPath).pipe(failWith("write_failed"));
+    return {
+      status: "available",
+      executablePath: managedPath,
+      source: "managed",
+      version: CLIPROXYAPI_VERSION,
+    } satisfies AvailableCliProxyApiBinary;
+  }).pipe(Effect.scoped);
+
+  const install: CliProxyApiBinary["Service"]["install"] = installSemaphore
+    .withPermit(installUnlocked)
+    .pipe(Effect.withSpan("CliProxyApiBinary.install"));
+
+  return CliProxyApiBinary.of({ resolve, install });
+});
+
+export const layer = Layer.effect(CliProxyApiBinary, make);
diff --git a/apps/server/src/providerProxy/ManagedProviderProxy.test.ts b/apps/server/src/providerProxy/ManagedProviderProxy.test.ts
new file mode 100644
index 0000000000000..9fc02991325e9
--- /dev/null
+++ b/apps/server/src/providerProxy/ManagedProviderProxy.test.ts
@@ -0,0 +1,42 @@
+import { describe, expect, it } from "vite-plus/test";
+import { parse as parseYaml } from "yaml";
+
+import { parseCliProxyApiVersionOutput } from "./CliProxyApiBinary.ts";
+import { renderCliProxyApiConfig } from "./ManagedProviderProxy.ts";
+
+describe("renderCliProxyApiConfig", () => {
+  it("writes CLIProxyAPI's v8 layout: loopback, one client key, a management key, sticky sessions", () => {
+    const config = parseYaml(
+      renderCliProxyApiConfig({
+        port: 41234,
+        apiKey: 'client"key',
+        managementKey: "mgmt\\key",
+        authDir: "C:\\Users\\me\\.t3\\userdata\\cliproxyapi\\auths",
+      }),
+    );
+
+    expect(config).toEqual({
+      "config-version": 8,
+      server: { host: "127.0.0.1", port: 41234 },
+      management: {
+        "allow-remote": false,
+        "secret-key": "mgmt\\key",
+        "disable-control-panel": true,
+      },
+      access: { "api-keys": ['client"key'] },
+      routing: { "session-affinity": true },
+      oauth: { "auth-dir": "C:\\Users\\me\\.t3\\userdata\\cliproxyapi\\auths" },
+    });
+  });
+});
+
+describe("parseCliProxyApiVersionOutput", () => {
+  it("reads the version CLIProxyAPI prints before its usage text", () => {
+    expect(
+      parseCliProxyApiVersionOutput(
+        "CLIProxyAPI Version: 8.0.47, Commit: 90c447d3, BuiltAt: 2026-10-29T00:27:53Z\nUsage of cli-proxy-api\n",
+      ),
+    ).toBe("8.0.47");
+    expect(parseCliProxyApiVersionOutput("Usage of cli-proxy-api\n  -config string\n")).toBeNull();
+  });
+});
diff --git a/apps/server/src/providerProxy/ManagedProviderProxy.ts b/apps/server/src/providerProxy/ManagedProviderProxy.ts
new file mode 100644
index 0000000000000..a1763f3e2578c
--- /dev/null
+++ b/apps/server/src/providerProxy/ManagedProviderProxy.ts
@@ -0,0 +1,311 @@
+/** Runs CLIProxyAPI on loopback while `providerProxy.host` is `managed`, restarting it with backoff. */
+import {
+  providerProxyHost,
+  type ProviderProxyRuntimeStatus,
+  type ServerSettings as ServerSettingsSchema,
+} from "@t3tools/contracts";
+import * as NetService from "@t3tools/shared/Net";
+import * as Clock from "effect/Clock";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as FiberHandle from "effect/FiberHandle";
+import * as FileSystem from "effect/FileSystem";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Path from "effect/Path";
+import * as Semaphore from "effect/Semaphore";
+import * as Stream from "effect/Stream";
+import * as SubscriptionRef from "effect/SubscriptionRef";
+import { ChildProcess, ChildProcessSpawner } from "effect/process";
+
+import * as ServerSecretStore from "../auth/ServerSecretStore.ts";
+import * as ServerConfig from "../config.ts";
+import * as ServerSettings from "../serverSettings.ts";
+import * as CliProxyApiBinary from "./CliProxyApiBinary.ts";
+import type { ManagedProxyEndpoint } from "./effectiveProxy.ts";
+
+const API_KEY_SECRET = "provider-proxy-managed-api-key";
+const MANAGEMENT_KEY_SECRET = "provider-proxy-managed-management-key";
+const PORT_SECRET = "provider-proxy-managed-port";
+const LOOPBACK_HOST = "127.0.0.1";
+const READY_LINE = /\bAPI server started successfully\b/u;
+// An instantly failing proxy would otherwise respawn in a tight loop.
+const RESTART_STABLE_UPTIME_MS = 30_000;
+const RESTART_BACKOFF_BASE_MS = 1_000;
+const RESTART_BACKOFF_MAX_MS = 60_000;
+// A failed download is retried no sooner than this, so an offline host does not redownload in a loop.
+const INSTALL_RETRY_MS = 10 * 60_000;
+
+/** CLIProxyAPI's v8 config layout. T3 rewrites it before every start. */
+export function renderCliProxyApiConfig(input: {
+  readonly port: number;
+  readonly apiKey: string;
+  readonly managementKey: string;
+  readonly authDir: string;
+}): string {
+  // JSON strings are valid YAML double-quoted scalars, including escaped Windows paths.
+  const quote = JSON.stringify;
+  return [
+    "# Written by T3 Code before each start; edits are replaced.",
+    "config-version: 8",
+    "server:",
+    `  host: ${quote(LOOPBACK_HOST)}`,
+    `  port: ${input.port}`,
+    "management:",
+    "  allow-remote: false",
+    `  secret-key: ${quote(input.managementKey)}`,
+    "  disable-control-panel: true",
+    "access:",
+    "  api-keys:",
+    `    - ${quote(input.apiKey)}`,
+    "routing:",
+    // A thread stays on one account, which also keeps prompt caching working.
+    "  session-affinity: true",
+    "oauth:",
+    `  auth-dir: ${quote(input.authDir)}`,
+    "",
+  ].join("\n");
+}
+
+export class ManagedProviderProxy extends Context.Service<
+  ManagedProviderProxy,
+  {
+    readonly status: Effect.Effect<ProviderProxyRuntimeStatus>;
+    /** Emits the current status, then each change. */
+    readonly statusChanges: Stream.Stream<ProviderProxyRuntimeStatus>;
+    /** Stable across restarts; `undefined` until the host was first set to `managed`. */
+    readonly endpoint: Effect.Effect<ManagedProxyEndpoint | undefined>;
+    /** Emits the current endpoint, then each change. */
+    readonly endpointChanges: Stream.Stream<ManagedProxyEndpoint | undefined>;
+  }
+>()("t3/providerProxy/ManagedProviderProxy") {
+  /** No proxy process; `endpoint` stands in for one that already started. */
+  static readonly layerTest = (endpoint?: ManagedProxyEndpoint) =>
+    Layer.succeed(ManagedProviderProxy, {
+      status: Effect.succeed<ProviderProxyRuntimeStatus>({
+        status: endpoint === undefined ? "stopped" : "running",
+      }),
+      statusChanges: Stream.empty,
+      endpoint: Effect.succeed(endpoint),
+      endpointChanges: Stream.make(endpoint),
+    });
+}
+
+const make = Effect.gen(function* () {
+  const settings = yield* ServerSettings.ServerSettingsService;
+  const secrets = yield* ServerSecretStore.ServerSecretStore;
+  const binary = yield* CliProxyApiBinary.CliProxyApiBinary;
+  const net = yield* NetService.NetService;
+  const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
+  const fileSystem = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
+  const config = yield* ServerConfig.ServerConfig;
+  const dataDir = path.join(config.stateDir, "cliproxyapi");
+  const authDir = path.join(dataDir, "auths");
+  const configPath = path.join(dataDir, "config.yaml");
+
+  const statusRef = yield* SubscriptionRef.make<ProviderProxyRuntimeStatus>({ status: "stopped" });
+  const endpointRef = yield* SubscriptionRef.make<ManagedProxyEndpoint | undefined>(undefined);
+  const setStatus = (status: ProviderProxyRuntimeStatus) => SubscriptionRef.set(statusRef, status);
+
+  const text = (bytes: Uint8Array) => new TextDecoder().decode(bytes);
+  const randomKey = (name: string) =>
+    secrets
+      .getOrCreateRandom(name, 32)
+      .pipe(Effect.map((bytes) => Buffer.from(bytes).toString("base64url")));
+  const savedPort = secrets
+    .get(PORT_SECRET)
+    .pipe(
+      Effect.map(Option.map((bytes) => Number(text(bytes)))),
+      Effect.map(Option.filter((port) => Number.isInteger(port) && port > 0 && port < 65_536)),
+    );
+  const toEndpoint = (port: number, apiKey: string, managementKey: string) => ({
+    url: `http://${LOOPBACK_HOST}:${port}`,
+    apiKey,
+    managementKey,
+  });
+
+  const loadEndpoint = Effect.gen(function* () {
+    const port = yield* savedPort;
+    if (Option.isNone(port)) return undefined;
+    const apiKey = yield* secrets.get(API_KEY_SECRET);
+    const managementKey = yield* secrets.get(MANAGEMENT_KEY_SECRET);
+    if (Option.isNone(apiKey) || Option.isNone(managementKey)) return undefined;
+    return toEndpoint(
+      port.value,
+      Buffer.from(apiKey.value).toString("base64url"),
+      Buffer.from(managementKey.value).toString("base64url"),
+    );
+  });
+
+  // Keeps the saved port while it is free, so proxied instances do not rebuild on every restart.
+  const prepareEndpoint = Effect.fn("ManagedProviderProxy.prepareEndpoint")(function* () {
+    const apiKey = yield* randomKey(API_KEY_SECRET);
+    const managementKey = yield* randomKey(MANAGEMENT_KEY_SECRET);
+    const saved = yield* savedPort;
+    const port =
+      Option.isSome(saved) && (yield* net.canListenOnHost(saved.value, LOOPBACK_HOST))
+        ? saved.value
+        : yield* net.reserveLoopbackPort(LOOPBACK_HOST);
+    if (Option.getOrUndefined(saved) !== port) {
+      yield* secrets.set(PORT_SECRET, new TextEncoder().encode(String(port)));
+    }
+    const endpoint = toEndpoint(port, apiKey, managementKey);
+    const previous = yield* SubscriptionRef.get(endpointRef);
+    if (
+      previous?.url !== endpoint.url ||
+      previous.apiKey !== endpoint.apiKey ||
+      previous.managementKey !== endpoint.managementKey
+    ) {
+      yield* SubscriptionRef.set(endpointRef, endpoint);
+    }
+    return { port, apiKey, managementKey };
+  });
+
+  const writeConfig = Effect.fn("ManagedProviderProxy.writeConfig")(function* (input: {
+    readonly port: number;
+    readonly apiKey: string;
+    readonly managementKey: string;
+  }) {
+    yield* fileSystem.makeDirectory(authDir, { recursive: true });
+    yield* fileSystem.chmod(dataDir, 0o700);
+    // The file holds the keys until CLIProxyAPI hashes the management key on startup.
+    yield* fileSystem.writeFileString(configPath, renderCliProxyApiConfig({ ...input, authDir }), {
+      mode: 0o600,
+    });
+    yield* fileSystem.chmod(configPath, 0o600);
+  });
+
+  const ensureBinary = Effect.gen(function* () {
+    const resolved = yield* binary.resolve;
+    if (resolved.status === "available") return resolved;
+    if (resolved.status === "unsupported") {
+      return yield* Effect.fail(
+        `CLIProxyAPI has no build for ${resolved.platform}-${resolved.arch}.` as const,
+      );
+    }
+    yield* setStatus({ status: "installing" });
+    return yield* binary.install.pipe(Effect.mapError((error) => error.message));
+  });
+
+  /** One proxy process, from start to exit. Fails with a message the status can show. */
+  const runOnce = Effect.fn("ManagedProviderProxy.runOnce")(function* (
+    executable: CliProxyApiBinary.AvailableCliProxyApiBinary,
+  ) {
+    const keys = yield* prepareEndpoint();
+    yield* writeConfig(keys);
+    yield* setStatus({ status: "starting", version: executable.version });
+    const child = yield* spawner.spawn(
+      ChildProcess.make(executable.executablePath, ["-config", configPath], {
+        cwd: dataDir,
+        shell: false,
+        detached: false,
+        stdin: "ignore",
+        stdout: "pipe",
+        stderr: "pipe",
+      }),
+    );
+    yield* Effect.logInfo("CLIProxyAPI started", {
+      pid: Number(child.pid),
+      version: executable.version,
+      source: executable.source,
+    });
+    // Output lines are per-event work for the life of the process; keep them untraced.
+    yield* child.all.pipe(
+      Stream.decodeText(),
+      Stream.splitLines,
+      Stream.runForEach(
+        Effect.fnUntraced(function* (line) {
+          if (READY_LINE.test(line)) {
+            yield* setStatus({ status: "running", version: executable.version });
+          }
+          const output = line
+            .replaceAll(keys.apiKey, "<redacted>")
+            .replaceAll(keys.managementKey, "<redacted>");
+          if (/\[(?:warn|warning|error|fatal|panic)\]/iu.test(line)) {
+            yield* Effect.logWarning("CLIProxyAPI output", { output });
+          } else {
+            yield* Effect.logDebug("CLIProxyAPI output", { output });
+          }
+        }),
+      ),
+      Effect.ignore,
+      Effect.forkScoped,
+    );
+    const exitCode = Number(yield* child.exitCode);
+    return yield* Effect.fail(`CLIProxyAPI exited with code ${exitCode}.`);
+  }, Effect.scoped);
+
+  const supervise = Effect.gen(function* () {
+    let restartDelay = 0;
+    while (true) {
+      const executable = yield* Effect.result(ensureBinary);
+      if (executable._tag === "Failure") {
+        yield* setStatus({ status: "error", message: executable.failure });
+        yield* Effect.logWarning("Could not prepare CLIProxyAPI", { reason: executable.failure });
+        yield* Effect.sleep(INSTALL_RETRY_MS);
+        continue;
+      }
+      const startedAt = yield* Clock.currentTimeMillis;
+      const result = yield* runOnce(executable.success).pipe(
+        Effect.catch((error) =>
+          typeof error === "string"
+            ? Effect.succeed(error)
+            : Effect.logWarning("Could not start CLIProxyAPI", { cause: error }).pipe(
+                Effect.as("Could not start CLIProxyAPI."),
+              ),
+        ),
+      );
+      const uptime = (yield* Clock.currentTimeMillis) - startedAt;
+      restartDelay =
+        uptime >= RESTART_STABLE_UPTIME_MS
+          ? RESTART_BACKOFF_BASE_MS
+          : Math.min(Math.max(restartDelay * 2, RESTART_BACKOFF_BASE_MS), RESTART_BACKOFF_MAX_MS);
+      yield* setStatus({ status: "error", message: result });
+      yield* Effect.logWarning("CLIProxyAPI stopped; restarting", { reason: result, restartDelay });
+      yield* Effect.sleep(restartDelay);
+    }
+  });
+
+  const supervisor = yield* FiberHandle.make<never, never>();
+  const applySemaphore = yield* Semaphore.make(1);
+  let appliedManaged = false;
+  const apply = Effect.fn("ManagedProviderProxy.apply")(function* (managed: boolean) {
+    if (managed === appliedManaged) return;
+    appliedManaged = managed;
+    yield* FiberHandle.clear(supervisor);
+    if (!managed) {
+      yield* setStatus({ status: "stopped" });
+      return;
+    }
+    yield* FiberHandle.run(supervisor, supervise);
+  }, applySemaphore.withPermits(1));
+
+  const initialEndpoint = yield* loadEndpoint.pipe(Effect.orElseSucceed(() => undefined));
+  if (initialEndpoint !== undefined) yield* SubscriptionRef.set(endpointRef, initialEndpoint);
+
+  const isManaged = (current: ServerSettingsSchema) =>
+    providerProxyHost(current.providerProxy) === "managed";
+  // Subscribe before the seed read so a save in between is not lost.
+  const changes = yield* settings.subscribeChanges;
+  const initialManaged = yield* settings.getSettings.pipe(
+    Effect.map(isManaged),
+    Effect.orElseSucceed(() => false),
+  );
+  yield* apply(initialManaged);
+  yield* changes.pipe(
+    Stream.map(isManaged),
+    Stream.changes,
+    Stream.runForEach(apply),
+    Effect.forkScoped,
+  );
+
+  return ManagedProviderProxy.of({
+    status: SubscriptionRef.get(statusRef),
+    statusChanges: SubscriptionRef.changes(statusRef),
+    endpoint: SubscriptionRef.get(endpointRef),
+    endpointChanges: SubscriptionRef.changes(endpointRef),
+  });
+});
+
+export const layer = Layer.effect(ManagedProviderProxy, make);
diff --git a/apps/server/src/providerProxy/ProxyAccounts.test.ts b/apps/server/src/providerProxy/ProxyAccounts.test.ts
new file mode 100644
index 0000000000000..10a0a6547d6ef
--- /dev/null
+++ b/apps/server/src/providerProxy/ProxyAccounts.test.ts
@@ -0,0 +1,234 @@
+import { it as effectIt } from "@effect/vitest";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import { HttpClient, type HttpClientRequest, HttpClientResponse, UrlParams } from "effect/http";
+import { describe, expect, it } from "vite-plus/test";
+
+import * as ServerSettings from "../serverSettings.ts";
+import * as ManagedProviderProxy from "./ManagedProviderProxy.ts";
+import * as ProxyAccounts from "./ProxyAccounts.ts";
+
+const now = DateTime.makeUnsafe("2026-10-30T00:00:00Z");
+
+describe("toProviderProxyAccount", () => {
+  it.each([
+    [
+      "an active account",
+      { name: "claude-a.json", provider: "claude", email: "a@example.test", status: "active" },
+      { name: "claude-a.json", provider: "claude", email: "a@example.test", state: "active" },
+    ],
+    [
+      "a disabled account",
+      { name: "codex-b.json", type: "codex", disabled: true, status: "disabled" },
+      { name: "codex-b.json", provider: "codex", state: "disabled" },
+    ],
+    [
+      "a cooling-down account",
+      {
+        name: "codex-c.json",
+        provider: "codex",
+        account: "c@example.test",
+        status: "error",
+        status_message: "quota exhausted",
+        unavailable: true,
+        next_retry_after: "2026-10-30T02:00:00Z",
+      },
+      {
+        name: "codex-c.json",
+        provider: "codex",
+        email: "c@example.test",
+        state: "cooldown",
+        statusMessage: "quota exhausted",
+        retryAt: "2026-10-30T02:00:00.000Z",
+      },
+    ],
+    [
+      "a failing account whose retry time passed",
+      {
+        name: "claude-d.json",
+        provider: "claude",
+        status: "error",
+        status_message: "token expired",
+        unavailable: true,
+        next_retry_after: "2026-10-29T23:00:00Z",
+      },
+      { name: "claude-d.json", provider: "claude", state: "error", statusMessage: "token expired" },
+    ],
+  ])("maps %s", (_label, file, account) => {
+    expect(ProxyAccounts.toProviderProxyAccount(file, now)).toEqual(account);
+  });
+
+  it("skips config-defined API keys, which have no credential file to manage", () => {
+    expect(
+      ProxyAccounts.toProviderProxyAccount(
+        { name: "gemini-api-key", provider: "gemini", runtime_only: true },
+        now,
+      ),
+    ).toBeUndefined();
+  });
+});
+
+const fullUrl = (request: HttpClientRequest.HttpClientRequest) => {
+  const query = UrlParams.toString(request.urlParams);
+  return query === "" ? request.url : `${request.url}?${query}`;
+};
+const bodyText = (request: HttpClientRequest.HttpClientRequest) =>
+  request.body._tag === "Uint8Array" ? new TextDecoder().decode(request.body.body) : "";
+
+interface Recorded {
+  readonly method: string;
+  readonly url: string;
+  readonly authorization: string | undefined;
+  readonly body: string;
+}
+
+/** A fake management API answering by `METHOD path`; unlisted routes answer 404. */
+const managementApi = (
+  routes: Record<string, { readonly status?: number; readonly body: unknown }>,
+  recorded: Array<Recorded>,
+) =>
+  HttpClient.make((request) => {
+    const url = fullUrl(request);
+    recorded.push({
+      method: request.method,
+      url,
+      authorization: request.headers.authorization,
+      body: bodyText(request),
+    });
+    const path = url.replace("http://proxy.test:8317/v0/management/", "");
+    const route = routes[`${request.method} ${path}`];
+    return Effect.succeed(
+      HttpClientResponse.fromWeb(
+        request,
+        route === undefined
+          ? Response.json({ error: "not found" }, { status: 404 })
+          : Response.json(route.body, { status: route.status ?? 200 }),
+      ),
+    );
+  });
+
+const withProxy = (client: HttpClient.HttpClient) =>
+  Effect.provide(
+    ProxyAccounts.layer.pipe(
+      Layer.provide(
+        Layer.mergeAll(
+          ServerSettings.layerTest({
+            providerProxy: {
+              host: "external",
+              url: "http://proxy.test:8317/v1",
+              apiKey: "",
+              managementKey: "mgmt-key",
+            },
+          }),
+          ManagedProviderProxy.ManagedProviderProxy.layerTest(),
+          Layer.succeed(HttpClient.HttpClient, client),
+        ),
+      ),
+    ),
+  );
+
+describe("ProxyAccounts", () => {
+  effectIt.effect("lists, disables, and removes accounts with the management key", () => {
+    const recorded: Array<Recorded> = [];
+    return Effect.gen(function* () {
+      const accounts = yield* ProxyAccounts.ProxyAccounts;
+      const state = yield* accounts.getState;
+      expect(state.accounts).toEqual([
+        { name: "claude-a.json", provider: "claude", email: "a@example.test", state: "active" },
+      ]);
+      yield* accounts.setAccountDisabled({ name: "claude-a.json", disabled: true });
+      yield* accounts.removeAccount("claude a.json");
+      const missing = yield* accounts.removeAccount("gone.json").pipe(Effect.flip);
+      expect(missing.detail).toBe("The proxy answered with HTTP 404: auth file not found.");
+
+      expect(recorded.map(({ method, url }) => `${method} ${url}`)).toEqual([
+        "GET http://proxy.test:8317/v0/management/auth-files",
+        "PATCH http://proxy.test:8317/v0/management/auth-files/status",
+        "DELETE http://proxy.test:8317/v0/management/auth-files?name=claude%20a.json",
+        "DELETE http://proxy.test:8317/v0/management/auth-files?name=gone.json",
+      ]);
+      expect(recorded.every((request) => request.authorization === "Bearer mgmt-key")).toBe(true);
+      expect(JSON.parse(recorded[1]!.body)).toEqual({ name: "claude-a.json", disabled: true });
+    }).pipe(
+      withProxy(
+        managementApi(
+          {
+            "GET auth-files": {
+              body: {
+                files: [
+                  { name: "claude-a.json", provider: "claude", email: "a@example.test" },
+                  { name: "gemini-key", provider: "gemini", runtime_only: true },
+                ],
+              },
+            },
+            "PATCH auth-files/status": { body: { status: "ok" } },
+            "DELETE auth-files?name=claude%20a.json": { body: { status: "ok" } },
+            "DELETE auth-files?name=gone.json": {
+              status: 404,
+              body: { error: "auth file not found" },
+            },
+          },
+          recorded,
+        ),
+      ),
+    );
+  });
+
+  effectIt.effect(
+    "signs in with paste-back when the proxy cannot catch the redirect itself",
+    () => {
+      const recorded: Array<Recorded> = [];
+      return Effect.gen(function* () {
+        const accounts = yield* ProxyAccounts.ProxyAccounts;
+        const login = yield* accounts.startLogin("claude");
+        expect(login).toEqual({ url: "https://claude.ai/oauth/authorize?x=1", state: "abc123" });
+        expect(yield* accounts.getLoginStatus("abc123")).toEqual({ status: "wait" });
+
+        const wrongLogin = yield* accounts
+          .completeLogin({
+            state: "abc123",
+            redirectUrl: "http://localhost:54545/callback?code=c&state=other",
+          })
+          .pipe(Effect.flip);
+        expect(wrongLogin._tag).toBe("ProviderProxyError");
+        yield* accounts.completeLogin({
+          state: "abc123",
+          redirectUrl: "http://localhost:54545/callback?code=c&state=abc123",
+        });
+
+        expect(recorded.map(({ method, url }) => `${method} ${url}`)).toEqual([
+          // The callback port was taken, so the proxy refused to catch the redirect.
+          "GET http://proxy.test:8317/v0/management/anthropic-auth-url?is_webui=true",
+          "GET http://proxy.test:8317/v0/management/anthropic-auth-url",
+          "GET http://proxy.test:8317/v0/management/get-auth-status?state=abc123",
+          "POST http://proxy.test:8317/v0/management/oauth-callback",
+        ]);
+        expect(JSON.parse(recorded[3]!.body)).toEqual({
+          redirect_url: "http://localhost:54545/callback?code=c&state=abc123",
+        });
+      }).pipe(
+        withProxy(
+          managementApi(
+            {
+              "GET anthropic-auth-url?is_webui=true": {
+                status: 500,
+                body: { error: "failed to start callback server" },
+              },
+              "GET anthropic-auth-url": {
+                body: {
+                  status: "ok",
+                  url: "https://claude.ai/oauth/authorize?x=1",
+                  state: "abc123",
+                },
+              },
+              "GET get-auth-status?state=abc123": { body: { status: "wait" } },
+              "POST oauth-callback": { body: { status: "ok" } },
+            },
+            recorded,
+          ),
+        ),
+      );
+    },
+  );
+});
diff --git a/apps/server/src/providerProxy/ProxyAccounts.ts b/apps/server/src/providerProxy/ProxyAccounts.ts
new file mode 100644
index 0000000000000..883f3ed228eb8
--- /dev/null
+++ b/apps/server/src/providerProxy/ProxyAccounts.ts
@@ -0,0 +1,320 @@
+/** The proxy's pooled accounts, through CLIProxyAPI's `/v0/management` API. */
+import {
+  providerProxyHost,
+  ProviderProxyError,
+  type ProviderProxyAccount,
+  type ProviderProxyLogin,
+  type ProviderProxyLoginProvider,
+  type ProviderProxyLoginStatus,
+  type ProviderProxyRuntimeStatus,
+  type ProviderProxyState,
+} from "@t3tools/contracts";
+import * as Cause from "effect/Cause";
+import * as Context from "effect/Context";
+import * as DateTime from "effect/DateTime";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import * as Option from "effect/Option";
+import * as Schema from "effect/Schema";
+import { HttpClient, HttpClientRequest } from "effect/http";
+
+import * as ServerSettings from "../serverSettings.ts";
+import { resolveProxyManagement, type ProxyManagementEndpoint } from "./effectiveProxy.ts";
+import * as ManagedProviderProxy from "./ManagedProviderProxy.ts";
+
+const OptionalText = Schema.optional(Schema.NullOr(Schema.String));
+const AuthFile = Schema.Struct({
+  name: Schema.String,
+  provider: OptionalText,
+  type: OptionalText,
+  email: OptionalText,
+  account: OptionalText,
+  label: OptionalText,
+  status: OptionalText,
+  status_message: OptionalText,
+  disabled: Schema.optional(Schema.NullOr(Schema.Boolean)),
+  unavailable: Schema.optional(Schema.NullOr(Schema.Boolean)),
+  runtime_only: Schema.optional(Schema.NullOr(Schema.Boolean)),
+  next_retry_after: OptionalText,
+});
+export type CliProxyAuthFile = typeof AuthFile.Type;
+const decodeAuthFiles = Schema.decodeUnknownEffect(
+  Schema.Struct({ files: Schema.Array(AuthFile) }),
+);
+const decodeLogin = Schema.decodeUnknownEffect(
+  Schema.Struct({ url: Schema.String, state: Schema.String }),
+);
+const decodeLoginStatus = Schema.decodeUnknownEffect(
+  Schema.Struct({
+    status: Schema.Literals(["ok", "wait", "error"]),
+    error: OptionalText,
+  }),
+);
+const decodeErrorBody = Schema.decodeUnknownOption(Schema.Struct({ error: Schema.String }));
+
+const REQUEST_TIMEOUT = "15 seconds";
+const MAX_PROXY_MESSAGE_LENGTH = 200;
+// CLIProxyAPI names the Claude login after its upstream.
+const LOGIN_PATHS: Record<ProviderProxyLoginProvider, string> = {
+  claude: "anthropic-auth-url",
+  codex: "codex-auth-url",
+};
+
+const nonEmpty = (value: string | null | undefined) => {
+  const trimmed = value?.trim();
+  return trimmed === undefined || trimmed === "" ? undefined : trimmed;
+};
+const bounded = (value: string) =>
+  value.length > MAX_PROXY_MESSAGE_LENGTH ? `${value.slice(0, MAX_PROXY_MESSAGE_LENGTH)}…` : value;
+
+/** Maps one `auth-files` entry; config-defined API keys have no file to manage and are skipped. */
+export function toProviderProxyAccount(
+  file: CliProxyAuthFile,
+  now: DateTime.Utc,
+): ProviderProxyAccount | undefined {
+  const name = nonEmpty(file.name);
+  const provider = nonEmpty(file.provider) ?? nonEmpty(file.type);
+  if (name === undefined || provider === undefined || file.runtime_only === true) return undefined;
+  const email = nonEmpty(file.email) ?? nonEmpty(file.account) ?? nonEmpty(file.label);
+  const retryAt = Option.flatMap(Option.fromNullishOr(nonEmpty(file.next_retry_after)), (value) =>
+    Option.filter(DateTime.make(value), (at) => DateTime.isGreaterThan(at, now)),
+  );
+  const state: ProviderProxyAccount["state"] =
+    file.disabled === true || file.status === "disabled"
+      ? "disabled"
+      : Option.isSome(retryAt)
+        ? "cooldown"
+        : file.status === "error" || file.unavailable === true
+          ? "error"
+          : "active";
+  const statusMessage = state === "active" ? undefined : nonEmpty(file.status_message);
+  return {
+    name,
+    provider,
+    ...(email === undefined ? {} : { email }),
+    state,
+    ...(statusMessage === undefined ? {} : { statusMessage: bounded(statusMessage) }),
+    ...(state === "cooldown" && Option.isSome(retryAt)
+      ? { retryAt: DateTime.formatIso(retryAt.value) }
+      : {}),
+  };
+}
+
+/** The pasted URL must belong to the sign-in it completes. */
+function redirectUrlMatchesLogin(redirectUrl: string, state: string): boolean {
+  try {
+    return new URL(redirectUrl).searchParams.get("state") === state;
+  } catch {
+    return false;
+  }
+}
+
+export class ProxyAccounts extends Context.Service<
+  ProxyAccounts,
+  {
+    readonly getState: Effect.Effect<ProviderProxyState>;
+    readonly startLogin: (
+      provider: ProviderProxyLoginProvider,
+    ) => Effect.Effect<ProviderProxyLogin, ProviderProxyError>;
+    readonly getLoginStatus: (
+      state: string,
+    ) => Effect.Effect<ProviderProxyLoginStatus, ProviderProxyError>;
+    readonly completeLogin: (input: {
+      readonly state: string;
+      readonly redirectUrl: string;
+    }) => Effect.Effect<void, ProviderProxyError>;
+    readonly setAccountDisabled: (input: {
+      readonly name: string;
+      readonly disabled: boolean;
+    }) => Effect.Effect<void, ProviderProxyError>;
+    readonly removeAccount: (name: string) => Effect.Effect<void, ProviderProxyError>;
+  }
+>()("t3/providerProxy/ProxyAccounts") {}
+
+const make = Effect.gen(function* () {
+  const client = yield* HttpClient.HttpClient;
+  const settingsService = yield* ServerSettings.ServerSettingsService;
+  const managed = yield* ManagedProviderProxy.ManagedProviderProxy;
+
+  const context = Effect.gen(function* () {
+    const settings = yield* settingsService.getSettings.pipe(
+      Effect.mapError(() => new ProviderProxyError({ detail: "Could not read proxy settings." })),
+    );
+    const host = providerProxyHost(settings.providerProxy);
+    const runtime: ProviderProxyRuntimeStatus =
+      host === "managed" ? yield* managed.status : { status: "stopped" };
+    const management = resolveProxyManagement(settings, yield* managed.endpoint);
+    return { host, runtime, management };
+  });
+
+  const requireManagement = context.pipe(
+    Effect.flatMap(({ management }) =>
+      management === undefined
+        ? Effect.fail(
+            new ProviderProxyError({
+              detail:
+                "This environment cannot manage the proxy's accounts. Run the proxy here, or add the external proxy's management key.",
+            }),
+          )
+        : Effect.succeed(management),
+    ),
+  );
+
+  const request = Effect.fn("ProxyAccounts.request")(function* (
+    management: ProxyManagementEndpoint,
+    build: (url: string) => HttpClientRequest.HttpClientRequest,
+    path: string,
+  ) {
+    const response = yield* client
+      .execute(
+        build(`${management.url}/v0/management/${path}`).pipe(
+          HttpClientRequest.bearerToken(management.managementKey),
+        ),
+      )
+      .pipe(
+        Effect.timeout(REQUEST_TIMEOUT),
+        Effect.mapError(
+          (error) =>
+            new ProviderProxyError({
+              detail: Cause.isTimeoutError(error)
+                ? "The proxy did not answer within 15 seconds."
+                : "Could not reach the proxy.",
+            }),
+        ),
+      );
+    const body = yield* response.json.pipe(Effect.orElseSucceed((): unknown => null));
+    if (response.status >= 200 && response.status < 300) return body;
+    // CLIProxyAPI's own error strings, such as "auth file not found", carry no credentials.
+    const proxyMessage = Option.match(decodeErrorBody(body), {
+      onNone: () => "",
+      onSome: ({ error }) => `: ${bounded(error)}`,
+    });
+    return yield* new ProviderProxyError({
+      detail: `The proxy answered with HTTP ${response.status}${proxyMessage}.`,
+    });
+  });
+
+  const malformed = () =>
+    new ProviderProxyError({ detail: "The proxy sent a response T3 Code does not understand." });
+
+  const getState: ProxyAccounts["Service"]["getState"] = Effect.gen(function* () {
+    const { host, runtime, management } = yield* context;
+    // A managed proxy that is not up yet has no accounts to read.
+    if (management === undefined || (host === "managed" && runtime.status !== "running")) {
+      return { runtime, accounts: null } satisfies ProviderProxyState;
+    }
+    return yield* request(management, HttpClientRequest.get, "auth-files").pipe(
+      Effect.flatMap((body) => decodeAuthFiles(body).pipe(Effect.mapError(malformed))),
+      Effect.flatMap(({ files }) =>
+        DateTime.now.pipe(
+          Effect.map((now) => files.flatMap((file) => toProviderProxyAccount(file, now) ?? [])),
+        ),
+      ),
+      Effect.map((accounts): ProviderProxyState => ({ runtime, accounts })),
+      Effect.catchTags({
+        ProviderProxyError: (error) =>
+          Effect.succeed({
+            runtime,
+            accounts: [],
+            accountsError: error.detail,
+          } satisfies ProviderProxyState),
+      }),
+    );
+  }).pipe(
+    Effect.catchTags({
+      ProviderProxyError: () =>
+        Effect.succeed({
+          runtime: { status: "stopped" },
+          accounts: null,
+        } satisfies ProviderProxyState),
+    }),
+    Effect.withSpan("ProxyAccounts.getState"),
+  );
+
+  const startLogin = Effect.fn("ProxyAccounts.startLogin")(function* (
+    provider: ProviderProxyLoginProvider,
+  ) {
+    const management = yield* requireManagement;
+    const path = LOGIN_PATHS[provider];
+    // `is_webui` makes the proxy catch the browser's localhost redirect itself, which finishes
+    // the sign-in without a paste when the browser runs on the proxy's machine. It needs the
+    // provider's fixed callback port, so fall back to paste-back when that port is taken.
+    const body = yield* request(management, HttpClientRequest.get, `${path}?is_webui=true`).pipe(
+      Effect.catchTags({
+        ProviderProxyError: () => request(management, HttpClientRequest.get, path),
+      }),
+    );
+    return yield* decodeLogin(body).pipe(Effect.mapError(malformed));
+  });
+
+  const getLoginStatus = Effect.fn("ProxyAccounts.getLoginStatus")(function* (state: string) {
+    const management = yield* requireManagement;
+    const body = yield* request(
+      management,
+      HttpClientRequest.get,
+      `get-auth-status?state=${encodeURIComponent(state)}`,
+    );
+    const status = yield* decodeLoginStatus(body).pipe(Effect.mapError(malformed));
+    const message = nonEmpty(status.error);
+    return {
+      status: status.status,
+      ...(message === undefined ? {} : { message: bounded(message) }),
+    } satisfies ProviderProxyLoginStatus;
+  });
+
+  const completeLogin = Effect.fn("ProxyAccounts.completeLogin")(function* (input: {
+    readonly state: string;
+    readonly redirectUrl: string;
+  }) {
+    if (!redirectUrlMatchesLogin(input.redirectUrl, input.state)) {
+      return yield* new ProviderProxyError({
+        detail:
+          "Paste the full address from this sign-in's browser tab, including ?code=…&state=….",
+      });
+    }
+    const management = yield* requireManagement;
+    yield* request(
+      management,
+      (url) =>
+        HttpClientRequest.post(url).pipe(
+          HttpClientRequest.bodyJsonUnsafe({ redirect_url: input.redirectUrl }),
+        ),
+      "oauth-callback",
+    );
+  });
+
+  const setAccountDisabled = Effect.fn("ProxyAccounts.setAccountDisabled")(function* (input: {
+    readonly name: string;
+    readonly disabled: boolean;
+  }) {
+    const management = yield* requireManagement;
+    yield* request(
+      management,
+      (url) =>
+        HttpClientRequest.patch(url).pipe(
+          HttpClientRequest.bodyJsonUnsafe({ name: input.name, disabled: input.disabled }),
+        ),
+      "auth-files/status",
+    );
+  });
+
+  const removeAccount = Effect.fn("ProxyAccounts.removeAccount")(function* (name: string) {
+    const management = yield* requireManagement;
+    yield* request(
+      management,
+      HttpClientRequest.delete,
+      `auth-files?name=${encodeURIComponent(name)}`,
+    );
+  });
+
+  return ProxyAccounts.of({
+    getState,
+    startLogin,
+    getLoginStatus,
+    completeLogin,
+    setAccountDisabled,
+    removeAccount,
+  });
+});
+
+export const layer = Layer.effect(ProxyAccounts, make);
diff --git a/apps/server/src/providerProxy/effectiveProxy.ts b/apps/server/src/providerProxy/effectiveProxy.ts
new file mode 100644
index 0000000000000..8ff4c73f21878
--- /dev/null
+++ b/apps/server/src/providerProxy/effectiveProxy.ts
@@ -0,0 +1,54 @@
+import { providerProxyHost, type ServerSettings } from "@t3tools/contracts";
+import {
+  normalizeProviderProxyUrl,
+  type ProviderProxyRoute,
+} from "@t3tools/provider-core/server/providerProxy";
+
+/** The loopback CLIProxyAPI this environment runs; its keys live in the secret store. */
+export interface ManagedProxyEndpoint {
+  readonly url: string;
+  readonly apiKey: string;
+  readonly managementKey: string;
+}
+
+export interface ProxyManagementEndpoint {
+  readonly url: string;
+  readonly managementKey: string;
+}
+
+/** Where `useProxy` instances send model traffic, or `undefined` when there is no proxy. */
+export function resolveProviderProxyRoute(
+  settings: ServerSettings,
+  managed: ManagedProxyEndpoint | undefined,
+): ProviderProxyRoute | undefined {
+  switch (providerProxyHost(settings.providerProxy)) {
+    case "off":
+      return undefined;
+    case "managed":
+      return managed === undefined ? undefined : { url: managed.url, apiKey: managed.apiKey };
+    case "external": {
+      const url = normalizeProviderProxyUrl(settings.providerProxy.url);
+      return url === "" ? undefined : { url, apiKey: settings.providerProxy.apiKey };
+    }
+  }
+}
+
+/** The proxy whose management API this environment may call: accounts and usage limits. */
+export function resolveProxyManagement(
+  settings: ServerSettings,
+  managed: ManagedProxyEndpoint | undefined,
+): ProxyManagementEndpoint | undefined {
+  switch (providerProxyHost(settings.providerProxy)) {
+    case "off":
+      return undefined;
+    case "managed":
+      return managed === undefined
+        ? undefined
+        : { url: managed.url, managementKey: managed.managementKey };
+    case "external": {
+      const url = normalizeProviderProxyUrl(settings.providerProxy.url);
+      const { managementKey } = settings.providerProxy;
+      return url === "" || managementKey === "" ? undefined : { url, managementKey };
+    }
+  }
+}
diff --git a/apps/server/src/server.ts b/apps/server/src/server.ts
index 741fc73103b7d..6616a20bae9b5 100644
--- a/apps/server/src/server.ts
+++ b/apps/server/src/server.ts
@@ -102,6 +102,9 @@ import * as ProviderAdapterRegistry from "./orchestration-v2/ProviderAdapterRegi
 import * as ProviderRegistry from "./provider/ProviderRegistry.ts";
 import * as ProviderUsageLimitsIngestion from "./provider/ProviderUsageLimitsIngestion.ts";
 import * as UsageLimitSources from "./usage/UsageLimitSources.ts";
+import * as CliProxyApiBinary from "./providerProxy/CliProxyApiBinary.ts";
+import * as ManagedProviderProxy from "./providerProxy/ManagedProviderProxy.ts";
+import * as ProxyAccounts from "./providerProxy/ProxyAccounts.ts";
 import * as ProjectFaviconResolver from "./project/ProjectFaviconResolver.ts";
 import * as T3ProjectFileLoader from "./project/T3ProjectFileLoader.ts";
 import * as RepositoryIdentityResolver from "./project/RepositoryIdentityResolver.ts";
@@ -486,6 +489,13 @@ const layerAuth = EnvironmentAuth.layer.pipe(
   Layer.provide(ServerSecretStore.layer),
 );
 
+const layerProviderProxy = ProxyAccounts.layer.pipe(
+  Layer.provideMerge(ManagedProviderProxy.layer),
+  Layer.provide(CliProxyApiBinary.layer),
+  Layer.provide(ServerSecretStore.layer),
+  Layer.provide(NetService.layer),
+);
+
 const layerCloudManagedEndpointRuntime = Layer.mergeAll(
   layerRelayClient,
   CloudManagedEndpointRuntime.layer.pipe(
@@ -639,6 +649,7 @@ const layerRuntimeCoreDependenciesBase = Layer.mergeAll(
   ),
   Layer.provideMerge(ProviderRegistry.layer),
   Layer.provideMerge(ProviderInstanceRegistryHydration.layer),
+  Layer.provideMerge(layerProviderProxy),
   // Provider hydration builds the Claude runner, which reports agents to the same scanner the
   // terminal and preview layers share.
   Layer.provideMerge(layerPortScanner),
diff --git a/apps/server/src/usage/UsageLimitSources.test.ts b/apps/server/src/usage/UsageLimitSources.test.ts
index abeecc001685b..d2baab1fe8ff8 100644
--- a/apps/server/src/usage/UsageLimitSources.test.ts
+++ b/apps/server/src/usage/UsageLimitSources.test.ts
@@ -11,6 +11,7 @@ import * as Schema from "effect/Schema";
 import { HttpClient } from "effect/http";
 
 import * as BackgroundPolicy from "../background/BackgroundPolicy.ts";
+import * as ManagedProviderProxy from "../providerProxy/ManagedProviderProxy.ts";
 import * as ServerSettings from "../serverSettings.ts";
 import * as UsageLimitSources from "./UsageLimitSources.ts";
 
@@ -78,6 +79,7 @@ it.effect("keeps malformed source URLs encodable for config subscribers", () =>
       Layer.mock(BackgroundPolicy.BackgroundPolicy)({
         shouldRunScopeWork: () => Effect.succeed(false),
       }),
+      ManagedProviderProxy.ManagedProviderProxy.layerTest(),
       Layer.succeed(
         HttpClient.HttpClient,
         HttpClient.make(() => Effect.die("Unexpected network request")),
@@ -129,4 +131,23 @@ it("reports the routing proxy's accounts unless a hub already points at it or ow
       UsageLimitSources.effectiveUsageLimitSources({ ...settings, usageLimitSources: listed }),
     ).toBe(listed);
   }
+
+  // A managed proxy reports through its own loopback management key; turning the host off hides it.
+  const managed = { url: "http://127.0.0.1:41234", apiKey: "sk", managementKey: "managed-mgmt" };
+  const managedSettings = {
+    ...settings,
+    providerProxy: { ...settings.providerProxy, host: "managed" as const },
+  };
+  expect(
+    UsageLimitSources.effectiveUsageLimitSources(managedSettings, managed)[
+      UsageLimitSources.PROVIDER_PROXY_SOURCE_ID
+    ],
+  ).toMatchObject({ url: "http://127.0.0.1:41234", managementKey: "managed-mgmt" });
+  expect(UsageLimitSources.effectiveUsageLimitSources(managedSettings)).toEqual({});
+  expect(
+    UsageLimitSources.effectiveUsageLimitSources(
+      { ...settings, providerProxy: { ...settings.providerProxy, host: "off" } },
+      managed,
+    ),
+  ).toEqual({});
 });
diff --git a/apps/server/src/usage/UsageLimitSources.ts b/apps/server/src/usage/UsageLimitSources.ts
index e9510f7f4755a..a5674a2fd14c5 100644
--- a/apps/server/src/usage/UsageLimitSources.ts
+++ b/apps/server/src/usage/UsageLimitSources.ts
@@ -9,6 +9,11 @@ import {
   type UsageLimitSourceSnapshot,
 } from "@t3tools/contracts";
 import { normalizeProviderProxyUrl } from "@t3tools/provider-core/server/providerProxy";
+import {
+  resolveProxyManagement,
+  type ManagedProxyEndpoint,
+} from "../providerProxy/effectiveProxy.ts";
+import * as ManagedProviderProxy from "../providerProxy/ManagedProviderProxy.ts";
 import { resolveServerBackgroundActivitySettings } from "@t3tools/shared/backgroundActivitySettings";
 import * as Context from "effect/Context";
 import * as DateTime from "effect/DateTime";
@@ -52,10 +57,11 @@ export const PROVIDER_PROXY_SOURCE_ID = "provider-proxy" as UsageLimitSourceId;
 /** The routing proxy reports its accounts without a separate hub entry, unless one already points at it. */
 export function effectiveUsageLimitSources(
   settings: ServerSettings,
+  managedProxy?: ManagedProxyEndpoint,
 ): Readonly<Record<string, UsageLimitSourceConfig>> {
-  const url = normalizeProviderProxyUrl(settings.providerProxy.url);
-  const { managementKey } = settings.providerProxy;
-  if (url === "" || managementKey === "") return settings.usageLimitSources;
+  const management = resolveProxyManagement(settings, managedProxy);
+  if (management === undefined) return settings.usageLimitSources;
+  const { url, managementKey } = management;
   const alreadyListed = Object.values(settings.usageLimitSources).some(
     (source) => source.managementKey !== "" && normalizeProviderProxyUrl(source.url) === url,
   );
@@ -79,6 +85,7 @@ export function effectiveUsageLimitSources(
 export const make = Effect.gen(function* () {
   const api = yield* makeCliproxyApi;
   const settingsService = yield* Settings.ServerSettingsService;
+  const managedProxy = yield* ManagedProviderProxy.ManagedProviderProxy;
   const backgroundPolicy = yield* BackgroundPolicy.BackgroundPolicy;
   const stateRef = yield* Ref.make<ReadonlyArray<UsageLimitSourceSnapshot>>([]);
   const changes = yield* Effect.acquireRelease(
@@ -118,8 +125,9 @@ export const make = Effect.gen(function* () {
     const settings = yield* settingsService.getSettings.pipe(
       Effect.orElseSucceed((): ServerSettings | null => null),
     );
+    const endpoint = yield* managedProxy.endpoint;
     const entries = Object.entries(
-      settings === null ? {} : effectiveUsageLimitSources(settings),
+      settings === null ? {} : effectiveUsageLimitSources(settings, endpoint),
     ).filter(([, config]) => config.enabled);
     const snapshots = yield* Effect.forEach(
       entries,
@@ -136,7 +144,9 @@ export const make = Effect.gen(function* () {
     const settings = yield* settingsService.getSettings.pipe(
       Effect.mapError(() => new UsageLimitSourceError({ detail: "Could not read hub settings." })),
     );
-    const config = effectiveUsageLimitSources(settings)[input.sourceId];
+    const config = effectiveUsageLimitSources(settings, yield* managedProxy.endpoint)[
+      input.sourceId
+    ];
     if (!config?.enabled || !config.managementKey) {
       return yield* new UsageLimitSourceError({
         detail: "The usage limit source is missing or disabled.",
@@ -149,9 +159,14 @@ export const make = Effect.gen(function* () {
     return result;
   }, refreshLock.withPermits(1));
 
-  yield* settingsService.streamChanges.pipe(
-    Stream.map(effectiveUsageLimitSources),
-    Stream.changes,
+  yield* Stream.merge(
+    settingsService.streamChanges.pipe(
+      Stream.map((settings) => effectiveUsageLimitSources(settings)),
+      Stream.changes,
+    ),
+    // A managed proxy can only answer once it runs.
+    managedProxy.statusChanges.pipe(Stream.filter((status) => status.status === "running")),
+  ).pipe(
     Stream.runForEach(() => refresh),
     Effect.forkScoped,
   );
diff --git a/apps/server/src/ws.test.ts b/apps/server/src/ws.test.ts
index 2c6adce82f390..242d4245e8664 100644
--- a/apps/server/src/ws.test.ts
+++ b/apps/server/src/ws.test.ts
@@ -94,6 +94,7 @@ import * as TerminalManager from "./terminal/Manager.ts";
 import * as ThreadLaunchService from "./orchestration-v2/ThreadLaunchService.ts";
 import * as ThreadSearch from "./orchestration-v2/ThreadSearch.ts";
 import * as UsageLimitSources from "./usage/UsageLimitSources.ts";
+import * as ProxyAccounts from "./providerProxy/ProxyAccounts.ts";
 import * as UsageService from "./usage/UsageService.ts";
 import * as VcsProvisioningService from "./vcs/VcsProvisioningService.ts";
 import * as VcsStatusBroadcaster from "./vcs/VcsStatusBroadcaster.ts";
@@ -543,6 +544,7 @@ const layerUnusedConfigRpcServices = Layer.mergeAll(
   Layer.mock(ThreadManagement.ThreadManagementService)({}),
   Layer.mock(ThreadSearch.ThreadSearch)({}),
   Layer.mock(UsageService.UsageService)({}),
+  Layer.mock(ProxyAccounts.ProxyAccounts)({}),
   Layer.mock(VcsProvisioningService.VcsProvisioningService)({}),
   Layer.mock(VcsStatusBroadcaster.VcsStatusBroadcaster)({}),
   Layer.mock(WorkspaceEntries.WorkspaceEntries)({}),
diff --git a/apps/server/src/ws.ts b/apps/server/src/ws.ts
index a7ef5dedf24fb..5cf46f2faafed 100644
--- a/apps/server/src/ws.ts
+++ b/apps/server/src/ws.ts
@@ -266,6 +266,7 @@ import {
 import * as AgentSessionScanner from "./project/AgentSessionScanner.ts";
 import * as AgentSessionImporter from "./project/AgentSessionImporter.ts";
 import * as UsageLimitSources from "./usage/UsageLimitSources.ts";
+import * as ProxyAccounts from "./providerProxy/ProxyAccounts.ts";
 
 const CONFIG_DISCOVERY_TIMEOUT = Duration.seconds(5);
 const isProviderUploadFeedbackError = Schema.is(ProviderUploadFeedbackError);
@@ -1299,6 +1300,7 @@ export const layerWsRpc = (
             );
       const usage = yield* UsageService.UsageService;
       const usageLimitSources = yield* UsageLimitSources.UsageLimitSources;
+      const proxyAccounts = yield* ProxyAccounts.ProxyAccounts;
       const worktreeSetupTracker = yield* WorktreeSetupTracker.WorktreeSetupTracker;
       const projectCloneTracker = yield* ProjectCloneTracker.ProjectCloneTracker;
       const repositoryIdentityResolver =
@@ -2420,6 +2422,14 @@ export const layerWsRpc = (
           ),
         [WS_METHODS.serverUpdateProvider]: (input) =>
           providerMaintenanceRunner.updateProvider(input),
+        [WS_METHODS.providerProxyGetState]: () => proxyAccounts.getState,
+        [WS_METHODS.providerProxyStartLogin]: ({ provider }) => proxyAccounts.startLogin(provider),
+        [WS_METHODS.providerProxyGetLoginStatus]: ({ state }) =>
+          proxyAccounts.getLoginStatus(state),
+        [WS_METHODS.providerProxyCompleteLogin]: (input) => proxyAccounts.completeLogin(input),
+        [WS_METHODS.providerProxySetAccountDisabled]: (input) =>
+          proxyAccounts.setAccountDisabled(input),
+        [WS_METHODS.providerProxyRemoveAccount]: ({ name }) => proxyAccounts.removeAccount(name),
         [WS_METHODS.providerConsumeResetCredit]:
           /* Request instrumentation already owns the span; keep this helper in that context. */
           Effect.fnUntraced(function* (input) {
diff --git a/apps/web/src/components/settings/ProviderInstanceCard.tsx b/apps/web/src/components/settings/ProviderInstanceCard.tsx
index c3af4e23eccdb..c10f9e194cb7f 100644
--- a/apps/web/src/components/settings/ProviderInstanceCard.tsx
+++ b/apps/web/src/components/settings/ProviderInstanceCard.tsx
@@ -275,7 +275,7 @@ function ProviderProxyRow(props: {
         blocked ??
         (props.proxyConfigured
           ? "Send this provider's requests through the proxy and its accounts."
-          : "Add a proxy URL under Proxy in these settings first.")
+          : "Choose where the proxy runs under Proxy in these settings first.")
       }
       control={
         <Switch
@@ -631,7 +631,7 @@ interface ProviderInstanceCardProps {
   readonly onAcceptUrlAuth?: ((action: AcpRegistryUrlAuthAction) => void) | undefined;
   readonly environmentId?: EnvironmentId | undefined;
   readonly projectOverride?: ProjectOverrideControl | undefined;
-  /** Whether this environment has a proxy URL for `useProxy` to route through. */
+  /** Whether this environment has a proxy for `useProxy` to route through. */
   readonly proxyConfigured?: boolean | undefined;
   readonly acpProjects?:
     | ReadonlyArray<{
diff --git a/apps/web/src/components/settings/ProviderProxySettings.tsx b/apps/web/src/components/settings/ProviderProxySettings.tsx
index 227a8366ad434..84951f3be6cf4 100644
--- a/apps/web/src/components/settings/ProviderProxySettings.tsx
+++ b/apps/web/src/components/settings/ProviderProxySettings.tsx
@@ -1,15 +1,89 @@
-import type { EnvironmentId, UnifiedSettings } from "@t3tools/contracts";
+import { useAtomValue } from "@effect/atom-react";
+import {
+  isAtomCommandInterrupted,
+  squashAtomCommandFailure,
+} from "@t3tools/client-runtime/state/runtime";
+import {
+  type EnvironmentId,
+  type ProviderProxyAccount,
+  type ProviderProxyHost,
+  type ProviderProxyLogin,
+  type ProviderProxyLoginProvider,
+  type ProviderProxyRuntimeStatus,
+  providerProxyHost,
+  type UnifiedSettings,
+} from "@t3tools/contracts";
 import { XIcon } from "lucide-react";
+import { useState } from "react";
 
+import { requestConfirmDialog } from "~/confirmDialog";
 import { useUpdateEnvironmentSettings } from "../../hooks/useSettings";
+import { ensureLocalApi } from "../../localApi";
+import { providerProxyEnvironment } from "../../state/providerProxy";
+import { useEnvironmentQuery } from "../../state/query";
+import { useAtomCommand } from "../../state/use-atom-command";
 import { Button } from "../ui/button";
 import { DraftInput } from "../ui/draft-input";
+import { Input } from "../ui/input";
+import { Select, SelectItem, SelectPopup, SelectTrigger, SelectValue } from "../ui/select";
+import { stackedThreadToast, toastManager } from "../ui/toast";
+import { ITEM_ROW_CLASSNAME, ITEM_ROW_INNER_CLASSNAME } from "./itemRows";
 import { SecretInput } from "./SecretInput";
 import { searchableSetting } from "./settingsSearch";
 import { SettingsRow, SettingsSection } from "./settingsLayout";
 
 const CONTROL_CLASS = "w-full min-w-0 @min-[32rem]/settings-row:w-56";
 
+const HOST_LABELS: Record<ProviderProxyHost, string> = {
+  off: "Off",
+  managed: "This environment",
+  external: "External URL",
+};
+
+const HOST_DESCRIPTIONS: Record<ProviderProxyHost, string> = {
+  off: "Send Claude, Codex, and OpenCode requests through a CLIProxyAPI server, which spreads them across several accounts.",
+  managed:
+    "T3 Code downloads CLIProxyAPI from GitHub and runs it on this machine. Turn on Use proxy for a Claude, Codex, or OpenCode provider to send its requests here.",
+  external:
+    "A CLIProxyAPI server you run. Turn on Use proxy for a Claude, Codex, or OpenCode provider to send its requests here.",
+};
+
+const PROVIDER_LABELS: Readonly<Record<string, string>> = { claude: "Claude", codex: "Codex" };
+const LOGIN_PROVIDERS: ReadonlyArray<ProviderProxyLoginProvider> = ["claude", "codex"];
+
+const failureToast = (title: string, description: string) =>
+  toastManager.add(stackedThreadToast({ type: "error", title, description }));
+
+function runtimeDescription(runtime: ProviderProxyRuntimeStatus): string {
+  switch (runtime.status) {
+    case "stopped":
+      return "Stopped.";
+    case "installing":
+      return "Downloading CLIProxyAPI…";
+    case "starting":
+      return "Starting…";
+    case "running":
+      return runtime.version ? `Running CLIProxyAPI ${runtime.version}.` : "Running.";
+    case "error":
+      return runtime.message ?? "CLIProxyAPI stopped. Restarting…";
+  }
+}
+
+function accountStateDescription(account: ProviderProxyAccount): string {
+  switch (account.state) {
+    case "active":
+      return "Active";
+    case "disabled":
+      return "Disabled";
+    case "cooldown":
+      return account.retryAt
+        ? `Cooling down until ${new Date(account.retryAt).toLocaleTimeString([], { hour: "numeric", minute: "2-digit" })}`
+        : "Cooling down";
+    case "error":
+      return account.statusMessage ? `Error: ${account.statusMessage}` : "Error";
+  }
+}
+
 /** Secrets arrive redacted: any non-empty value means one is stored. */
 export function ProviderProxySettings({
   environmentId,
@@ -23,26 +97,62 @@ export function ProviderProxySettings({
   const updateSettings = useUpdateEnvironmentSettings(environmentId);
   const update = (patch: Partial<UnifiedSettings["providerProxy"]>) =>
     updateSettings({ providerProxy: patch });
+  const host = providerProxyHost(proxy);
+  const managesAccounts = host === "managed" || (host === "external" && proxy.managementKey !== "");
 
   return (
-    <SettingsSection
-      {...searchableSetting("provider-proxy")}
-      headerAction={
-        proxy.url !== "" && !readOnly ? (
-          <Button
-            size="xs"
-            variant="ghost"
-            onClick={() => update({ url: "", apiKey: "", managementKey: "" })}
-          >
-            Remove proxy
-          </Button>
-        ) : null
-      }
-    >
+    <SettingsSection {...searchableSetting("provider-proxy")}>
+      <SettingsRow
+        id="provider-proxy-host"
+        title="Proxy"
+        description={HOST_DESCRIPTIONS[host]}
+        control={
+          <div className={CONTROL_CLASS}>
+            <Select
+              value={host}
+              disabled={readOnly}
+              onValueChange={(value) => {
+                if (value === "off" || value === "managed" || value === "external") {
+                  update({ host: value });
+                }
+              }}
+            >
+              <SelectTrigger size="sm" className="w-full min-w-0" aria-label="Proxy host">
+                <SelectValue>{HOST_LABELS[host]}</SelectValue>
+              </SelectTrigger>
+              <SelectPopup align="end" alignItemWithTrigger={false}>
+                <SelectItem value="off">{HOST_LABELS.off}</SelectItem>
+                <SelectItem value="managed">{HOST_LABELS.managed}</SelectItem>
+                <SelectItem value="external">{HOST_LABELS.external}</SelectItem>
+              </SelectPopup>
+            </Select>
+          </div>
+        }
+      />
+      {host === "external" ? (
+        <ExternalProxyRows proxy={proxy} readOnly={readOnly} update={update} />
+      ) : null}
+      {managesAccounts ? (
+        <ProxyAccountRows environmentId={environmentId} showRuntime={host === "managed"} />
+      ) : null}
+    </SettingsSection>
+  );
+}
+
+function ExternalProxyRows({
+  proxy,
+  readOnly,
+  update,
+}: {
+  readonly proxy: UnifiedSettings["providerProxy"];
+  readonly readOnly: boolean;
+  readonly update: (patch: Partial<UnifiedSettings["providerProxy"]>) => void;
+}) {
+  return (
+    <>
       <SettingsRow
         id="provider-proxy-url"
         title={<label htmlFor="provider-proxy-url-input">Proxy URL</label>}
-        description="A CLIProxyAPI server. Turn on Use proxy for a Claude, Codex, or OpenCode provider to send its requests here."
         control={
           <DraftInput
             id="provider-proxy-url-input"
@@ -57,64 +167,357 @@ export function ProviderProxySettings({
           />
         }
       />
-      <SettingsRow
+      <SecretRow
         id="provider-proxy-api-key"
-        title={<label htmlFor="provider-proxy-api-key-input">API key</label>}
+        title="API key"
         description="One of the proxy's API keys. Leave empty if the proxy has none."
-        control={
-          <div className="flex w-full min-w-0 items-center gap-2 @min-[32rem]/settings-row:w-56">
-            <SecretInput
-              id="provider-proxy-api-key-input"
-              size="sm"
-              className="min-w-0 flex-1"
-              value=""
-              configured={proxy.apiKey !== ""}
-              disabled={readOnly}
-              onCommit={(apiKey) => update({ apiKey: apiKey.trim() })}
+        configured={proxy.apiKey !== ""}
+        readOnly={readOnly}
+        onCommit={(apiKey) => update({ apiKey })}
+      />
+      <SecretRow
+        id="provider-proxy-management-key"
+        title="Management key"
+        description="Optional. Lists the proxy's accounts here and under Usage → Limits."
+        configured={proxy.managementKey !== ""}
+        readOnly={readOnly}
+        onCommit={(managementKey) => update({ managementKey })}
+      />
+    </>
+  );
+}
+
+function SecretRow({
+  id,
+  title,
+  description,
+  configured,
+  readOnly,
+  onCommit,
+}: {
+  readonly id: string;
+  readonly title: string;
+  readonly description: string;
+  readonly configured: boolean;
+  readonly readOnly: boolean;
+  readonly onCommit: (value: string) => void;
+}) {
+  return (
+    <SettingsRow
+      id={id}
+      title={<label htmlFor={`${id}-input`}>{title}</label>}
+      description={description}
+      control={
+        <div className="flex w-full min-w-0 items-center gap-2 @min-[32rem]/settings-row:w-56">
+          <SecretInput
+            id={`${id}-input`}
+            size="sm"
+            className="min-w-0 flex-1"
+            value=""
+            configured={configured}
+            disabled={readOnly}
+            onCommit={(value) => onCommit(value.trim())}
+          />
+          {configured && !readOnly ? (
+            <Button
+              type="button"
+              size="icon-sm"
+              variant="ghost-destructive"
+              onClick={() => onCommit("")}
+              aria-label={`Clear ${title.toLowerCase()}`}
+            >
+              <XIcon className="size-3.5" />
+            </Button>
+          ) : null}
+        </div>
+      }
+    />
+  );
+}
+
+function ProxyAccountRows({
+  environmentId,
+  showRuntime,
+}: {
+  readonly environmentId: EnvironmentId;
+  readonly showRuntime: boolean;
+}) {
+  const state = useEnvironmentQuery(providerProxyEnvironment.state({ environmentId, input: {} }));
+  const canAdd = useAtomValue(providerProxyEnvironment.startLogin.permissionAtom(environmentId));
+  const startLogin = useAtomCommand(providerProxyEnvironment.startLogin, {
+    label: "start proxy sign-in",
+  });
+  const [login, setLogin] = useState<
+    (ProviderProxyLogin & { readonly provider: ProviderProxyLoginProvider }) | null
+  >(null);
+  const [starting, setStarting] = useState(false);
+
+  const add = async (provider: ProviderProxyLoginProvider) => {
+    setStarting(true);
+    const result = await startLogin({ environmentId, input: { provider } });
+    setStarting(false);
+    if (result._tag === "Success") setLogin({ ...result.value, provider });
+    else if (!isAtomCommandInterrupted(result)) {
+      failureToast("Could not start sign-in", String(squashAtomCommandFailure(result)));
+    }
+  };
+
+  if (state.error) {
+    return <SettingsRow title="Could not read the proxy" description={state.error} />;
+  }
+  const data = state.data;
+  if (!data) return <SettingsRow title="Loading proxy…" role="status" />;
+  const accounts = data.accounts ?? [];
+  const providers = [
+    ...new Set([...LOGIN_PROVIDERS, ...accounts.map((account) => account.provider)]),
+  ];
+
+  return (
+    <>
+      {showRuntime ? (
+        <SettingsRow
+          id="provider-proxy-status"
+          title="Status"
+          description={runtimeDescription(data.runtime)}
+          role="status"
+        />
+      ) : null}
+      {data.accountsError ? (
+        <SettingsRow title="Could not list accounts" description={data.accountsError} />
+      ) : null}
+      {data.accounts === null ? null : (
+        <SettingsRow
+          id="provider-proxy-accounts"
+          title="Accounts"
+          description={
+            accounts.length === 0
+              ? "Sign in to Claude or ChatGPT accounts. The proxy spreads requests across them."
+              : "The proxy spreads requests across active accounts and keeps each thread on one."
+          }
+          control={
+            canAdd ? (
+              <div className="flex shrink-0 items-center gap-2">
+                {LOGIN_PROVIDERS.map((provider) => (
+                  <Button
+                    key={provider}
+                    size="xs"
+                    variant="outline"
+                    disabled={starting || login !== null}
+                    onClick={() => void add(provider)}
+                  >
+                    Add {PROVIDER_LABELS[provider]}
+                  </Button>
+                ))}
+              </div>
+            ) : null
+          }
+        />
+      )}
+      {login === null ? null : (
+        <ProxyLoginRow environmentId={environmentId} login={login} onDone={() => setLogin(null)} />
+      )}
+      {providers.flatMap((provider) =>
+        accounts
+          .filter((account) => account.provider === provider)
+          .map((account) => (
+            <ProxyAccountRow
+              key={account.name}
+              environmentId={environmentId}
+              account={account}
+              providerLabel={PROVIDER_LABELS[provider] ?? provider}
             />
-            {proxy.apiKey !== "" && !readOnly ? (
-              <Button
-                type="button"
-                size="icon-sm"
-                variant="ghost-destructive"
-                onClick={() => update({ apiKey: "" })}
-                aria-label="Clear API key"
-              >
-                <XIcon className="size-3.5" />
+          )),
+      )}
+    </>
+  );
+}
+
+function ProxyLoginRow({
+  environmentId,
+  login,
+  onDone,
+}: {
+  readonly environmentId: EnvironmentId;
+  readonly login: ProviderProxyLogin & { readonly provider: ProviderProxyLoginProvider };
+  readonly onDone: () => void;
+}) {
+  const status = useEnvironmentQuery(
+    providerProxyEnvironment.loginStatus({ environmentId, input: { state: login.state } }),
+  );
+  const completeLogin = useAtomCommand(providerProxyEnvironment.completeLogin, {
+    label: "finish proxy sign-in",
+  });
+  const [redirectUrl, setRedirectUrl] = useState("");
+  const [submitting, setSubmitting] = useState(false);
+  const label = PROVIDER_LABELS[login.provider] ?? login.provider;
+  const outcome = status.data?.status;
+
+  const open = () => {
+    void ensureLocalApi()
+      .shell.openExternal(login.url)
+      .catch(() =>
+        failureToast("Could not open the sign-in page", "Copy the link and open it yourself."),
+      );
+  };
+  const submit = async () => {
+    setSubmitting(true);
+    const result = await completeLogin({
+      environmentId,
+      input: { state: login.state, redirectUrl: redirectUrl.trim() },
+    });
+    setSubmitting(false);
+    if (result._tag === "Failure" && !isAtomCommandInterrupted(result)) {
+      failureToast("Could not finish sign-in", String(squashAtomCommandFailure(result)));
+    }
+  };
+
+  const description =
+    outcome === "ok"
+      ? `${label} account added.`
+      : outcome === "error"
+        ? (status.data?.message ?? "Sign-in failed.")
+        : "Open the sign-in page. When the browser lands on a localhost address that does not load, copy that address and paste it here.";
+
+  return (
+    <div className={ITEM_ROW_CLASSNAME}>
+      <div className="space-y-3">
+        <div className={ITEM_ROW_INNER_CLASSNAME}>
+          <div className="min-w-0 flex-1 space-y-1">
+            <h3 className="text-sm font-medium text-foreground">Add a {label} account</h3>
+            <p className="text-xs text-muted-foreground" role="status">
+              {description}
+            </p>
+          </div>
+          <div className="flex shrink-0 items-center gap-2">
+            {outcome === "ok" || outcome === "error" ? (
+              <Button size="xs" variant="outline" onClick={onDone}>
+                Done
               </Button>
-            ) : null}
+            ) : (
+              <>
+                <Button size="xs" variant="outline" onClick={open}>
+                  Open sign-in page
+                </Button>
+                <Button size="xs" variant="ghost" onClick={onDone}>
+                  Cancel
+                </Button>
+              </>
+            )}
           </div>
-        }
-      />
-      <SettingsRow
-        id="provider-proxy-management-key"
-        title={<label htmlFor="provider-proxy-management-key-input">Management key</label>}
-        description="Optional. Shows the proxy's accounts under Usage → Limits."
-        control={
-          <div className="flex w-full min-w-0 items-center gap-2 @min-[32rem]/settings-row:w-56">
-            <SecretInput
-              id="provider-proxy-management-key-input"
+        </div>
+        {outcome === "ok" || outcome === "error" ? null : (
+          <form
+            className="flex items-center gap-2"
+            onSubmit={(event) => {
+              event.preventDefault();
+              if (redirectUrl.trim() !== "") void submit();
+            }}
+          >
+            <Input
               size="sm"
               className="min-w-0 flex-1"
-              value=""
-              configured={proxy.managementKey !== ""}
-              disabled={readOnly}
-              onCommit={(managementKey) => update({ managementKey: managementKey.trim() })}
+              value={redirectUrl}
+              placeholder="http://localhost:…/callback?code=…&state=…"
+              aria-label="Address the browser landed on"
+              autoComplete="off"
+              spellCheck={false}
+              onChange={(event) => setRedirectUrl(event.target.value)}
             />
-            {proxy.managementKey !== "" && !readOnly ? (
-              <Button
-                type="button"
-                size="icon-sm"
-                variant="ghost-destructive"
-                onClick={() => update({ managementKey: "" })}
-                aria-label="Clear management key"
-              >
-                <XIcon className="size-3.5" />
-              </Button>
-            ) : null}
-          </div>
-        }
-      />
-    </SettingsSection>
+            <Button
+              type="submit"
+              size="xs"
+              variant="outline"
+              disabled={submitting || redirectUrl.trim() === ""}
+            >
+              Finish
+            </Button>
+          </form>
+        )}
+      </div>
+    </div>
+  );
+}
+
+function ProxyAccountRow({
+  environmentId,
+  account,
+  providerLabel,
+}: {
+  readonly environmentId: EnvironmentId;
+  readonly account: ProviderProxyAccount;
+  readonly providerLabel: string;
+}) {
+  const setDisabled = useAtomCommand(providerProxyEnvironment.setAccountDisabled, {
+    label: "change proxy account",
+  });
+  const remove = useAtomCommand(providerProxyEnvironment.removeAccount, {
+    label: "remove proxy account",
+  });
+  const canChange = useAtomValue(
+    providerProxyEnvironment.setAccountDisabled.permissionAtom(environmentId),
+  );
+  const canRemove = useAtomValue(
+    providerProxyEnvironment.removeAccount.permissionAtom(environmentId),
+  );
+  const [busy, setBusy] = useState(false);
+  const title = account.email ?? account.name;
+  const disabled = account.state === "disabled";
+
+  const toggle = async () => {
+    setBusy(true);
+    const result = await setDisabled({
+      environmentId,
+      input: { name: account.name, disabled: !disabled },
+    });
+    setBusy(false);
+    if (result._tag === "Failure" && !isAtomCommandInterrupted(result)) {
+      failureToast(
+        disabled ? "Could not enable the account" : "Could not disable the account",
+        String(squashAtomCommandFailure(result)),
+      );
+    }
+  };
+  const removeAccount = async () => {
+    const confirmed = await (requestConfirmDialog(
+      `Remove ${title} from the proxy? Its sign-in is deleted; add it again to use it.`,
+      { variant: "destructive" },
+    ) ?? Promise.resolve(false));
+    if (!confirmed) return;
+    setBusy(true);
+    const result = await remove({ environmentId, input: { name: account.name } });
+    setBusy(false);
+    if (result._tag === "Failure" && !isAtomCommandInterrupted(result)) {
+      failureToast("Could not remove the account", String(squashAtomCommandFailure(result)));
+    }
+  };
+
+  return (
+    <div className={ITEM_ROW_CLASSNAME}>
+      <div className={ITEM_ROW_INNER_CLASSNAME}>
+        <div className="min-w-0 flex-1 space-y-1">
+          <h3 className="truncate text-sm font-medium text-foreground">{title}</h3>
+          <p className="text-xs text-muted-foreground">
+            {providerLabel} · {accountStateDescription(account)}
+          </p>
+        </div>
+        <div className="flex shrink-0 items-center gap-2">
+          {canChange ? (
+            <Button size="xs" variant="outline" disabled={busy} onClick={() => void toggle()}>
+              {disabled ? "Enable" : "Disable"}
+            </Button>
+          ) : null}
+          {canRemove ? (
+            <Button
+              size="xs"
+              variant="destructive-outline"
+              disabled={busy}
+              onClick={() => void removeAccount()}
+            >
+              Remove
+            </Button>
+          ) : null}
+        </div>
+      </div>
+    </div>
   );
 }
diff --git a/apps/web/src/components/settings/ProviderSettingsPanel.tsx b/apps/web/src/components/settings/ProviderSettingsPanel.tsx
index b456187fd9a47..d21a5f2d37f28 100644
--- a/apps/web/src/components/settings/ProviderSettingsPanel.tsx
+++ b/apps/web/src/components/settings/ProviderSettingsPanel.tsx
@@ -22,6 +22,7 @@ import {
   type ProjectId,
   type ProviderInstanceConfig,
   type ProviderInstanceId,
+  providerProxyConfigured,
   type ServerProvider,
   resolveEnvironmentMachineKind,
   resolveProjectProviderInstanceEnabled,
@@ -933,7 +934,7 @@ export function EnvironmentProviderSettings({
         canWriteSettings={canWriteSettings}
         liveProvider={serverProviders.find((candidate) => candidate.instanceId === row.instanceId)}
         isUpdateDispatching={updatingProviderInstanceIds.has(row.instanceId)}
-        proxyConfigured={settings.providerProxy.url !== ""}
+        proxyConfigured={providerProxyConfigured(settings.providerProxy)}
         showProjectOverride={showProjectOverride}
         projectOverrideValue={
           showProjectOverride
diff --git a/apps/web/src/components/settings/settingsSearch.ts b/apps/web/src/components/settings/settingsSearch.ts
index 1a86d42574e8f..6cb4483517fb9 100644
--- a/apps/web/src/components/settings/settingsSearch.ts
+++ b/apps/web/src/components/settings/settingsSearch.ts
@@ -804,7 +804,7 @@ export const SETTINGS_SEARCH_ITEMS = [
     title: "Proxy",
     to: "/settings/providers",
     searchTerms: [
-      "proxy CLIProxyAPI CLI proxy route account pool load balance api key management key base url",
+      "proxy CLIProxyAPI CLI proxy route account pool load balance api key management key base url host this environment managed external accounts add account sign in",
     ],
     providerSettingsOnly: true,
   },
diff --git a/apps/web/src/state/providerProxy.ts b/apps/web/src/state/providerProxy.ts
new file mode 100644
index 0000000000000..69d1edad164e8
--- /dev/null
+++ b/apps/web/src/state/providerProxy.ts
@@ -0,0 +1,5 @@
+import { createProviderProxyEnvironmentAtoms } from "@t3tools/client-runtime/state/providerProxy";
+
+import { connectionAtomRuntime } from "../connection/runtime";
+
+export const providerProxyEnvironment = createProviderProxyEnvironmentAtoms(connectionAtomRuntime);
diff --git a/docs/user/install.md b/docs/user/install.md
index b0a21122de4a6..209599aa9fec8 100644
--- a/docs/user/install.md
+++ b/docs/user/install.md
@@ -196,19 +196,29 @@ their original values.
 
 ### Route providers through a proxy
 
-A [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) server can serve Claude, Codex, and
-OpenCode from accounts it holds, and spread requests across several accounts. To use one, open
-**Settings → Providers → Proxy** on the environment that runs the agents. Enter the proxy's URL,
-and one of its API keys if it requires one. Add its management key to see its accounts under
-**Usage → Limits**. Then turn on **Use proxy** for each Claude, Codex, or OpenCode provider that
-should use it.
-
-A provider with **Use proxy** on never falls back to its own login. If the proxy is removed, the
-provider shows as unavailable until you add a proxy again or turn the switch off. Codex threads
-started through the proxy need it to continue. T3-managed ChatGPT sign-in and external OpenCode
-servers cannot use a proxy. While OpenCode uses the proxy, it offers only Anthropic and OpenAI
-models and runs without its plugins, because other providers and plugin logins such as ChatGPT
-would send requests around the proxy. This needs OpenCode 1.14.49 or newer, and any
+A [CLIProxyAPI](https://github.com/router-for-me/CLIProxyAPI) server can serve Claude, Codex,
+and OpenCode from accounts it holds, and spread requests across several accounts. Open
+**Settings → Providers → Proxy** on the environment that runs the agents and choose where the
+proxy runs:
+
+- **This environment.** T3 Code downloads a pinned CLIProxyAPI release from GitHub, runs it on
+  this machine for local connections only, and restarts it if it stops. Add accounts under
+  **Accounts** with **Add Claude** or **Add Codex**: open the sign-in page and sign in. If the
+  browser then lands on a `localhost` address that does not load, copy that address and paste it
+  into T3 Code. Accounts can be disabled, enabled again, or removed there.
+- **External URL.** Enter the URL of a CLIProxyAPI server you run, and one of its API keys if it
+  requires one. Add its management key to manage its accounts in the same place and see them under
+  **Usage → Limits**.
+
+Then turn on **Use proxy** for each Claude, Codex, or OpenCode provider that should use it. The
+proxy keeps each thread on one account while that account is available.
+
+A provider with **Use proxy** on never falls back to its own login. If the proxy is turned off,
+the provider shows as unavailable until you choose a proxy again or turn the switch off. Codex
+threads started through the proxy need it to continue. T3-managed ChatGPT sign-in and external
+OpenCode servers cannot use a proxy. While OpenCode uses the proxy, it offers only Anthropic and
+OpenAI models and runs without its plugins, because other providers and plugin logins such as
+ChatGPT would send requests around the proxy. This needs OpenCode 1.14.49 or newer, and any
 `OPENCODE_CONFIG_CONTENT` must be plain JSON. An OpenCode organization or managed config that
 points Anthropic or OpenAI elsewhere makes the provider unavailable. OpenCode 2 cannot use the
 proxy yet.
diff --git a/docs/user/usage.md b/docs/user/usage.md
index 86b2828aa96cd..121725df8cdfd 100644
--- a/docs/user/usage.md
+++ b/docs/user/usage.md
@@ -154,7 +154,8 @@ account and choose **Use reset** to redeem one. No hub plugin is required.
 
 This connection supplies usage information only. To send agent requests through the hub, set it
 as the environment's [proxy](./install.md#route-providers-through-a-proxy); with its management
-key there, its accounts appear here without a separate hub. Remove the hub from the same
+key there, or with the proxy running on this environment, its accounts appear here without a
+separate hub. Remove the hub from the same
 settings section when you no longer need it.
 
 ## Subscription usage widget
diff --git a/packages/client-runtime/package.json b/packages/client-runtime/package.json
index e1f81638ea3d4..f5323617599d1 100644
--- a/packages/client-runtime/package.json
+++ b/packages/client-runtime/package.json
@@ -223,6 +223,10 @@
       "types": "./src/state/peerLinks.ts",
       "default": "./src/state/peerLinks.ts"
     },
+    "./state/providerProxy": {
+      "types": "./src/state/providerProxy.ts",
+      "default": "./src/state/providerProxy.ts"
+    },
     "./state/peerPairingCode": {
       "types": "./src/state/peerPairingCode.ts",
       "default": "./src/state/peerPairingCode.ts"
diff --git a/packages/client-runtime/src/state/commandPermissions.test.ts b/packages/client-runtime/src/state/commandPermissions.test.ts
index adfad46a41b89..5ea7e986dae74 100644
--- a/packages/client-runtime/src/state/commandPermissions.test.ts
+++ b/packages/client-runtime/src/state/commandPermissions.test.ts
@@ -12,6 +12,7 @@ import {
   AuthOrchestrationOperateScope,
   AuthOrchestrationReadScope,
   AuthPreviewOperateScope,
+  AuthProvidersManageScope,
   AuthSettingsWriteScope,
   AuthSourceControlWriteScope,
   ThreadId,
@@ -122,20 +123,23 @@ describe("command permissions", () => {
     ),
   );
 
-  it.effect("requires the destination settings grant to check OTLP endpoints", () =>
+  it.effect.each([
+    [WS_METHODS.serverCheckOtlpEndpoint, AuthSettingsWriteScope],
+    // Proxy accounts serve every proxied provider, so operate permission alone is not enough.
+    [WS_METHODS.providerProxyStartLogin, AuthProvidersManageScope],
+    [WS_METHODS.providerProxyCompleteLogin, AuthProvidersManageScope],
+    [WS_METHODS.providerProxySetAccountDisabled, AuthProvidersManageScope],
+    [WS_METHODS.providerProxyRemoveAccount, AuthProvidersManageScope],
+  ] as const)("requires the destination's own grant for %s", ([method, scope]) =>
     Effect.scoped(
       Effect.gen(function* () {
         const registry = yield* setup;
-        const check = createCommandPermissions(runtime, WS_METHODS.serverCheckOtlpEndpoint);
+        const check = createCommandPermissions(runtime, method);
         registry.set(sessions(env), AsyncResult.success(grant(true)));
         expect(registry.get(check.permissionAtom(env))).toBe(false);
         registry.set(
           sessions(env),
-          AsyncResult.success({
-            ...grant(false),
-            scopes: [AuthSettingsWriteScope],
-            permissions: [AuthSettingsWriteScope],
-          }),
+          AsyncResult.success({ ...grant(false), scopes: [scope], permissions: [scope] }),
         );
         expect(registry.get(check.permissionAtom(env))).toBe(true);
         yield* check.authorize(registry, env);
diff --git a/packages/client-runtime/src/state/providerProxy.ts b/packages/client-runtime/src/state/providerProxy.ts
new file mode 100644
index 0000000000000..b9cb4926658af
--- /dev/null
+++ b/packages/client-runtime/src/state/providerProxy.ts
@@ -0,0 +1,59 @@
+import { type ProviderProxyState, WS_METHODS } from "@t3tools/contracts";
+import * as Effect from "effect/Effect";
+import type { Atom } from "effect/reactivity";
+
+import type { EnvironmentRegistry } from "../connection/registry.ts";
+import { createEnvironmentRpcCommand, createEnvironmentRpcQueryAtomFamily } from "./runtime.ts";
+
+// Install and start take seconds to minutes; nothing else changes the state on its own.
+const TRANSIENT_REFRESH_MS = 2_000;
+const isSettledRuntime = (state: ProviderProxyState) =>
+  state.runtime.status !== "installing" && state.runtime.status !== "starting";
+
+export function createProviderProxyEnvironmentAtoms<R, E>(
+  runtime: Atom.AtomRuntime<EnvironmentRegistry | R, E>,
+) {
+  const state = createEnvironmentRpcQueryAtomFamily(runtime, {
+    label: "environment-data:provider-proxy:state",
+    tag: WS_METHODS.providerProxyGetState,
+    staleTimeMs: 5_000,
+    refreshIntervalMs: TRANSIENT_REFRESH_MS,
+    isFinal: isSettledRuntime,
+  });
+  // A sign-in finishes in the browser, so its status is read until it settles.
+  const loginStatus = createEnvironmentRpcQueryAtomFamily(runtime, {
+    label: "environment-data:provider-proxy:login-status",
+    tag: WS_METHODS.providerProxyGetLoginStatus,
+    staleTimeMs: 0,
+    refreshIntervalMs: TRANSIENT_REFRESH_MS,
+    isFinal: (status) => status.status !== "wait",
+    onAnswer: ({ environmentId }, status, registry) =>
+      status.status === "ok"
+        ? Effect.sync(() => registry.refresh(state({ environmentId, input: {} })))
+        : Effect.void,
+  });
+  return {
+    state,
+    loginStatus,
+    startLogin: createEnvironmentRpcCommand(runtime, {
+      label: "environment-data:provider-proxy:start-login",
+      tag: WS_METHODS.providerProxyStartLogin,
+    }),
+    completeLogin: createEnvironmentRpcCommand(runtime, {
+      label: "environment-data:provider-proxy:complete-login",
+      tag: WS_METHODS.providerProxyCompleteLogin,
+    }),
+    setAccountDisabled: createEnvironmentRpcCommand(runtime, {
+      label: "environment-data:provider-proxy:set-account-disabled",
+      tag: WS_METHODS.providerProxySetAccountDisabled,
+      onSuccess: ({ environmentId }, registry) =>
+        Effect.sync(() => registry.refresh(state({ environmentId, input: {} }))),
+    }),
+    removeAccount: createEnvironmentRpcCommand(runtime, {
+      label: "environment-data:provider-proxy:remove-account",
+      tag: WS_METHODS.providerProxyRemoveAccount,
+      onSuccess: ({ environmentId }, registry) =>
+        Effect.sync(() => registry.refresh(state({ environmentId, input: {} }))),
+    }),
+  };
+}
diff --git a/packages/contracts/src/clientRpcPermissions.ts b/packages/contracts/src/clientRpcPermissions.ts
index f9564b2e2441c..5a435858ff2a2 100644
--- a/packages/contracts/src/clientRpcPermissions.ts
+++ b/packages/contracts/src/clientRpcPermissions.ts
@@ -5,6 +5,7 @@ import {
   AuthOrchestrationOperateScope,
   AuthOrchestrationReadScope,
   AuthPreviewOperateScope,
+  AuthProvidersManageScope,
   AuthSettingsWriteScope,
   AuthSourceControlWriteScope,
   AuthTerminalOperateScope,
@@ -20,6 +21,11 @@ export const CLIENT_GUARDED_RPC_SCOPES = {
   [WS_METHODS.previewStopLocalServer]: AuthTerminalOperateScope,
   [WS_METHODS.serverRunStorageCleanup]: AuthSettingsWriteScope,
   [WS_METHODS.serverCheckOtlpEndpoint]: AuthSettingsWriteScope,
+  // Proxy accounts serve every proxied provider instance, like provider sign-in.
+  [WS_METHODS.providerProxyStartLogin]: AuthProvidersManageScope,
+  [WS_METHODS.providerProxyCompleteLogin]: AuthProvidersManageScope,
+  [WS_METHODS.providerProxySetAccountDisabled]: AuthProvidersManageScope,
+  [WS_METHODS.providerProxyRemoveAccount]: AuthProvidersManageScope,
   [WS_METHODS.pullRequestsRunAction]: AuthSourceControlWriteScope,
   [WS_METHODS.pullRequestsUpdate]: AuthSourceControlWriteScope,
   [WS_METHODS.pullRequestsComment]: AuthSourceControlWriteScope,
diff --git a/packages/contracts/src/index.ts b/packages/contracts/src/index.ts
index e61597e52ecdb..fb282ad42fb81 100644
--- a/packages/contracts/src/index.ts
+++ b/packages/contracts/src/index.ts
@@ -19,6 +19,7 @@ export * from "./providerInstance.ts";
 export * from "./providerSetup.ts";
 export * from "./providerRuntime.ts";
 export * from "./providerUsageLimits.ts";
+export * from "./providerProxy.ts";
 export * from "./usageLimitSourceId.ts";
 export * from "./providerPolicy.ts";
 export * from "./modelSelection.ts";
diff --git a/packages/contracts/src/providerProxy.ts b/packages/contracts/src/providerProxy.ts
new file mode 100644
index 0000000000000..e0ae16510eade
--- /dev/null
+++ b/packages/contracts/src/providerProxy.ts
@@ -0,0 +1,92 @@
+import * as Schema from "effect/Schema";
+
+import { IsoDateTime, TrimmedNonEmptyString } from "./baseSchemas.ts";
+
+/** Where `useProxy` provider instances send model traffic. */
+export const ProviderProxyHost = Schema.Literals(["off", "managed", "external"]);
+export type ProviderProxyHost = typeof ProviderProxyHost.Type;
+
+/** Settings saved before `host` existed meant "external" whenever a URL was set. */
+export const providerProxyHost = (proxy: {
+  readonly host?: ProviderProxyHost | undefined;
+  readonly url: string;
+}): ProviderProxyHost => proxy.host ?? (proxy.url === "" ? "off" : "external");
+
+/** Whether `useProxy` instances have somewhere to send requests. */
+export const providerProxyConfigured = (proxy: {
+  readonly host?: ProviderProxyHost | undefined;
+  readonly url: string;
+}): boolean => {
+  const host = providerProxyHost(proxy);
+  return host === "managed" || (host === "external" && proxy.url !== "");
+};
+
+/** The CLIProxyAPI process this environment runs when the host is `managed`. */
+export const ProviderProxyRuntimeStatus = Schema.Struct({
+  status: Schema.Literals(["stopped", "installing", "starting", "running", "error"]),
+  version: Schema.optionalKey(TrimmedNonEmptyString),
+  message: Schema.optionalKey(TrimmedNonEmptyString),
+});
+export type ProviderProxyRuntimeStatus = typeof ProviderProxyRuntimeStatus.Type;
+
+export const ProviderProxyAccount = Schema.Struct({
+  /** The proxy's credential file name; account operations address it. */
+  name: TrimmedNonEmptyString,
+  /** The proxy's provider id, such as `claude` or `codex`. */
+  provider: TrimmedNonEmptyString,
+  email: Schema.optionalKey(TrimmedNonEmptyString),
+  state: Schema.Literals(["active", "disabled", "cooldown", "error"]),
+  statusMessage: Schema.optionalKey(TrimmedNonEmptyString),
+  /** When a cooling-down account becomes usable again. */
+  retryAt: Schema.optionalKey(IsoDateTime),
+});
+export type ProviderProxyAccount = typeof ProviderProxyAccount.Type;
+
+export const ProviderProxyState = Schema.Struct({
+  runtime: ProviderProxyRuntimeStatus,
+  /** `null` when this environment has no management access to a proxy. */
+  accounts: Schema.NullOr(Schema.Array(ProviderProxyAccount)),
+  accountsError: Schema.optionalKey(Schema.String),
+});
+export type ProviderProxyState = typeof ProviderProxyState.Type;
+
+export const ProviderProxyLoginProvider = Schema.Literals(["claude", "codex"]);
+export type ProviderProxyLoginProvider = typeof ProviderProxyLoginProvider.Type;
+
+export const ProviderProxyStartLoginInput = Schema.Struct({
+  provider: ProviderProxyLoginProvider,
+});
+export const ProviderProxyLogin = Schema.Struct({
+  state: TrimmedNonEmptyString,
+  url: TrimmedNonEmptyString,
+});
+export type ProviderProxyLogin = typeof ProviderProxyLogin.Type;
+
+export const ProviderProxyLoginStatusInput = Schema.Struct({ state: TrimmedNonEmptyString });
+export const ProviderProxyLoginStatus = Schema.Struct({
+  status: Schema.Literals(["wait", "ok", "error"]),
+  message: Schema.optionalKey(Schema.String),
+});
+export type ProviderProxyLoginStatus = typeof ProviderProxyLoginStatus.Type;
+
+/** The URL the browser landed on after signing in; it carries the code and state. */
+export const ProviderProxyCompleteLoginInput = Schema.Struct({
+  state: TrimmedNonEmptyString,
+  redirectUrl: TrimmedNonEmptyString,
+});
+
+export const ProviderProxySetAccountDisabledInput = Schema.Struct({
+  name: TrimmedNonEmptyString,
+  disabled: Schema.Boolean,
+});
+
+export const ProviderProxyRemoveAccountInput = Schema.Struct({ name: TrimmedNonEmptyString });
+
+export class ProviderProxyError extends Schema.TaggedError<ProviderProxyError>()(
+  "ProviderProxyError",
+  { detail: Schema.String },
+) {
+  override get message(): string {
+    return this.detail;
+  }
+}
diff --git a/packages/contracts/src/rpc.ts b/packages/contracts/src/rpc.ts
index aae86bd9db465..3534b9d506fd2 100644
--- a/packages/contracts/src/rpc.ts
+++ b/packages/contracts/src/rpc.ts
@@ -344,6 +344,17 @@ import {
   ProviderConsumeResetCreditInput,
   ProviderConsumeResetCreditResult,
 } from "./providerUsageLimits.ts";
+import {
+  ProviderProxyCompleteLoginInput,
+  ProviderProxyError,
+  ProviderProxyLogin,
+  ProviderProxyLoginStatus,
+  ProviderProxyLoginStatusInput,
+  ProviderProxyRemoveAccountInput,
+  ProviderProxySetAccountDisabledInput,
+  ProviderProxyStartLoginInput,
+  ProviderProxyState,
+} from "./providerProxy.ts";
 import { UsagePricing, UsageReadError, UsageSummary, UsageSummaryInput } from "./usage.ts";
 import {
   StorageCleanupReport,
@@ -428,6 +439,12 @@ export const WS_METHODS = {
   providerUploadFeedback: "provider.uploadFeedback",
   providerAuthStart: "provider.auth.start",
   providerConsumeResetCredit: "provider.consumeResetCredit",
+  providerProxyGetState: "provider.proxy.getState",
+  providerProxyStartLogin: "provider.proxy.startLogin",
+  providerProxyGetLoginStatus: "provider.proxy.getLoginStatus",
+  providerProxyCompleteLogin: "provider.proxy.completeLogin",
+  providerProxySetAccountDisabled: "provider.proxy.setAccountDisabled",
+  providerProxyRemoveAccount: "provider.proxy.removeAccount",
   providerAuthComplete: "provider.auth.complete",
   chatGptReconnectProfile: "provider.chatgpt.reconnect-profile",
   chatGptImportProfile: "provider.chatgpt.import-profile",
@@ -660,6 +677,41 @@ const WsProviderConsumeResetCreditRpc = Rpc.make(WS_METHODS.providerConsumeReset
   error: Schema.Union([ProviderSetupError, UsageLimitSourceError, EnvironmentAuthorizationError]),
 });
 
+const ProviderProxyRpcError = Schema.Union([ProviderProxyError, EnvironmentAuthorizationError]);
+
+const WsProviderProxyGetStateRpc = Rpc.make(WS_METHODS.providerProxyGetState, {
+  payload: Schema.Struct({}),
+  success: ProviderProxyState,
+  error: EnvironmentAuthorizationError,
+});
+
+const WsProviderProxyStartLoginRpc = Rpc.make(WS_METHODS.providerProxyStartLogin, {
+  payload: ProviderProxyStartLoginInput,
+  success: ProviderProxyLogin,
+  error: ProviderProxyRpcError,
+});
+
+const WsProviderProxyGetLoginStatusRpc = Rpc.make(WS_METHODS.providerProxyGetLoginStatus, {
+  payload: ProviderProxyLoginStatusInput,
+  success: ProviderProxyLoginStatus,
+  error: ProviderProxyRpcError,
+});
+
+const WsProviderProxyCompleteLoginRpc = Rpc.make(WS_METHODS.providerProxyCompleteLogin, {
+  payload: ProviderProxyCompleteLoginInput,
+  error: ProviderProxyRpcError,
+});
+
+const WsProviderProxySetAccountDisabledRpc = Rpc.make(WS_METHODS.providerProxySetAccountDisabled, {
+  payload: ProviderProxySetAccountDisabledInput,
+  error: ProviderProxyRpcError,
+});
+
+const WsProviderProxyRemoveAccountRpc = Rpc.make(WS_METHODS.providerProxyRemoveAccount, {
+  payload: ProviderProxyRemoveAccountInput,
+  error: ProviderProxyRpcError,
+});
+
 const WsProviderAuthStartRpc = Rpc.make(WS_METHODS.providerAuthStart, {
   payload: ProviderAuthStartInput,
   success: ProviderAuthState,
@@ -1939,6 +1991,12 @@ export const WsRpcGroup = RpcGroup.make(
   WsServerRefreshProvidersRpc,
   WsServerUpdateProviderRpc,
   WsProviderConsumeResetCreditRpc,
+  WsProviderProxyGetStateRpc,
+  WsProviderProxyStartLoginRpc,
+  WsProviderProxyGetLoginStatusRpc,
+  WsProviderProxyCompleteLoginRpc,
+  WsProviderProxySetAccountDisabledRpc,
+  WsProviderProxyRemoveAccountRpc,
   WsProviderAuthStartRpc,
   WsProviderAuthCompleteRpc,
   WsChatGptReconnectProfileRpc,
diff --git a/packages/contracts/src/settings.ts b/packages/contracts/src/settings.ts
index 8188aa1ffc466..a59234e085c13 100644
--- a/packages/contracts/src/settings.ts
+++ b/packages/contracts/src/settings.ts
@@ -20,6 +20,7 @@ import {
   TrimmedString,
 } from "./baseSchemas.ts";
 import { UsageLimitSourceId } from "./usageLimitSourceId.ts";
+import { ProviderProxyHost } from "./providerProxy.ts";
 import { EnvironmentMachineKind, ThreadEnvMode, WorktreeSubmodules } from "./environment.ts";
 import { KeybindingShortcut } from "./keybindings.ts";
 import {
@@ -928,8 +929,12 @@ const SecretProviderConfigWrite = Schema.Struct({
       : `Invalid ${entry.kind} secret provider config.`;
   }),
 );
-/** A CLIProxyAPI server that `useProxy` provider instances send model traffic to. Empty `url` turns it off. */
+/**
+ * The CLIProxyAPI server that `useProxy` provider instances send model traffic to. `managed` runs
+ * one on this environment; `external` uses `url` and the keys. Read the host with `providerProxyHost`.
+ */
 export const ProviderProxySettings = Schema.Struct({
+  host: Schema.optionalKey(ProviderProxyHost),
   url: TrimmedString.pipe(Schema.withDecodingDefault(Effect.succeed(""))),
   apiKey: TrimmedString.pipe(Schema.withDecodingDefault(Effect.succeed("")), secretSetting),
   // Optional; when set, the proxy's accounts also feed Usage -> Limits.
@@ -1727,6 +1732,7 @@ export const ServerSettingsPatch = Schema.Struct({
   /** Redaction markers retain secrets; empty secrets remove them. */
   providerProxy: Schema.optionalKey(
     Schema.Struct({
+      host: Schema.optionalKey(ProviderProxyHost),
       url: Schema.optionalKey(TrimmedString),
       apiKey: Schema.optionalKey(TrimmedString),
       managementKey: Schema.optionalKey(TrimmedString),

From e13c4623bd7f0828fbb11d880d4d4c353b6cedd4 Mon Sep 17 00:00:00 2001
From: saphid <saphid@users.noreply.github.com>
Date: Fri, 30 Oct 2026 15:36:58 +1100
Subject: [PATCH 14/26] fix(server): proxy sign-in stays local, status keeps
 refreshing, overrides must be v8

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../src/providerProxy/CliProxyApiBinary.ts      | 12 ++++++++++--
 .../providerProxy/ManagedProviderProxy.test.ts  | 11 ++++++++++-
 .../src/providerProxy/ProxyAccounts.test.ts     |  8 +-------
 apps/server/src/providerProxy/ProxyAccounts.ts  | 10 ++--------
 docs/user/install.md                            |  4 ++--
 .../client-runtime/src/state/providerProxy.ts   | 17 ++++++++---------
 6 files changed, 33 insertions(+), 29 deletions(-)

diff --git a/apps/server/src/providerProxy/CliProxyApiBinary.ts b/apps/server/src/providerProxy/CliProxyApiBinary.ts
index 495f74c311aee..5810d0985047b 100644
--- a/apps/server/src/providerProxy/CliProxyApiBinary.ts
+++ b/apps/server/src/providerProxy/CliProxyApiBinary.ts
@@ -115,6 +115,10 @@ export function parseCliProxyApiVersionOutput(output: string): string | null {
   return /\bCLIProxyAPI Version: v?(\d+\.\d+\.\d+)\b/u.exec(output)?.[1] ?? null;
 }
 
+/** T3 writes v8's config layout; v7 and older read top-level host, port, and auth fields. */
+export const isCompatibleCliProxyApiVersion = (version: string): boolean =>
+  version.split(".")[0] === CLIPROXYAPI_VERSION.split(".")[0];
+
 export class CliProxyApiBinary extends Context.Service<
   CliProxyApiBinary,
   {
@@ -170,7 +174,7 @@ const make = Effect.gen(function* () {
     const overridePath = yield* override;
     if (overridePath !== null) {
       const version = yield* probeVersion(overridePath);
-      if (version !== null) {
+      if (version !== null && isCompatibleCliProxyApiVersion(version)) {
         return {
           status: "available",
           executablePath: overridePath,
@@ -178,7 +182,11 @@ const make = Effect.gen(function* () {
           version,
         } satisfies CliProxyApiBinaryStatus;
       }
-      yield* Effect.logWarning(`${CLIPROXYAPI_PATH_ENV_NAME} does not point to CLIProxyAPI`);
+      yield* Effect.logWarning(
+        version === null
+          ? `${CLIPROXYAPI_PATH_ENV_NAME} does not point to CLIProxyAPI`
+          : `${CLIPROXYAPI_PATH_ENV_NAME} points to CLIProxyAPI ${version}; T3 Code needs ${CLIPROXYAPI_VERSION.split(".")[0]}.x`,
+      );
       return { status: "missing" } satisfies CliProxyApiBinaryStatus;
     }
     if ((yield* probeVersion(managedPath)) === CLIPROXYAPI_VERSION) {
diff --git a/apps/server/src/providerProxy/ManagedProviderProxy.test.ts b/apps/server/src/providerProxy/ManagedProviderProxy.test.ts
index 9fc02991325e9..a009128cbe732 100644
--- a/apps/server/src/providerProxy/ManagedProviderProxy.test.ts
+++ b/apps/server/src/providerProxy/ManagedProviderProxy.test.ts
@@ -1,7 +1,10 @@
 import { describe, expect, it } from "vite-plus/test";
 import { parse as parseYaml } from "yaml";
 
-import { parseCliProxyApiVersionOutput } from "./CliProxyApiBinary.ts";
+import {
+  isCompatibleCliProxyApiVersion,
+  parseCliProxyApiVersionOutput,
+} from "./CliProxyApiBinary.ts";
 import { renderCliProxyApiConfig } from "./ManagedProviderProxy.ts";
 
 describe("renderCliProxyApiConfig", () => {
@@ -38,5 +41,11 @@ describe("parseCliProxyApiVersionOutput", () => {
       ),
     ).toBe("8.0.47");
     expect(parseCliProxyApiVersionOutput("Usage of cli-proxy-api\n  -config string\n")).toBeNull();
+    // A v7 override would ignore the v8 listener and management settings T3 writes.
+    expect(["8.0.47", "8.1.0", "7.2.81"].map(isCompatibleCliProxyApiVersion)).toEqual([
+      true,
+      true,
+      false,
+    ]);
   });
 });
diff --git a/apps/server/src/providerProxy/ProxyAccounts.test.ts b/apps/server/src/providerProxy/ProxyAccounts.test.ts
index 10a0a6547d6ef..b7f411cbf832a 100644
--- a/apps/server/src/providerProxy/ProxyAccounts.test.ts
+++ b/apps/server/src/providerProxy/ProxyAccounts.test.ts
@@ -198,23 +198,17 @@ describe("ProxyAccounts", () => {
         });
 
         expect(recorded.map(({ method, url }) => `${method} ${url}`)).toEqual([
-          // The callback port was taken, so the proxy refused to catch the redirect.
-          "GET http://proxy.test:8317/v0/management/anthropic-auth-url?is_webui=true",
           "GET http://proxy.test:8317/v0/management/anthropic-auth-url",
           "GET http://proxy.test:8317/v0/management/get-auth-status?state=abc123",
           "POST http://proxy.test:8317/v0/management/oauth-callback",
         ]);
-        expect(JSON.parse(recorded[3]!.body)).toEqual({
+        expect(JSON.parse(recorded[2]!.body)).toEqual({
           redirect_url: "http://localhost:54545/callback?code=c&state=abc123",
         });
       }).pipe(
         withProxy(
           managementApi(
             {
-              "GET anthropic-auth-url?is_webui=true": {
-                status: 500,
-                body: { error: "failed to start callback server" },
-              },
               "GET anthropic-auth-url": {
                 body: {
                   status: "ok",
diff --git a/apps/server/src/providerProxy/ProxyAccounts.ts b/apps/server/src/providerProxy/ProxyAccounts.ts
index 883f3ed228eb8..e1d93321cc087 100644
--- a/apps/server/src/providerProxy/ProxyAccounts.ts
+++ b/apps/server/src/providerProxy/ProxyAccounts.ts
@@ -236,14 +236,8 @@ const make = Effect.gen(function* () {
   ) {
     const management = yield* requireManagement;
     const path = LOGIN_PATHS[provider];
-    // `is_webui` makes the proxy catch the browser's localhost redirect itself, which finishes
-    // the sign-in without a paste when the browser runs on the proxy's machine. It needs the
-    // provider's fixed callback port, so fall back to paste-back when that port is taken.
-    const body = yield* request(management, HttpClientRequest.get, `${path}?is_webui=true`).pipe(
-      Effect.catchTags({
-        ProviderProxyError: () => request(management, HttpClientRequest.get, path),
-      }),
-    );
+    // Not `is_webui`: its callback forwarder binds 0.0.0.0, so sign-in completes by paste-back.
+    const body = yield* request(management, HttpClientRequest.get, path);
     return yield* decodeLogin(body).pipe(Effect.mapError(malformed));
   });
 
diff --git a/docs/user/install.md b/docs/user/install.md
index 209599aa9fec8..9980585a852c6 100644
--- a/docs/user/install.md
+++ b/docs/user/install.md
@@ -203,8 +203,8 @@ proxy runs:
 
 - **This environment.** T3 Code downloads a pinned CLIProxyAPI release from GitHub, runs it on
   this machine for local connections only, and restarts it if it stops. Add accounts under
-  **Accounts** with **Add Claude** or **Add Codex**: open the sign-in page and sign in. If the
-  browser then lands on a `localhost` address that does not load, copy that address and paste it
+  **Accounts** with **Add Claude** or **Add Codex**: open the sign-in page and sign in. The
+  browser then lands on a `localhost` address that does not load; copy that address and paste it
   into T3 Code. Accounts can be disabled, enabled again, or removed there.
 - **External URL.** Enter the URL of a CLIProxyAPI server you run, and one of its API keys if it
   requires one. Add its management key to manage its accounts in the same place and see them under
diff --git a/packages/client-runtime/src/state/providerProxy.ts b/packages/client-runtime/src/state/providerProxy.ts
index b9cb4926658af..4d995a2abf1db 100644
--- a/packages/client-runtime/src/state/providerProxy.ts
+++ b/packages/client-runtime/src/state/providerProxy.ts
@@ -1,14 +1,14 @@
-import { type ProviderProxyState, WS_METHODS } from "@t3tools/contracts";
+import { WS_METHODS } from "@t3tools/contracts";
 import * as Effect from "effect/Effect";
 import type { Atom } from "effect/reactivity";
 
 import type { EnvironmentRegistry } from "../connection/registry.ts";
 import { createEnvironmentRpcCommand, createEnvironmentRpcQueryAtomFamily } from "./runtime.ts";
 
-// Install and start take seconds to minutes; nothing else changes the state on its own.
-const TRANSIENT_REFRESH_MS = 2_000;
-const isSettledRuntime = (state: ProviderProxyState) =>
-  state.runtime.status !== "installing" && state.runtime.status !== "starting";
+const LOGIN_REFRESH_MS = 2_000;
+// The supervisor can recover, crash, or restart after a settings change at any time, so the
+// managed view keeps reading its state while it is mounted.
+const STATE_REFRESH_MS = 3_000;
 
 export function createProviderProxyEnvironmentAtoms<R, E>(
   runtime: Atom.AtomRuntime<EnvironmentRegistry | R, E>,
@@ -16,16 +16,15 @@ export function createProviderProxyEnvironmentAtoms<R, E>(
   const state = createEnvironmentRpcQueryAtomFamily(runtime, {
     label: "environment-data:provider-proxy:state",
     tag: WS_METHODS.providerProxyGetState,
-    staleTimeMs: 5_000,
-    refreshIntervalMs: TRANSIENT_REFRESH_MS,
-    isFinal: isSettledRuntime,
+    staleTimeMs: 0,
+    refreshIntervalMs: STATE_REFRESH_MS,
   });
   // A sign-in finishes in the browser, so its status is read until it settles.
   const loginStatus = createEnvironmentRpcQueryAtomFamily(runtime, {
     label: "environment-data:provider-proxy:login-status",
     tag: WS_METHODS.providerProxyGetLoginStatus,
     staleTimeMs: 0,
-    refreshIntervalMs: TRANSIENT_REFRESH_MS,
+    refreshIntervalMs: LOGIN_REFRESH_MS,
     isFinal: (status) => status.status !== "wait",
     onAnswer: ({ environmentId }, status, registry) =>
       status.status === "ok"

From 954c4f1ebd5ad0c9c88ee86d085622d53e51e853 Mon Sep 17 00:00:00 2001
From: saphid <saphid@users.noreply.github.com>
Date: Fri, 30 Oct 2026 15:54:32 +1100
Subject: [PATCH 15/26] fix(server): proxy accounts time out body stalls;
 stopping the proxy clears its limits

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../src/providerProxy/ProxyAccounts.test.ts   | 23 +++++++++++++++++++
 .../server/src/providerProxy/ProxyAccounts.ts | 10 ++++++--
 apps/server/src/usage/UsageLimitSources.ts    |  4 ++--
 3 files changed, 33 insertions(+), 4 deletions(-)

diff --git a/apps/server/src/providerProxy/ProxyAccounts.test.ts b/apps/server/src/providerProxy/ProxyAccounts.test.ts
index b7f411cbf832a..7a5aa85264c4a 100644
--- a/apps/server/src/providerProxy/ProxyAccounts.test.ts
+++ b/apps/server/src/providerProxy/ProxyAccounts.test.ts
@@ -1,7 +1,9 @@
 import { it as effectIt } from "@effect/vitest";
 import * as DateTime from "effect/DateTime";
 import * as Effect from "effect/Effect";
+import * as Fiber from "effect/Fiber";
 import * as Layer from "effect/Layer";
+import * as TestClock from "effect/testing/TestClock";
 import { HttpClient, type HttpClientRequest, HttpClientResponse, UrlParams } from "effect/http";
 import { describe, expect, it } from "vite-plus/test";
 
@@ -129,6 +131,27 @@ const withProxy = (client: HttpClient.HttpClient) =>
   );
 
 describe("ProxyAccounts", () => {
+  effectIt.effect("times out a proxy that sends headers and then stalls the body", () =>
+    Effect.gen(function* () {
+      const accounts = yield* ProxyAccounts.ProxyAccounts;
+      const removal = yield* accounts
+        .removeAccount("claude-a.json")
+        .pipe(Effect.flip, Effect.forkChild);
+      yield* TestClock.adjust("15 seconds");
+      expect((yield* Fiber.join(removal)).detail).toBe(
+        "The proxy did not answer within 15 seconds.",
+      );
+    }).pipe(
+      withProxy(
+        HttpClient.make((request) =>
+          Effect.succeed(
+            HttpClientResponse.fromWeb(request, new Response(new ReadableStream({ start() {} }))),
+          ),
+        ),
+      ),
+    ),
+  );
+
   effectIt.effect("lists, disables, and removes accounts with the management key", () => {
     const recorded: Array<Recorded> = [];
     return Effect.gen(function* () {
diff --git a/apps/server/src/providerProxy/ProxyAccounts.ts b/apps/server/src/providerProxy/ProxyAccounts.ts
index e1d93321cc087..9f7870b2fb0a3 100644
--- a/apps/server/src/providerProxy/ProxyAccounts.ts
+++ b/apps/server/src/providerProxy/ProxyAccounts.ts
@@ -165,13 +165,20 @@ const make = Effect.gen(function* () {
     build: (url: string) => HttpClientRequest.HttpClientRequest,
     path: string,
   ) {
-    const response = yield* client
+    // The deadline covers the body too: a proxy can send headers and then stall.
+    const { response, body } = yield* client
       .execute(
         build(`${management.url}/v0/management/${path}`).pipe(
           HttpClientRequest.bearerToken(management.managementKey),
         ),
       )
       .pipe(
+        Effect.flatMap((response) =>
+          response.json.pipe(
+            Effect.orElseSucceed((): unknown => null),
+            Effect.map((body) => ({ response, body })),
+          ),
+        ),
         Effect.timeout(REQUEST_TIMEOUT),
         Effect.mapError(
           (error) =>
@@ -182,7 +189,6 @@ const make = Effect.gen(function* () {
             }),
         ),
       );
-    const body = yield* response.json.pipe(Effect.orElseSucceed((): unknown => null));
     if (response.status >= 200 && response.status < 300) return body;
     // CLIProxyAPI's own error strings, such as "auth file not found", carry no credentials.
     const proxyMessage = Option.match(decodeErrorBody(body), {
diff --git a/apps/server/src/usage/UsageLimitSources.ts b/apps/server/src/usage/UsageLimitSources.ts
index a5674a2fd14c5..ff2a6c78e9e7d 100644
--- a/apps/server/src/usage/UsageLimitSources.ts
+++ b/apps/server/src/usage/UsageLimitSources.ts
@@ -164,8 +164,8 @@ export const make = Effect.gen(function* () {
       Stream.map((settings) => effectiveUsageLimitSources(settings)),
       Stream.changes,
     ),
-    // A managed proxy can only answer once it runs.
-    managedProxy.statusChanges.pipe(Stream.filter((status) => status.status === "running")),
+    // Starting makes the managed proxy answer; stopping must drop its accounts.
+    managedProxy.statusChanges,
   ).pipe(
     Stream.runForEach(() => refresh),
     Effect.forkScoped,

From 986a2753cc10ed3a160c00f68395c6a4ce420020 Mon Sep 17 00:00:00 2001
From: saphid <saphid@users.noreply.github.com>
Date: Fri, 30 Oct 2026 16:02:41 +1100
Subject: [PATCH 16/26] fix: https-only sign-in links, disabled hubs don't hide
 proxy accounts, accounts need providers:manage

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../src/providerProxy/ProxyAccounts.test.ts   |  9 ++++++++-
 .../server/src/providerProxy/ProxyAccounts.ts |  5 ++++-
 .../src/usage/UsageLimitSources.test.ts       | 19 ++++++++++++-------
 apps/server/src/usage/UsageLimitSources.ts    |  5 ++++-
 .../settings/ProviderProxySettings.tsx        |  8 +++++++-
 5 files changed, 35 insertions(+), 11 deletions(-)

diff --git a/apps/server/src/providerProxy/ProxyAccounts.test.ts b/apps/server/src/providerProxy/ProxyAccounts.test.ts
index 7a5aa85264c4a..98df5a6ddd4a9 100644
--- a/apps/server/src/providerProxy/ProxyAccounts.test.ts
+++ b/apps/server/src/providerProxy/ProxyAccounts.test.ts
@@ -206,6 +206,9 @@ describe("ProxyAccounts", () => {
         const accounts = yield* ProxyAccounts.ProxyAccounts;
         const login = yield* accounts.startLogin("claude");
         expect(login).toEqual({ url: "https://claude.ai/oauth/authorize?x=1", state: "abc123" });
+        // Clients open this URL, so a proxy can't hand them a non-https link.
+        const unsafe = yield* accounts.startLogin("codex").pipe(Effect.flip);
+        expect(unsafe._tag).toBe("ProviderProxyError");
         expect(yield* accounts.getLoginStatus("abc123")).toEqual({ status: "wait" });
 
         const wrongLogin = yield* accounts
@@ -222,10 +225,11 @@ describe("ProxyAccounts", () => {
 
         expect(recorded.map(({ method, url }) => `${method} ${url}`)).toEqual([
           "GET http://proxy.test:8317/v0/management/anthropic-auth-url",
+          "GET http://proxy.test:8317/v0/management/codex-auth-url",
           "GET http://proxy.test:8317/v0/management/get-auth-status?state=abc123",
           "POST http://proxy.test:8317/v0/management/oauth-callback",
         ]);
-        expect(JSON.parse(recorded[2]!.body)).toEqual({
+        expect(JSON.parse(recorded[3]!.body)).toEqual({
           redirect_url: "http://localhost:54545/callback?code=c&state=abc123",
         });
       }).pipe(
@@ -239,6 +243,9 @@ describe("ProxyAccounts", () => {
                   state: "abc123",
                 },
               },
+              "GET codex-auth-url": {
+                body: { status: "ok", url: "file:///etc/passwd", state: "def456" },
+              },
               "GET get-auth-status?state=abc123": { body: { status: "wait" } },
               "POST oauth-callback": { body: { status: "ok" } },
             },
diff --git a/apps/server/src/providerProxy/ProxyAccounts.ts b/apps/server/src/providerProxy/ProxyAccounts.ts
index 9f7870b2fb0a3..48f292d8ab617 100644
--- a/apps/server/src/providerProxy/ProxyAccounts.ts
+++ b/apps/server/src/providerProxy/ProxyAccounts.ts
@@ -244,7 +244,10 @@ const make = Effect.gen(function* () {
     const path = LOGIN_PATHS[provider];
     // Not `is_webui`: its callback forwarder binds 0.0.0.0, so sign-in completes by paste-back.
     const body = yield* request(management, HttpClientRequest.get, path);
-    return yield* decodeLogin(body).pipe(Effect.mapError(malformed));
+    const login = yield* decodeLogin(body).pipe(Effect.mapError(malformed));
+    // Clients open this URL; an external proxy must not hand them a file: or app link.
+    if (URL.parse(login.url)?.protocol !== "https:") return yield* malformed();
+    return login;
   });
 
   const getLoginStatus = Effect.fn("ProxyAccounts.getLoginStatus")(function* (state: string) {
diff --git a/apps/server/src/usage/UsageLimitSources.test.ts b/apps/server/src/usage/UsageLimitSources.test.ts
index d2baab1fe8ff8..23e8a2dfe4d55 100644
--- a/apps/server/src/usage/UsageLimitSources.test.ts
+++ b/apps/server/src/usage/UsageLimitSources.test.ts
@@ -111,13 +111,18 @@ it("reports the routing proxy's accounts unless a hub already points at it or ow
       enabled: true,
     },
   });
-  // A keyless hub at the same URL can't read accounts, so the proxy's key still applies.
-  expect(
-    UsageLimitSources.effectiveUsageLimitSources({
-      ...settings,
-      usageLimitSources: { [UsageLimitSourceId.make("hub")]: { ...hub, managementKey: "" } },
-    })[UsageLimitSources.PROVIDER_PROXY_SOURCE_ID]?.managementKey,
-  ).toBe("mgmt");
+  // A keyless or disabled hub at the same URL can't report accounts, so the proxy's key applies.
+  for (const unusable of [
+    { ...hub, managementKey: "" },
+    { ...hub, enabled: false },
+  ]) {
+    expect(
+      UsageLimitSources.effectiveUsageLimitSources({
+        ...settings,
+        usageLimitSources: { [UsageLimitSourceId.make("hub")]: unusable },
+      })[UsageLimitSources.PROVIDER_PROXY_SOURCE_ID]?.managementKey,
+    ).toBe("mgmt");
+  }
   for (const listed of [
     { [UsageLimitSourceId.make("hub")]: hub },
     {
diff --git a/apps/server/src/usage/UsageLimitSources.ts b/apps/server/src/usage/UsageLimitSources.ts
index ff2a6c78e9e7d..d38f92e86af89 100644
--- a/apps/server/src/usage/UsageLimitSources.ts
+++ b/apps/server/src/usage/UsageLimitSources.ts
@@ -63,7 +63,10 @@ export function effectiveUsageLimitSources(
   if (management === undefined) return settings.usageLimitSources;
   const { url, managementKey } = management;
   const alreadyListed = Object.values(settings.usageLimitSources).some(
-    (source) => source.managementKey !== "" && normalizeProviderProxyUrl(source.url) === url,
+    (source) =>
+      source.enabled &&
+      source.managementKey !== "" &&
+      normalizeProviderProxyUrl(source.url) === url,
   );
   // A hand-written source may already use the synthetic id; it keeps the slot.
   if (alreadyListed || PROVIDER_PROXY_SOURCE_ID in settings.usageLimitSources) {
diff --git a/apps/web/src/components/settings/ProviderProxySettings.tsx b/apps/web/src/components/settings/ProviderProxySettings.tsx
index 84951f3be6cf4..48bd8dfe0f563 100644
--- a/apps/web/src/components/settings/ProviderProxySettings.tsx
+++ b/apps/web/src/components/settings/ProviderProxySettings.tsx
@@ -98,7 +98,13 @@ export function ProviderProxySettings({
   const update = (patch: Partial<UnifiedSettings["providerProxy"]>) =>
     updateSettings({ providerProxy: patch });
   const host = providerProxyHost(proxy);
-  const managesAccounts = host === "managed" || (host === "external" && proxy.managementKey !== "");
+  // The server reads proxy state only for sessions that can manage providers.
+  const canManageProviders = useAtomValue(
+    providerProxyEnvironment.startLogin.permissionAtom(environmentId),
+  );
+  const managesAccounts =
+    canManageProviders &&
+    (host === "managed" || (host === "external" && proxy.managementKey !== ""));
 
   return (
     <SettingsSection {...searchableSetting("provider-proxy")}>

From e21db30c42ccbc561b5b40b9351125fdec0c5dc5 Mon Sep 17 00:00:00 2001
From: SAPHID <saphid@users.noreply.github.com>
Date: Sat, 31 Oct 2026 11:49:13 +0000
Subject: [PATCH 17/26] fix(usage): retain proxy account reporting when a
 matching hub is disabled

---
 apps/server/src/usage/UsageLimitSources.test.ts | 5 ++++-
 apps/server/src/usage/UsageLimitSources.ts      | 5 ++++-
 2 files changed, 8 insertions(+), 2 deletions(-)

diff --git a/apps/server/src/usage/UsageLimitSources.test.ts b/apps/server/src/usage/UsageLimitSources.test.ts
index 82906f59bfa9e..c241a2972d254 100644
--- a/apps/server/src/usage/UsageLimitSources.test.ts
+++ b/apps/server/src/usage/UsageLimitSources.test.ts
@@ -109,7 +109,10 @@ it("reports the routing proxy's accounts unless a hub already points at it or ow
       enabled: true,
     },
   });
-  for (const unreadableHub of [{ ...hub, managementKey: "" }, { ...hub, enabled: false }]) {
+  for (const unreadableHub of [
+    { ...hub, managementKey: "" },
+    { ...hub, enabled: false },
+  ]) {
     expect(
       UsageLimitSources.effectiveUsageLimitSources({
         ...settings,
diff --git a/apps/server/src/usage/UsageLimitSources.ts b/apps/server/src/usage/UsageLimitSources.ts
index e9510f7f4755a..56349289798b8 100644
--- a/apps/server/src/usage/UsageLimitSources.ts
+++ b/apps/server/src/usage/UsageLimitSources.ts
@@ -57,7 +57,10 @@ export function effectiveUsageLimitSources(
   const { managementKey } = settings.providerProxy;
   if (url === "" || managementKey === "") return settings.usageLimitSources;
   const alreadyListed = Object.values(settings.usageLimitSources).some(
-    (source) => source.managementKey !== "" && normalizeProviderProxyUrl(source.url) === url,
+    (source) =>
+      source.enabled &&
+      source.managementKey !== "" &&
+      normalizeProviderProxyUrl(source.url) === url,
   );
   // A hand-written source may already use the synthetic id; it keeps the slot.
   if (alreadyListed || PROVIDER_PROXY_SOURCE_ID in settings.usageLimitSources) {

From 14acf3c95a61a723bc4e97e0ec07bb5e5787644b Mon Sep 17 00:00:00 2001
From: SAPHID <saphid@users.noreply.github.com>
Date: Sat, 31 Oct 2026 11:52:26 +0000
Subject: [PATCH 18/26] test(usage): cover managed proxy startup refresh
 duplication

---
 .../src/usage/UsageLimitSources.test.ts       | 63 ++++++++++++++++++-
 1 file changed, 62 insertions(+), 1 deletion(-)

diff --git a/apps/server/src/usage/UsageLimitSources.test.ts b/apps/server/src/usage/UsageLimitSources.test.ts
index 6a2a80bcbf2a9..69e4f330b6b28 100644
--- a/apps/server/src/usage/UsageLimitSources.test.ts
+++ b/apps/server/src/usage/UsageLimitSources.test.ts
@@ -6,9 +6,13 @@ import {
   UsageLimitSourceId,
 } from "@t3tools/contracts";
 import * as Effect from "effect/Effect";
+import * as Deferred from "effect/Deferred";
+import * as Queue from "effect/Queue";
+import * as Ref from "effect/Ref";
+import * as Stream from "effect/Stream";
 import * as Layer from "effect/Layer";
 import * as Schema from "effect/Schema";
-import { HttpClient } from "effect/http";
+import { HttpClient, HttpClientResponse } from "effect/http";
 
 import * as BackgroundPolicy from "../background/BackgroundPolicy.ts";
 import * as ManagedProviderProxy from "../providerProxy/ManagedProviderProxy.ts";
@@ -155,3 +159,60 @@ it("reports the routing proxy's accounts unless a hub already points at it or ow
     ),
   ).toEqual({});
 });
+
+it.effect("refreshes once at startup and again when managed proxy status changes", () =>
+  Effect.gen(function* () {
+    const refreshes = yield* Ref.make(0);
+    const initialStatusRead = yield* Deferred.make<void>();
+    const changedStatusRead = yield* Deferred.make<void>();
+    const statuses = yield* Queue.unbounded<{ readonly status: "running" }>();
+    const managed = Layer.succeed(ManagedProviderProxy.ManagedProviderProxy, {
+      status: Effect.succeed({ status: "stopped" }),
+      statusChanges: Stream.concat(
+        Stream.make({ status: "stopped" } as const),
+        Stream.concat(
+          Stream.fromEffect(Deferred.succeed(initialStatusRead, undefined)).pipe(Stream.drain),
+          Stream.fromQueue(statuses),
+        ),
+      ),
+      endpoint: Effect.succeed(undefined),
+      endpointChanges: Stream.empty,
+    });
+    const http = HttpClient.make((request) =>
+      Ref.updateAndGet(refreshes, (count) => count + 1).pipe(
+        Effect.tap((count) =>
+          count === 3 ? Deferred.succeed(changedStatusRead, undefined) : Effect.void,
+        ),
+        Effect.map(() => HttpClientResponse.fromWeb(request, new Response("{}", { status: 401 }))),
+      ),
+    );
+    yield* Effect.gen(function* () {
+      const sources = yield* UsageLimitSources.make;
+      yield* Deferred.await(initialStatusRead);
+      yield* sources.refresh;
+      expect(yield* Ref.get(refreshes)).toBe(2);
+      yield* Queue.offer(statuses, { status: "running" });
+      yield* Deferred.await(changedStatusRead);
+      yield* sources.refresh;
+      expect(yield* Ref.get(refreshes)).toBe(4);
+    }).pipe(Effect.provide([managed, Layer.succeed(HttpClient.HttpClient, http)]));
+  }).pipe(
+    Effect.provide([
+      ServerSettings.layerTest({
+        usageLimitSources: {
+          [UsageLimitSourceId.make("hub")]: {
+            kind: "cliproxy",
+            url: "http://hub.test",
+            managementKey: "mgmt",
+            enabled: true,
+          },
+        },
+      }),
+      Layer.mock(BackgroundPolicy.BackgroundPolicy)({
+        shouldRunScopeWork: () => Effect.succeed(false),
+      }),
+      NodeCrypto.layer,
+    ]),
+    Effect.scoped,
+  ),
+);

From c84e848b08b6f64206be3e5a1728db25dab8fa57 Mon Sep 17 00:00:00 2001
From: SAPHID <saphid@users.noreply.github.com>
Date: Sat, 31 Oct 2026 11:57:25 +0000
Subject: [PATCH 19/26] fix(usage): avoid duplicate initial managed proxy
 refresh

---
 apps/server/src/usage/UsageLimitSources.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/server/src/usage/UsageLimitSources.ts b/apps/server/src/usage/UsageLimitSources.ts
index d38f92e86af89..588903215f76f 100644
--- a/apps/server/src/usage/UsageLimitSources.ts
+++ b/apps/server/src/usage/UsageLimitSources.ts
@@ -168,7 +168,7 @@ export const make = Effect.gen(function* () {
       Stream.changes,
     ),
     // Starting makes the managed proxy answer; stopping must drop its accounts.
-    managedProxy.statusChanges,
+    managedProxy.statusChanges.pipe(Stream.drop(1)),
   ).pipe(
     Stream.runForEach(() => refresh),
     Effect.forkScoped,

From 4bd7dffc599d9ef692cec3f072404dbda08f7077 Mon Sep 17 00:00:00 2001
From: SAPHID <saphid@users.noreply.github.com>
Date: Sat, 31 Oct 2026 12:00:03 +0000
Subject: [PATCH 20/26] test(usage): retain literal managed status in refresh
 fixture

---
 apps/server/src/usage/UsageLimitSources.test.ts | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/apps/server/src/usage/UsageLimitSources.test.ts b/apps/server/src/usage/UsageLimitSources.test.ts
index 69e4f330b6b28..25efcfabfd50a 100644
--- a/apps/server/src/usage/UsageLimitSources.test.ts
+++ b/apps/server/src/usage/UsageLimitSources.test.ts
@@ -167,7 +167,7 @@ it.effect("refreshes once at startup and again when managed proxy status changes
     const changedStatusRead = yield* Deferred.make<void>();
     const statuses = yield* Queue.unbounded<{ readonly status: "running" }>();
     const managed = Layer.succeed(ManagedProviderProxy.ManagedProviderProxy, {
-      status: Effect.succeed({ status: "stopped" }),
+      status: Effect.succeed({ status: "stopped" } as const),
       statusChanges: Stream.concat(
         Stream.make({ status: "stopped" } as const),
         Stream.concat(
@@ -175,7 +175,7 @@ it.effect("refreshes once at startup and again when managed proxy status changes
           Stream.fromQueue(statuses),
         ),
       ),
-      endpoint: Effect.succeed(undefined),
+      endpoint: Effect.void,
       endpointChanges: Stream.empty,
     });
     const http = HttpClient.make((request) =>

From f1ebb6ae47ae1c3b9d08b8b48540a8bf6840497a Mon Sep 17 00:00:00 2001
From: SAPHID <saphid@users.noreply.github.com>
Date: Sat, 31 Oct 2026 12:02:47 +0000
Subject: [PATCH 21/26] test(usage): reuse managed proxy endpoint fixture

---
 apps/server/src/usage/UsageLimitSources.test.ts | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/apps/server/src/usage/UsageLimitSources.test.ts b/apps/server/src/usage/UsageLimitSources.test.ts
index 25efcfabfd50a..6f3214827af8e 100644
--- a/apps/server/src/usage/UsageLimitSources.test.ts
+++ b/apps/server/src/usage/UsageLimitSources.test.ts
@@ -166,8 +166,11 @@ it.effect("refreshes once at startup and again when managed proxy status changes
     const initialStatusRead = yield* Deferred.make<void>();
     const changedStatusRead = yield* Deferred.make<void>();
     const statuses = yield* Queue.unbounded<{ readonly status: "running" }>();
+    const baseline = yield* ManagedProviderProxy.ManagedProviderProxy.pipe(
+      Effect.provide(ManagedProviderProxy.layerTest()),
+    );
     const managed = Layer.succeed(ManagedProviderProxy.ManagedProviderProxy, {
-      status: Effect.succeed({ status: "stopped" } as const),
+      ...baseline,
       statusChanges: Stream.concat(
         Stream.make({ status: "stopped" } as const),
         Stream.concat(
@@ -175,8 +178,6 @@ it.effect("refreshes once at startup and again when managed proxy status changes
           Stream.fromQueue(statuses),
         ),
       ),
-      endpoint: Effect.void,
-      endpointChanges: Stream.empty,
     });
     const http = HttpClient.make((request) =>
       Ref.updateAndGet(refreshes, (count) => count + 1).pipe(

From f087a3f9d9a084fff151ca04ae37b3f2f596d4d7 Mon Sep 17 00:00:00 2001
From: SAPHID <saphid@users.noreply.github.com>
Date: Sat, 31 Oct 2026 13:22:21 +0000
Subject: [PATCH 22/26] test(server): use the managed proxy service fixture

---
 apps/server/src/usage/UsageLimitSources.test.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/apps/server/src/usage/UsageLimitSources.test.ts b/apps/server/src/usage/UsageLimitSources.test.ts
index 6f3214827af8e..5484f75fc40bd 100644
--- a/apps/server/src/usage/UsageLimitSources.test.ts
+++ b/apps/server/src/usage/UsageLimitSources.test.ts
@@ -167,7 +167,7 @@ it.effect("refreshes once at startup and again when managed proxy status changes
     const changedStatusRead = yield* Deferred.make<void>();
     const statuses = yield* Queue.unbounded<{ readonly status: "running" }>();
     const baseline = yield* ManagedProviderProxy.ManagedProviderProxy.pipe(
-      Effect.provide(ManagedProviderProxy.layerTest()),
+      Effect.provide(ManagedProviderProxy.ManagedProviderProxy.layerTest()),
     );
     const managed = Layer.succeed(ManagedProviderProxy.ManagedProviderProxy, {
       ...baseline,

From d4b5dc0dbe342dc77cdc56598e66bd2626923df4 Mon Sep 17 00:00:00 2001
From: SAPHID <saphid@users.noreply.github.com>
Date: Sat, 31 Oct 2026 13:44:38 +0000
Subject: [PATCH 23/26] fix(proxy): preserve configured routing and current
 management credentials

---
 .../Adapters/ClaudeAdapterV2.test.ts          | 22 +++++++++-
 .../Adapters/ClaudeAdapterV2.ts               | 15 ++++++-
 .../src/provider/Drivers/ClaudeDriver.ts      |  2 +-
 .../server/src/provider/Drivers/ClaudeHome.ts |  7 ++++
 .../provider/ProviderInstanceRegistry.test.ts | 40 ++++++++++++++++---
 .../src/usage/UsageLimitSources.test.ts       |  3 +-
 apps/server/src/usage/UsageLimitSources.ts    |  2 +-
 7 files changed, 80 insertions(+), 11 deletions(-)

diff --git a/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.test.ts b/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.test.ts
index ffe99dd293f39..54582c4a8ee76 100644
--- a/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.test.ts
+++ b/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.test.ts
@@ -980,12 +980,17 @@ describe("ClaudeAdapterV2 Auto-accept edits", () => {
 });
 
 describe("ClaudeAdapterV2 append-system-prompt-file launch argument", () => {
-  const startTurnWithLaunchArgs = Effect.fnUntraced(function* (launchArgs: string, cwd: string) {
+  const startTurnWithLaunchArgs = Effect.fnUntraced(function* (
+    launchArgs: string,
+    cwd: string,
+    proxy?: { readonly url: string; readonly apiKey: string },
+  ) {
     const fileSystem = yield* FileSystem.FileSystem;
     const opened: Array<ClaudeAdapterV2.ClaudeAgentSdkQueryOptions> = [];
     const adapter = yield* ClaudeAdapterV2.makeClaudeAdapterV2({
       instanceId: ClaudeAdapterV2.CLAUDE_DEFAULT_INSTANCE_ID,
       settings: { ...DEFAULT_CLAUDE_SETTINGS, launchArgs },
+      ...(proxy === undefined ? {} : { proxy }),
       environment: {},
       attachmentsDir: yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-claude-append-" }),
       fileSystem,
@@ -1098,6 +1103,21 @@ describe("ClaudeAdapterV2 append-system-prompt-file launch argument", () => {
           showThinkingSummaries: true,
         });
         assert.isUndefined(opened[0]!.extraArgs?.["settings"]);
+        const proxy = { url: "http://proxy.test:8317", apiKey: "proxy-test-key" };
+        const routed = yield* startTurnWithLaunchArgs(launchArgs, cwd, proxy);
+        assert.isTrue(Exit.isSuccess(routed.exit));
+        assert.deepInclude(routed.opened[0]!.settings, {
+          skillOverrides: { lint: "off" },
+          env: {
+            ANTHROPIC_BASE_URL: proxy.url,
+            ANTHROPIC_AUTH_TOKEN: proxy.apiKey,
+            ANTHROPIC_API_KEY: "",
+            CLAUDE_CODE_OAUTH_TOKEN: "",
+            CLAUDE_CODE_USE_BEDROCK: "",
+            CLAUDE_CODE_USE_VERTEX: "",
+            CLAUDE_CODE_USE_FOUNDRY: "",
+          },
+        });
       }).pipe(
         Effect.provide(
           Layer.mergeAll(IdAllocator.layer, McpProviderSessions.layer, NodeServices.layer),
diff --git a/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts b/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts
index 7d999bbdc677c..61aaf1e22c26e 100644
--- a/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts
+++ b/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.ts
@@ -154,6 +154,7 @@ import { spawnAndCollect } from "@t3tools/provider-core/server/snapshotProbe";
 import { signalProcessGroup } from "@t3tools/provider-core/server/processGroup";
 import {
   applyClaudeProxyEnvironment,
+  claudeProxySettingsEnvironment,
   claudeSignedOutMessage,
   makeClaudeEnvironment,
   resolveClaudeHomePath,
@@ -4476,6 +4477,7 @@ function claudeProposedPlan(input: unknown): string | null {
 
 export interface ClaudeAdapterV2Options {
   readonly instanceId: ProviderInstanceId;
+  readonly proxy?: ProviderAdapterDriverCreateInput<ClaudeSettings>["proxy"];
   readonly settings: ClaudeSettings;
   readonly environment: NodeJS.ProcessEnv;
   readonly attachmentsDir: string;
@@ -10185,12 +10187,22 @@ export const makeClaudeAdapterV2 = Effect.fn("makeClaudeAdapterV2")(function* (
             fileSystem,
             path,
           });
-          const launchArgSettings = yield* readClaudeLaunchArgSettings({
+          const userLaunchArgSettings = yield* readClaudeLaunchArgSettings({
             settings: adapterOptions.settings,
             cwd: turnInput.runtimePolicy.cwd,
             fileSystem,
             path,
           });
+          const launchArgSettings =
+            adapterOptions.proxy === undefined
+              ? userLaunchArgSettings
+              : {
+                  ...userLaunchArgSettings,
+                  env: {
+                    ...userLaunchArgSettings?.env,
+                    ...claudeProxySettingsEnvironment(adapterOptions.proxy),
+                  },
+                };
           const closedExistingNativeThreadId = existing !== null ? existing.nativeThreadId : null;
           if (existing !== null) {
             yield* existing.query.close.pipe(Effect.ignore);
@@ -11528,6 +11540,7 @@ export const createClaudeAdapterV2 = Effect.fn("ClaudeAdapterV2Driver.create")(
     return yield* makeClaudeAdapterV2({
       instanceId,
       settings: { ...config, enabled, binaryPath },
+      ...(proxy === undefined ? {} : { proxy }),
       environment: claudeEnvironment,
       attachmentsDir: serverConfig.attachmentsDir,
       fileSystem,
diff --git a/apps/server/src/provider/Drivers/ClaudeDriver.ts b/apps/server/src/provider/Drivers/ClaudeDriver.ts
index 53d56756b2be1..14cdc7e0e5db5 100644
--- a/apps/server/src/provider/Drivers/ClaudeDriver.ts
+++ b/apps/server/src/provider/Drivers/ClaudeDriver.ts
@@ -209,7 +209,7 @@ export const ClaudeDriver: ProviderDriver<ClaudeSettings, ClaudeDriverEnv, Path.
     const lastGoodCapabilities = yield* Ref.make<ClaudeCapabilitiesProbe | undefined>(undefined);
     const capabilitiesProbeCache = yield* Cache.makeWith(
       () =>
-        probeClaudeCapabilities(effectiveConfig, processEnv, stateDir).pipe(
+        probeClaudeCapabilities(effectiveConfig, processEnv, stateDir, proxy === undefined).pipe(
           Effect.flatMap((capabilities) =>
             ClaudeResetCredits.readClaudeOrganizationId(accountConfigPath).pipe(
               Effect.map((workspaceId) => ({
diff --git a/apps/server/src/provider/Drivers/ClaudeHome.ts b/apps/server/src/provider/Drivers/ClaudeHome.ts
index 47f5506db6202..a6affb50d5bef 100644
--- a/apps/server/src/provider/Drivers/ClaudeHome.ts
+++ b/apps/server/src/provider/Drivers/ClaudeHome.ts
@@ -54,6 +54,13 @@ const CLAUDE_ROUTE_OVERRIDE_VARIABLES = [
   "CLAUDE_CODE_USE_FOUNDRY",
 ] as const;
 
+export const claudeProxySettingsEnvironment = (proxy: ProviderProxyRoute) => ({
+  ANTHROPIC_BASE_URL: proxy.url,
+  ANTHROPIC_AUTH_TOKEN: providerProxyToken(proxy),
+  ANTHROPIC_API_KEY: "",
+  ...Object.fromEntries(CLAUDE_ROUTE_OVERRIDE_VARIABLES.map((name) => [name, ""])),
+});
+
 export const applyClaudeProxyEnvironment = (
   environment: NodeJS.ProcessEnv,
   proxy: ProviderProxyRoute | undefined,
diff --git a/apps/server/src/provider/ProviderInstanceRegistry.test.ts b/apps/server/src/provider/ProviderInstanceRegistry.test.ts
index 36d58062a255e..14bcbe4254fb5 100644
--- a/apps/server/src/provider/ProviderInstanceRegistry.test.ts
+++ b/apps/server/src/provider/ProviderInstanceRegistry.test.ts
@@ -462,6 +462,7 @@ describe("ProviderInstanceRegistry — multi-instance codex slice", () => {
       const claudeId = ProviderInstanceId.make("claude_probe_recovery");
       let probeCount = 0;
       let successfulProbeCount = 0;
+      let usageProbeCount = 0;
       let failProbe = false;
       const query = vi.spyOn(ClaudeSdk, "query").mockImplementation(
         () =>
@@ -486,12 +487,15 @@ describe("ProviderInstanceRegistry — multi-instance codex slice", () => {
                 },
               });
             },
-            usage_EXPERIMENTAL_MAY_CHANGE_DO_NOT_RELY_ON_THIS_API_YET: async () => ({
-              rate_limits_available: true,
-              rate_limits: {
-                five_hour: { utilization: 12, resets_at: "2026-07-18T14:39:00Z" },
-              },
-            }),
+            usage_EXPERIMENTAL_MAY_CHANGE_DO_NOT_RELY_ON_THIS_API_YET: async () => {
+              usageProbeCount++;
+              return {
+                rate_limits_available: true,
+                rate_limits: {
+                  five_hour: { utilization: 12, resets_at: "2026-07-18T14:39:00Z" },
+                },
+              };
+            },
           }) as ReturnType<typeof ClaudeSdk.query>,
       );
       yield* Effect.addFinalizer(() => Effect.sync(() => query.mockRestore()));
@@ -579,6 +583,30 @@ describe("ProviderInstanceRegistry — multi-instance codex slice", () => {
         expect.arrayContaining([expect.objectContaining({ name: "recovered" })]),
       );
       expect(probeCount).toBeGreaterThan(sameAccountFailureProbeCount);
+      expect(usageProbeCount).toBeGreaterThan(0);
+      failProbe = false;
+      const beforeProxy = usageProbeCount;
+      const { registry: proxiedRegistry } = yield* makeProviderInstanceRegistry<ClaudeDriverEnv>({
+        drivers: [ClaudeDriver],
+        configMap: {
+          [claudeId]: {
+            driver: ProviderDriverKind.make("claudeAgent"),
+            enabled: true,
+            useProxy: true,
+            proxy: { url: "http://proxy.test:8317", apiKey: "proxy-test-key" },
+            config: makeClaudeConfig({
+              enabled: true,
+              binaryPath: fixtures.claudeBinaryPath,
+              homePath: fixtures.claudeHomePath,
+            }),
+          },
+        },
+      });
+      const proxied = yield* proxiedRegistry.getInstance(claudeId);
+      expect(proxied).toBeDefined();
+      const proxySnapshot = yield* proxied!.snapshot.refresh;
+      expect(proxySnapshot.auth.type).toBe("proxy");
+      expect(usageProbeCount).toBe(beforeProxy);
     }).pipe(Effect.provide(layerTest)),
   );
 
diff --git a/apps/server/src/usage/UsageLimitSources.test.ts b/apps/server/src/usage/UsageLimitSources.test.ts
index 5484f75fc40bd..fb3b41617788d 100644
--- a/apps/server/src/usage/UsageLimitSources.test.ts
+++ b/apps/server/src/usage/UsageLimitSources.test.ts
@@ -98,7 +98,7 @@ it("reports the routing proxy's accounts unless a hub already points at it or ow
   const hub = {
     kind: "cliproxy" as const,
     url: "http://proxy:8317/",
-    managementKey: "hub-key",
+    managementKey: "mgmt",
     enabled: true,
   };
   const settings = {
@@ -117,6 +117,7 @@ it("reports the routing proxy's accounts unless a hub already points at it or ow
   });
   for (const unusable of [
     { ...hub, managementKey: "" },
+    { ...hub, managementKey: "rotated-old-key" },
     { ...hub, enabled: false },
   ]) {
     expect(
diff --git a/apps/server/src/usage/UsageLimitSources.ts b/apps/server/src/usage/UsageLimitSources.ts
index 588903215f76f..fc0cbf9fa60e0 100644
--- a/apps/server/src/usage/UsageLimitSources.ts
+++ b/apps/server/src/usage/UsageLimitSources.ts
@@ -65,7 +65,7 @@ export function effectiveUsageLimitSources(
   const alreadyListed = Object.values(settings.usageLimitSources).some(
     (source) =>
       source.enabled &&
-      source.managementKey !== "" &&
+      source.managementKey === managementKey &&
       normalizeProviderProxyUrl(source.url) === url,
   );
   // A hand-written source may already use the synthetic id; it keeps the slot.

From 1bbcaf8f1400a0bc421eee2f0fdc789d23eff041 Mon Sep 17 00:00:00 2001
From: SAPHID <saphid@users.noreply.github.com>
Date: Sat, 31 Oct 2026 13:51:21 +0000
Subject: [PATCH 24/26] fix(proxy): apply Claude routing to structured text
 generation

---
 .../Adapters/ClaudeAdapterV2.test.ts              |  5 +++--
 apps/server/src/provider/Drivers/ClaudeDriver.ts  |  1 +
 .../textGeneration/ClaudeTextGeneration.test.ts   | 15 +++++++++++----
 .../src/textGeneration/ClaudeTextGeneration.ts    |  4 ++++
 4 files changed, 19 insertions(+), 6 deletions(-)

diff --git a/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.test.ts b/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.test.ts
index 54582c4a8ee76..344e994fc9b9c 100644
--- a/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.test.ts
+++ b/apps/server/src/orchestration-v2/Adapters/ClaudeAdapterV2.test.ts
@@ -1085,7 +1085,7 @@ describe("ClaudeAdapterV2 append-system-prompt-file launch argument", () => {
 
   // regression: #15073 the SDK replaced the --settings launch argument with T3's settings
   it.effect.each([
-    `--settings '{"skillOverrides":{"lint":"off"},"showThinkingSummaries":false}'`,
+    `--settings '{"skillOverrides":{"lint":"off"},"showThinkingSummaries":false,"env":{"OTHER":"kept","ANTHROPIC_BASE_URL":"https://old.example.test"}}'`,
     "--settings user-settings.json",
   ])("merges %s beneath T3's settings", (launchArgs) =>
     Effect.scoped(
@@ -1094,7 +1094,7 @@ describe("ClaudeAdapterV2 append-system-prompt-file launch argument", () => {
         const cwd = yield* fileSystem.makeTempDirectoryScoped({ prefix: "t3-claude-settings-" });
         yield* fileSystem.writeFileString(
           NodePath.join(cwd, "user-settings.json"),
-          '{"skillOverrides":{"lint":"off"},"showThinkingSummaries":false}',
+          '{"skillOverrides":{"lint":"off"},"showThinkingSummaries":false,"env":{"OTHER":"kept","ANTHROPIC_BASE_URL":"https://old.example.test"}}',
         );
         const { exit, opened } = yield* startTurnWithLaunchArgs(launchArgs, cwd);
         assert.isTrue(Exit.isSuccess(exit));
@@ -1109,6 +1109,7 @@ describe("ClaudeAdapterV2 append-system-prompt-file launch argument", () => {
         assert.deepInclude(routed.opened[0]!.settings, {
           skillOverrides: { lint: "off" },
           env: {
+            OTHER: "kept",
             ANTHROPIC_BASE_URL: proxy.url,
             ANTHROPIC_AUTH_TOKEN: proxy.apiKey,
             ANTHROPIC_API_KEY: "",
diff --git a/apps/server/src/provider/Drivers/ClaudeDriver.ts b/apps/server/src/provider/Drivers/ClaudeDriver.ts
index 14cdc7e0e5db5..e8df26c4fc789 100644
--- a/apps/server/src/provider/Drivers/ClaudeDriver.ts
+++ b/apps/server/src/provider/Drivers/ClaudeDriver.ts
@@ -201,6 +201,7 @@ export const ClaudeDriver: ProviderDriver<ClaudeSettings, ClaudeDriverEnv, Path.
       effectiveConfig,
       processEnv,
       modelCatalog,
+      proxy,
     );
 
     // Per-instance capabilities cache: keyed on binary + resolved HOME so
diff --git a/apps/server/src/textGeneration/ClaudeTextGeneration.test.ts b/apps/server/src/textGeneration/ClaudeTextGeneration.test.ts
index 3ea0502f83b33..e7aabd7010da0 100644
--- a/apps/server/src/textGeneration/ClaudeTextGeneration.test.ts
+++ b/apps/server/src/textGeneration/ClaudeTextGeneration.test.ts
@@ -66,6 +66,7 @@ function withFakeClaudeEnv<A, E, R>(
     configDirMustBe?: string;
     cwdMustNotBe?: string;
     claudeConfig?: Partial<ClaudeSettings>;
+    proxy?: { readonly url: string; readonly apiKey: string };
   },
   effectFn: (textGeneration: TextGeneration.TextGeneration["Service"]) => Effect.Effect<A, E, R>,
 ) {
@@ -190,15 +191,16 @@ function withFakeClaudeEnv<A, E, R>(
       config,
       undefined,
       Effect.succeed(SYNTHETIC_CLAUDE_MODEL_CATALOG),
+      input.proxy,
     );
     return yield* effectFn(textGeneration);
   }).pipe(Effect.scoped);
 }
 
 it.layer(layerClaudeTextGenerationTest)("ClaudeTextGeneration", (it) => {
-  it.effect(
-    "keeps canonical built-in capabilities when a custom model collides with its alias",
-    () =>
+  it.effect.each([false, true])(
+    "keeps canonical built-in capabilities when a custom model collides with its alias (proxy: %s)",
+    (proxied) =>
       withFakeClaudeEnv(
         {
           output: JSON.stringify({
@@ -207,7 +209,12 @@ it.layer(layerClaudeTextGenerationTest)("ClaudeTextGeneration", (it) => {
               body: "Body",
             },
           }),
-          argsMustContain: `--model ${SYNTHETIC_CLAUDE_CAPABLE_MODEL}[expanded] --effort max --settings {"disableAllHooks":true,"fastMode":true}`,
+          argsMustContain: proxied
+            ? '"ANTHROPIC_BASE_URL":"http://proxy.test:8317"'
+            : `--model ${SYNTHETIC_CLAUDE_CAPABLE_MODEL}[expanded] --effort max --settings {"disableAllHooks":true,"fastMode":true}`,
+          ...(proxied
+            ? { proxy: { url: "http://proxy.test:8317", apiKey: "proxy-test-key" } }
+            : {}),
           claudeConfig: { customModels: [SYNTHETIC_CLAUDE_COLLIDING_ALIAS] },
         },
         (textGeneration) =>
diff --git a/apps/server/src/textGeneration/ClaudeTextGeneration.ts b/apps/server/src/textGeneration/ClaudeTextGeneration.ts
index 8fa9ccb1c8094..e9d03860f1b0f 100644
--- a/apps/server/src/textGeneration/ClaudeTextGeneration.ts
+++ b/apps/server/src/textGeneration/ClaudeTextGeneration.ts
@@ -7,6 +7,7 @@ import { ChildProcess, ChildProcessSpawner } from "effect/process";
 
 import { type ClaudeSettings, TextGenerationError } from "@t3tools/contracts";
 import { resolveSpawnCommand } from "@t3tools/shared/shell";
+import type { ProviderProxyRoute } from "@t3tools/provider-core/server/providerProxy";
 
 import * as TextGenerationOperations from "@t3tools/provider-core/server/textGenerationOperations";
 import {
@@ -31,6 +32,7 @@ import {
 } from "../provider/ClaudeModelCatalog.ts";
 import {
   hasClaudeManagedMcpConfig,
+  claudeProxySettingsEnvironment,
   makeClaudeEnvironment,
 } from "../provider/Drivers/ClaudeHome.ts";
 
@@ -81,6 +83,7 @@ export const makeClaudeTextGeneration = Effect.fn("makeClaudeTextGeneration")(fu
   claudeSettings: ClaudeSettings,
   environment?: NodeJS.ProcessEnv,
   modelCatalog: Effect.Effect<ClaudeModelCatalog> = Effect.succeed(BUNDLED_CLAUDE_MODEL_CATALOG),
+  proxy?: ProviderProxyRoute,
 ) {
   const commandSpawner = yield* ChildProcessSpawner.ChildProcessSpawner;
   const fileSystem = yield* FileSystem.FileSystem;
@@ -171,6 +174,7 @@ export const makeClaudeTextGeneration = Effect.fn("makeClaudeTextGeneration")(fu
       fastModeDescriptor?.type === "boolean" ? fastModeDescriptor.currentValue : undefined;
     const settings = {
       disableAllHooks: true,
+      ...(proxy === undefined ? {} : { env: claudeProxySettingsEnvironment(proxy) }),
       ...(typeof thinking === "boolean" ? { alwaysThinkingEnabled: thinking } : {}),
       ...(fastMode ? { fastMode: true } : {}),
       ...(ultracode ? { ultracode: true } : {}),

From 35014f567861f40b39697474b6fe949f9afa2677 Mon Sep 17 00:00:00 2001
From: SAPHID <saphid@users.noreply.github.com>
Date: Sat, 31 Oct 2026 14:15:36 +0000
Subject: [PATCH 25/26] fix(claude): keep proxy credentials out of process
 arguments

---
 .../ClaudeTextGeneration.test.ts              | 40 +++++++++++++++++--
 .../textGeneration/ClaudeTextGeneration.ts    | 25 +++++++++++-
 .../testing/ClaudeTextGeneration.fixture.mjs  | 26 +++++++++++-
 3 files changed, 85 insertions(+), 6 deletions(-)

diff --git a/apps/server/src/textGeneration/ClaudeTextGeneration.test.ts b/apps/server/src/textGeneration/ClaudeTextGeneration.test.ts
index e7aabd7010da0..f8dd41aeaa2ce 100644
--- a/apps/server/src/textGeneration/ClaudeTextGeneration.test.ts
+++ b/apps/server/src/textGeneration/ClaudeTextGeneration.test.ts
@@ -68,13 +68,20 @@ function withFakeClaudeEnv<A, E, R>(
     claudeConfig?: Partial<ClaudeSettings>;
     proxy?: { readonly url: string; readonly apiKey: string };
   },
-  effectFn: (textGeneration: TextGeneration.TextGeneration["Service"]) => Effect.Effect<A, E, R>,
+  effectFn: (
+    textGeneration: TextGeneration.TextGeneration["Service"],
+    tempDir: string,
+  ) => Effect.Effect<A, E, R>,
 ) {
   return Effect.gen(function* () {
     const fs = yield* FileSystem.FileSystem;
     const tempDir = yield* fs.makeTempDirectoryScoped({ prefix: "t3code-claude-text-" });
     const binDir = yield* makeFakeClaudeBinary(tempDir, input.lifecyclePort);
     const pathDelimiter = (yield* HostProcess.isWindows) ? ";" : ":";
+    const path = yield* Path.Path;
+    const platform = yield* HostProcess.Platform;
+    const previousSettingsExpected = process.env.T3_FAKE_CLAUDE_SETTINGS_EXPECTED;
+    const previousSettingsReceipt = process.env.T3_FAKE_CLAUDE_SETTINGS_RECEIPT;
     const previousPath = process.env.PATH;
     const previousOutput = process.env.T3_FAKE_CLAUDE_OUTPUT;
     const previousExitCode = process.env.T3_FAKE_CLAUDE_EXIT_CODE;
@@ -87,6 +94,16 @@ function withFakeClaudeEnv<A, E, R>(
 
     yield* Effect.acquireRelease(
       Effect.sync(() => {
+        if (input.proxy === undefined) {
+          delete process.env.T3_FAKE_CLAUDE_SETTINGS_EXPECTED;
+          delete process.env.T3_FAKE_CLAUDE_SETTINGS_RECEIPT;
+        } else {
+          process.env.T3_FAKE_CLAUDE_SETTINGS_EXPECTED = JSON.stringify({
+            ...input.proxy,
+            platform,
+          });
+          process.env.T3_FAKE_CLAUDE_SETTINGS_RECEIPT = path.join(tempDir, "settings-path.txt");
+        }
         process.env.PATH = `${binDir}${pathDelimiter}${previousPath ?? ""}`;
         process.env.T3_FAKE_CLAUDE_OUTPUT = input.output;
 
@@ -134,6 +151,12 @@ function withFakeClaudeEnv<A, E, R>(
       }),
       () =>
         Effect.sync(() => {
+          if (previousSettingsExpected === undefined)
+            delete process.env.T3_FAKE_CLAUDE_SETTINGS_EXPECTED;
+          else process.env.T3_FAKE_CLAUDE_SETTINGS_EXPECTED = previousSettingsExpected;
+          if (previousSettingsReceipt === undefined)
+            delete process.env.T3_FAKE_CLAUDE_SETTINGS_RECEIPT;
+          else process.env.T3_FAKE_CLAUDE_SETTINGS_RECEIPT = previousSettingsReceipt;
           process.env.PATH = previousPath;
 
           if (previousOutput === undefined) {
@@ -193,7 +216,7 @@ function withFakeClaudeEnv<A, E, R>(
       Effect.succeed(SYNTHETIC_CLAUDE_MODEL_CATALOG),
       input.proxy,
     );
-    return yield* effectFn(textGeneration);
+    return yield* effectFn(textGeneration, tempDir);
   }).pipe(Effect.scoped);
 }
 
@@ -209,15 +232,16 @@ it.layer(layerClaudeTextGenerationTest)("ClaudeTextGeneration", (it) => {
               body: "Body",
             },
           }),
+          ...(proxied ? { argsMustNotContain: "proxy-test-key" } : {}),
           argsMustContain: proxied
-            ? '"ANTHROPIC_BASE_URL":"http://proxy.test:8317"'
+            ? "--effort max --settings"
             : `--model ${SYNTHETIC_CLAUDE_CAPABLE_MODEL}[expanded] --effort max --settings {"disableAllHooks":true,"fastMode":true}`,
           ...(proxied
             ? { proxy: { url: "http://proxy.test:8317", apiKey: "proxy-test-key" } }
             : {}),
           claudeConfig: { customModels: [SYNTHETIC_CLAUDE_COLLIDING_ALIAS] },
         },
-        (textGeneration) =>
+        (textGeneration, tempDir) =>
           Effect.gen(function* () {
             const generated = yield* textGeneration.generatePrContent({
               cwd: process.cwd(),
@@ -239,6 +263,14 @@ it.layer(layerClaudeTextGenerationTest)("ClaudeTextGeneration", (it) => {
             });
 
             expect(generated.title).toBe("Improve orchestration flow");
+            if (proxied) {
+              const fs = yield* FileSystem.FileSystem;
+              const path = yield* Path.Path;
+              const settingsPath = yield* fs.readFileString(
+                path.join(tempDir, "settings-path.txt"),
+              );
+              expect(yield* fs.exists(settingsPath)).toBe(false);
+            }
           }),
       ),
   );
diff --git a/apps/server/src/textGeneration/ClaudeTextGeneration.ts b/apps/server/src/textGeneration/ClaudeTextGeneration.ts
index e9d03860f1b0f..3db69dcd1f87b 100644
--- a/apps/server/src/textGeneration/ClaudeTextGeneration.ts
+++ b/apps/server/src/textGeneration/ClaudeTextGeneration.ts
@@ -1,6 +1,7 @@
 import * as Effect from "effect/Effect";
 import * as FileSystem from "effect/FileSystem";
 import * as Option from "effect/Option";
+import * as Path from "effect/Path";
 import * as Schema from "effect/Schema";
 import * as Stream from "effect/Stream";
 import { ChildProcess, ChildProcessSpawner } from "effect/process";
@@ -87,6 +88,7 @@ export const makeClaudeTextGeneration = Effect.fn("makeClaudeTextGeneration")(fu
 ) {
   const commandSpawner = yield* ChildProcessSpawner.ChildProcessSpawner;
   const fileSystem = yield* FileSystem.FileSystem;
+  const path = yield* Path.Path;
   const claudeEnvironment = yield* makeClaudeEnvironment(claudeSettings, environment);
   const scopedModelCatalog = modelCatalog.pipe(
     Effect.map((catalog) => scopeClaudeModelCatalog(catalog, claudeSettings.customModels)),
@@ -196,6 +198,27 @@ export const makeClaudeTextGeneration = Effect.fn("makeClaudeTextGeneration")(fu
                 ),
               )
           : cwd;
+      const settingsArgument =
+        proxy === undefined
+          ? settingsJson
+          : yield* Effect.gen(function* () {
+              const directory = yield* fileSystem.makeTempDirectoryScoped({
+                prefix: "t3code-claude-settings-",
+              });
+              yield* fileSystem.chmod(directory, 0o700);
+              const settingsPath = path.join(directory, "settings.json");
+              yield* fileSystem.writeFileString(settingsPath, settingsJson, { mode: 0o600 });
+              return settingsPath;
+            }).pipe(
+              Effect.mapError((cause) =>
+                normalizeCliError(
+                  "claude",
+                  operation,
+                  cause,
+                  "Failed to prepare Claude CLI settings",
+                ),
+              ),
+            );
       const managedMcpConfig = yield* hasClaudeManagedMcpConfig();
       const spawnCommand = yield* resolveSpawnCommand(
         claudeSettings.binaryPath || "claude",
@@ -209,7 +232,7 @@ export const makeClaudeTextGeneration = Effect.fn("makeClaudeTextGeneration")(fu
           resolveClaudeCatalogApiModelId(catalog, resolvedModelSelection),
           ...(cliEffort ? ["--effort", cliEffort] : []),
           "--settings",
-          settingsJson,
+          settingsArgument,
           ...(investigate
             ? [
                 "--tools",
diff --git a/apps/server/src/textGeneration/testing/ClaudeTextGeneration.fixture.mjs b/apps/server/src/textGeneration/testing/ClaudeTextGeneration.fixture.mjs
index d5ca2f185eb8d..d9c99b6c303d5 100644
--- a/apps/server/src/textGeneration/testing/ClaudeTextGeneration.fixture.mjs
+++ b/apps/server/src/textGeneration/testing/ClaudeTextGeneration.fixture.mjs
@@ -1,4 +1,5 @@
 import * as NodeFS from "node:fs";
+import * as NodePath from "node:path";
 
 const argv = process.argv.slice(2);
 const args = argv.join(" ");
@@ -26,7 +27,30 @@ if (!argv.includes("--strict-mcp-config")) {
   fail("text generation must not load configured MCP servers", 9);
 }
 const settingsIndex = argv.indexOf("--settings");
-if (settingsIndex === -1 || JSON.parse(argv[settingsIndex + 1]).disableAllHooks !== true) {
+const settingsArgument = argv[settingsIndex + 1];
+const expectedProxy = process.env.T3_FAKE_CLAUDE_SETTINGS_EXPECTED;
+if (expectedProxy) {
+  const { url, apiKey, platform } = JSON.parse(expectedProxy);
+  if (args.includes(apiKey)) fail("proxy settings exposed in argv", 13);
+  const settings = JSON.parse(NodeFS.readFileSync(settingsArgument, "utf8"));
+  if (settings.env?.ANTHROPIC_BASE_URL !== url || settings.env?.ANTHROPIC_AUTH_TOKEN !== apiKey) {
+    fail("settings file missing proxy route", 14);
+  }
+  if (
+    platform !== "win32" &&
+    ((NodeFS.statSync(settingsArgument).mode & 0o777) !== 0o600 ||
+      (NodeFS.statSync(NodePath.dirname(settingsArgument)).mode & 0o777) !== 0o700)
+  ) {
+    fail("settings file permissions expose credentials", 15);
+  }
+  NodeFS.writeFileSync(process.env.T3_FAKE_CLAUDE_SETTINGS_RECEIPT, settingsArgument);
+}
+const settings = JSON.parse(
+  settingsArgument.startsWith("{")
+    ? settingsArgument
+    : NodeFS.readFileSync(settingsArgument, "utf8"),
+);
+if (settingsIndex === -1 || settings.disableAllHooks !== true) {
   fail("text generation must disable hooks", 10);
 }
 const cwdMustNotBe = process.env.T3_FAKE_CLAUDE_CWD_MUST_NOT_BE;

From b97e463e2e64929b15738eda95e6613f2602bbde Mon Sep 17 00:00:00 2001
From: maria-rcks <maria@kuuro.net>
Date: Sat, 31 Oct 2026 19:23:50 +0000
Subject: [PATCH 26/26] fix(server): refresh cached sessions after provider
 routing changes

---
 .../ProviderAdapterRegistry.ts                |  8 +++
 .../ProviderSessionManager.test.ts            | 58 ++++++++++++++++++-
 .../ProviderSessionManager.ts                 | 41 ++++++++++++-
 3 files changed, 105 insertions(+), 2 deletions(-)

diff --git a/apps/server/src/orchestration-v2/ProviderAdapterRegistry.ts b/apps/server/src/orchestration-v2/ProviderAdapterRegistry.ts
index a04c1df887277..44c8ea2c330ec 100644
--- a/apps/server/src/orchestration-v2/ProviderAdapterRegistry.ts
+++ b/apps/server/src/orchestration-v2/ProviderAdapterRegistry.ts
@@ -42,6 +42,9 @@ export interface ProviderAdapterRegistryV2Shape {
   readonly get: (
     instanceId: ProviderInstanceId,
   ) => Effect.Effect<ProviderAdapter.ProviderAdapterV2["Service"], ProviderAdapterRegistryV2Error>;
+  readonly getRuntimeIdentity?: (
+    instanceId: ProviderInstanceId,
+  ) => Effect.Effect<object | undefined>;
   readonly list: () => Effect.Effect<ReadonlyArray<ProviderInstanceId>>;
   readonly getMetadata?: (instanceId: ProviderInstanceId) => Effect.Effect<
     {
@@ -68,6 +71,11 @@ export const layerFromProviderInstanceRegistry: Layer.Layer<
   Effect.gen(function* () {
     const instances = yield* ProviderInstanceRegistry.ProviderInstanceRegistry;
     return ProviderAdapterRegistryV2.of({
+      getRuntimeIdentity: Effect.fn("ProviderAdapterRegistryV2.getRuntimeIdentity")((instanceId) =>
+        instances
+          .getInstance(instanceId)
+          .pipe(Effect.map((instance) => instance?.orchestrationAdapter)),
+      ),
       get: Effect.fn("ProviderAdapterRegistryV2.get")(function (instanceId) {
         return instances.getInstance(instanceId).pipe(
           Effect.flatMap((instance) => {
diff --git a/apps/server/src/orchestration-v2/ProviderSessionManager.test.ts b/apps/server/src/orchestration-v2/ProviderSessionManager.test.ts
index 5bbb3926e2b66..a295e7f761a72 100644
--- a/apps/server/src/orchestration-v2/ProviderSessionManager.test.ts
+++ b/apps/server/src/orchestration-v2/ProviderSessionManager.test.ts
@@ -464,6 +464,7 @@ function layerTest(input: {
   readonly state: Ref.Ref<TestProviderRuntimeState>;
   readonly idleTimeoutMs: number;
   readonly maxIdlePinMs?: number;
+  readonly runtimeIdentity?: Ref.Ref<object>;
   readonly failEventStream?: boolean;
   readonly capabilities?: OrchestrationV2ProviderCapabilities;
   readonly mcpConfigs?: Ref.Ref<
@@ -528,7 +529,17 @@ function layerTest(input: {
       ...(input.scopeCloseReached === undefined
         ? {}
         : { scopeCloseReached: input.scopeCloseReached }),
-    }).pipe(Effect.map(ProviderAdapterRegistry.layerSingle)),
+    }).pipe(
+      Effect.map((adapter) =>
+        input.runtimeIdentity === undefined
+          ? ProviderAdapterRegistry.layerSingle(adapter)
+          : Layer.succeed(ProviderAdapterRegistry.ProviderAdapterRegistryV2, {
+              get: () => Effect.succeed(adapter),
+              list: () => Effect.succeed([adapter.instanceId]),
+              getRuntimeIdentity: () => Ref.get(input.runtimeIdentity!),
+            }),
+      ),
+    ),
   );
   const layerConfiguredMcpRegistry =
     input.pauseResolve === undefined
@@ -3411,6 +3422,51 @@ it.effect(
     }),
 );
 
+it.effect(
+  "ProviderSessionManagerV2 replaces a cached session when its provider route changes",
+  () =>
+    Effect.gen(function* () {
+      const state = yield* Ref.make(emptyState);
+      const runtimeIdentity = yield* Ref.make<object>({});
+      const pendingWork = yield* Ref.make(false);
+      yield* Effect.gen(function* () {
+        const manager = yield* ProviderSessionManager.ProviderSessionManagerV2;
+        const eventSink = yield* EventSink.EventSinkV2;
+        const idAllocator = yield* IdAllocator.IdAllocatorV2;
+        const threadId = ThreadId.make("proxy-route-change");
+        const now = yield* DateTime.now;
+        yield* eventSink.write({
+          events: [yield* makeThreadCreatedEvent({ idAllocator, threadId, now })],
+        });
+        const providerSessionId = idAllocator.derive.providerSession({
+          providerInstanceId: modelSelection.instanceId,
+        });
+        const input = { threadId, providerSessionId, modelSelection, runtimePolicy };
+        const direct = yield* manager.open(input);
+        assert.strictEqual(yield* manager.open(input), direct);
+        yield* Ref.set(runtimeIdentity, {});
+        yield* Ref.set(pendingWork, true);
+        assert.isTrue(Exit.isFailure(yield* Effect.exit(manager.open(input))));
+        assert.equal((yield* Ref.get(state)).closeCount, 0);
+        yield* Ref.set(pendingWork, false);
+        const proxied = yield* manager.open(input);
+        assert.notStrictEqual(proxied, direct);
+        assert.equal((yield* Ref.get(state)).openCount, 2);
+        assert.equal((yield* Ref.get(state)).closeCount, 1);
+        assert.strictEqual(yield* manager.open(input), proxied);
+      }).pipe(
+        Effect.provide(
+          layerTest({
+            state,
+            runtimeIdentity,
+            idleTimeoutMs: 60000,
+            hasPendingBackgroundWork: Ref.get(pendingWork),
+          }),
+        ),
+      );
+    }),
+);
+
 it.effect(
   "ProviderSessionManagerV2 invalidates only errored threads and keeps reusable session errors cached",
   () =>
diff --git a/apps/server/src/orchestration-v2/ProviderSessionManager.ts b/apps/server/src/orchestration-v2/ProviderSessionManager.ts
index 03a7278774a64..852a03c3b28df 100644
--- a/apps/server/src/orchestration-v2/ProviderSessionManager.ts
+++ b/apps/server/src/orchestration-v2/ProviderSessionManager.ts
@@ -216,6 +216,7 @@ export class ProviderSessionManagerV2 extends Context.Service<
 >()("t3/orchestration-v2/ProviderSessionManager/ProviderSessionManagerV2") {}
 
 interface LiveSessionEntry {
+  readonly runtimeIdentity: object | undefined;
   readonly attachedThreadIds: ReadonlySet<ThreadId>;
   readonly loadedProviderThreadKeyByThread: ReadonlyMap<ThreadId, string>;
   /** Scope revocation to recorded credential ids so superseded sessions cannot revoke replacements opened before detach. */
@@ -2135,7 +2136,44 @@ export const layerWithOptions = (
                 }
               }
               const key = sessionKey(input.providerSessionId);
-              const existing = (yield* Ref.get(sessions)).get(key);
+              const runtimeIdentity =
+                registry.getRuntimeIdentity === undefined
+                  ? undefined
+                  : yield* registry.getRuntimeIdentity(input.modelSelection.instanceId);
+              let existing = (yield* Ref.get(sessions)).get(key);
+              if (existing !== undefined && existing.runtimeIdentity !== runtimeIdentity) {
+                const changedSettings = () =>
+                  new ProviderSessionOpenError({
+                    instanceId: input.modelSelection.instanceId,
+                    providerSessionId: input.providerSessionId,
+                    cause:
+                      "Provider settings changed. Wait for its active work to finish before starting another turn.",
+                  });
+                const pending =
+                  existing.runtime.hasPendingBackgroundWork === undefined
+                    ? false
+                    : yield* existing.runtime.hasPendingBackgroundWork;
+                if (existing.busyTurns.size > 0 || pending) {
+                  return yield* changedSettings();
+                }
+                yield* releaseEntry({
+                  providerSessionId: input.providerSessionId,
+                  reason: "manual_shutdown",
+                  detail: "Provider settings changed.",
+                  onlyIfIdleGeneration: existing.idleGeneration,
+                }).pipe(
+                  Effect.mapError(
+                    (cause) =>
+                      new ProviderSessionOpenError({
+                        instanceId: input.modelSelection.instanceId,
+                        providerSessionId: input.providerSessionId,
+                        cause,
+                      }),
+                  ),
+                );
+                if ((yield* Ref.get(sessions)).has(key)) return yield* changedSettings();
+                existing = undefined;
+              }
               if (existing !== undefined) {
                 const attached = existing.attachedThreadIds.has(input.threadId);
                 if (!attached && !existing.supportsMultipleProviderThreads) {
@@ -2234,6 +2272,7 @@ export const layerWithOptions = (
               >(new Map());
               const exposedRuntime = decorateRuntime(runtime, eventSubscribers);
               const entry: LiveSessionEntry = {
+                runtimeIdentity,
                 attachedThreadIds: new Set([input.threadId]),
                 loadedProviderThreadKeyByThread: new Map(),
                 mcpCredentialIdByThread: