Skip to content

fix(startup): avoid permission-sensitive service re-registration #970

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
stephen-drew wants to merge 4 commits into from
Closed

fix(startup): avoid permission-sensitive service re-registration #970

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
0153f0b
fix(update): repair existing service without re-registration
stephen-drew Aug 3, 2026
b15df8f
fix(startup): avoid permission-sensitive service reinstall
stephen-drew Aug 3, 2026
3730bad
docs: explain permission-safe service recovery
stephen-drew Aug 3, 2026
6135abf
test(update): align deploy contract with service repair
stephen-drew Aug 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 10 additions & 16 deletions bin/ocx.mjs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -134,19 +134,15 @@ function runNpmSelfUpdate() {
}

// Remember whether a background service manages the proxy BEFORE stopping — `ocx stop`
// unloads it permanently, so a successful update must reinstall it afterwards.
// unloads it, so a successful update must refresh and restart it afterwards.
const serviceStatePath = join(configDir(), "service-state.json");
const serviceWasInstalled = existsSync(serviceStatePath);
const trayBeforeUpdate = planWindowsTrayUpdate(
process.platform === "win32" ? trayInstallState() : { installed: false, running: false },
);
/** Read the backend from service-state.json so the update reinstalls the same one. */
/** Refresh the existing backend without re-registering it from a non-elevated updater. */
function serviceReinstallArgs() {
try {
const state = JSON.parse(readFileSync(serviceStatePath, "utf8"));
if (state.backend === "native") return [launcher, "service", "install", "--native"];
} catch { /* missing or corrupt — fall through to default */ }
return [launcher, "service", "install"];
return [launcher, "service", "repair"];
}

// Capture listen target before stop clears runtime-port.json (mirrors GUI/CLI update worker).
Expand Down Expand Up @@ -241,10 +237,10 @@ function runNpmSelfUpdate() {
if (trayBeforeUpdate.restoreOnFailure) runTrayLifecycle(launcher, "start");
}
}
// The stop above unloaded any managed service; reinstall via the freshly-installed
// launcher so the new files write the baked paths and the service restarts.
// The stop above unloaded any managed service; repair via the freshly-installed
// launcher so the new files write the baked paths and the existing manager restarts.
if (serviceWasInstalled) {
console.log("Reinstalling the background service with the updated files...");
console.log("Refreshing the background service with the updated files...");
const prevBake = process.env.OCX_BAKE_PORT;
process.env.OCX_BAKE_PORT = String(bakePort);
try {
Expand Down Expand Up @@ -274,17 +270,15 @@ function runNpmSelfUpdate() {
}
}
if (needDirectStart) {
// On Windows, schtasks /create requires elevation. The launcher inherits the
// user's (non-admin) token, so the service reinstall can fail with access
// denied — or exit 0 while leaving a non-viable manager. Fall back to a
// direct detached proxy start so the update never leaves the user without
// a running proxy.
// A repair can still fail, or exit 0 while leaving a non-viable manager.
// Fall back to a direct detached proxy start so the update never leaves the
// user without a running proxy.
console.warn(
svc.status === 0
? "opencodex: service refresh left a non-viable manager — starting the proxy directly instead."
: "opencodex: service refresh failed — starting the proxy directly instead.",
);
console.warn(" Run 'ocx service install' as administrator to refresh the background service.");
console.warn(" Run 'ocx service repair' to see why the background service could not restart.");
const env = { ...process.env };
delete env.OCX_SERVICE;
const child = spawn(process.execPath, [launcher, "start", "--port", String(bakePort)], {
Expand Down
2 changes: 1 addition & 1 deletion docs-site/src/content/docs/guides/web-dashboard.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ the browser or password manager's decision.
| **Sub-agent delegation** | Choose a native or routed model and optional reasoning effort shared by OpenCodex delegation guidance and the separate native-default opt-in. This is not a proxy-side per-spawn router; see below. |
| **Sidecars** | Choose the web-search model and effort plus the vision-description model. Changes apply on the next request. |
| **Maintenance** | Resync the Codex model catalog, inspect project-local config bypass warnings, check the latest or preview release, and run an update with optional proxy restart. |
| **Startup safety** | Show whether injected Codex routing survives a restart, with separate service and launcher-shim health plus exact repair commands. |
| **Startup safety** | Show whether injected Codex routing survives a restart, with separate service and launcher-shim health plus state-aware commands: Start for a clean stopped service, Repair for an installed unhealthy service, and Install only when registration is missing or must be replaced. |
| **Windows tray** | Install a per-user login tray for one-click proxy start, stop, restart, dashboard access, and status. The tray is a controller, not a proxy restart service. |
| **Codex autostart** | Allow an already-installed Codex launcher shim to run `ocx ensure`. This toggle does not install a shim or background service. |
| **Providers** | Add, edit, set the default (enabled providers only), enable/disable, and remove providers; manage OAuth account pools and API-key pools where supported. Removing the current default switches to the first remaining enabled provider when one exists; otherwise deletion is refused and the current default is kept. Provider Settings can disable live model discovery for endpoints with missing, slow, or oversized `/models` catalogs. For Claude (Anthropic) OAuth pools, each logged-in account shows its own 5-hour and weekly rate-limit bars (usage is per credential); a failed probe keeps the last-known bars and marks them unavailable until the next successful refresh. |
Expand Down
8 changes: 6 additions & 2 deletions docs-site/src/content/docs/ja/reference/cli/lifecycle.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -135,14 +135,15 @@ Codex のローカル モデル ピッカー キャッシュを無効にし、

## バックグラウンドサービス

### `ocx service [install|start|stop|status|uninstall|remove]`
### `ocx service [install|repair|start|stop|status|uninstall|remove]`

opencodex を、ログイン時に自動起動し、クラッシュ時に自動再起動するログイン管理バックグラウンド サービス (macOS **launchd**、Linux **systemd ユーザー ユニット**、Windows **タスク スケジューラ**) として実行します。サービスは `OCX_SERVICE=1` を設定して実行されるため、再起動によって Codex 設定が変更されることはありません。

|サブコマンド |アクション |
| --- | --- |
|なし |サービスを作成/更新して開始します。 |
| `install` |サービスを作成して開始します。 |
| `repair` |既存のサービスを再登録せずに更新して再起動します。 |
| `start` |インストールされているサービスを開始します。 |
| `stop` |サービスを停止し、ネイティブ Codex を復元します。 |
| `status` |サービスとプロキシの診断とログ パスをレポートします。 |
Expand All @@ -152,10 +153,13 @@ opencodex を、ログイン時に自動起動し、クラッシュ時に自動
```bash
ocx service
ocx service install
ocx service repair
ocx service status
ocx service uninstall
```

`ocx repair` は `ocx service repair` の別名です。既存の有効なサービスには、正常だが停止している場合は `start`、生成されたアセットが古い、または異常な場合は `repair` を使用します。`install` は新規登録または明示的な再登録にのみ使用し、Windows では管理者の承認が必要になる場合があります。

Windows では、`ocx service status` は、ID 検証済みの OpenCodex プロキシの到達可能性とは別に、タスク スケジューラの登録を報告します。ローカライズされた `schtasks` テーブルは出力されないため、概要は Windows コード ページ間で読み取れるままです。

Windows では、タスク スケジューラ エントリを作成するには昇格が必要です。認識されたローカライズされたアクセス拒否テキストは、既存のガイダンス パスを維持します。そのテキストが判読できない場合、フォールバックには、所有されているコマンド形状 `/create /tn opencodex-proxy /xml <non-empty-path> /f`、ステータス 1、および確認済みの非昇格トークンが必要です。ダッシュボードのスタートアップ セーフティ アクションは、UAC を自動的に要求できるようになります。そのフォールバックがトークンの状態を判断できない場合、元のスケジューラ エラーが保持されます。外部タスクおよび操作は、自動昇格マーカーを発行することはできません。ダッシュボードの UAC プロンプトを承認するか、管理者特権の PowerShell ウィンドウで `ocx service install` を再実行します。
Expand Down Expand Up @@ -197,7 +201,7 @@ Windows ステータス トレイ アイコンをインストールして制御

### `ocx update [--tag latest|preview]`

npm から opencodex を自己更新します。安定したインストールでは `@latest` を使用します。 `--tag latest|preview` を渡さない限り、プレビュー インストールは `@preview` に残ります。ソース チェックアウトを検出し、代わりに `git pull && bun install` を使用するように指示しますが、そのタグの最新バージョンをすでに使用している場合は何もしません。実行中のプロキシは、ファイルが置き換えられる前に停止されます。インストールされたサービスは再構築されて自動的に開始されますが、フォアグラウンド インストールでは次のステップとして `ocx start` が出力されます。
npm から opencodex を自己更新します。安定したインストールでは `@latest` を使用します。 `--tag latest|preview` を渡さない限り、プレビュー インストールは `@preview` に残ります。ソース チェックアウトを検出し、代わりに `git pull && bun install` を使用するように指示しますが、そのタグの最新バージョンをすでに使用している場合は何もしません。実行中のプロキシは、ファイルが置き換えられる前に停止されます。既存のサービスは再登録しない repair パスで更新され、自動的に開始されます。サービスが実際に存在しない場合のみ通常の install パスを使用し、フォアグラウンド インストールでは次のステップとして `ocx start` が出力されます。

```bash
ocx update
Expand Down
11 changes: 8 additions & 3 deletions docs-site/src/content/docs/ko/reference/cli/lifecycle.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -176,7 +176,7 @@ Codex의 로컬 모델 선택기 캐시를 무효화하여, 활성 opencodex 카

## 백그라운드 서비스

### `ocx service [install|start|stop|status|uninstall|remove]`
### `ocx service [install|repair|start|stop|status|uninstall|remove]`

로그인 관리형 백그라운드 서비스로 opencodex를 실행합니다(macOS **launchd**, Linux **systemd** 사용자
유닛, Windows **Task Scheduler**). 로그인 시 자동 시작하고 충돌 시 자동 재시작합니다. 서비스 실행은
Expand All @@ -186,6 +186,7 @@ Codex의 로컬 모델 선택기 캐시를 무효화하여, 활성 opencodex 카
| --- | --- |
| 없음 | 서비스를 생성/업데이트하고 시작합니다. |
| `install` | 서비스를 생성하고 시작합니다. |
| `repair` | 기존 서비스를 다시 등록하지 않고 새로 고친 뒤 재시작합니다. |
| `start` | 설치된 서비스를 시작합니다. |
| `stop` | 서비스를 중지하고 기본 Codex를 복원합니다. |
| `status` | 서비스와 프록시 진단, 로그 경로를 보고합니다. |
Expand All @@ -195,10 +196,13 @@ Codex의 로컬 모델 선택기 캐시를 무효화하여, 활성 opencodex 카
```bash
ocx service
ocx service install
ocx service repair
ocx service status
ocx service uninstall
```

`ocx repair`는 `ocx service repair`의 별칭입니다. 기존의 활성 서비스가 정상적으로 중지된 상태라면 `start`를, 생성된 자산이 오래되었거나 서비스가 비정상이라면 `repair`를 사용하세요. `install`은 새 등록이나 명시적인 재등록에만 사용하며, Windows에서는 관리자 승인이 필요할 수 있습니다.

Windows에서는 `ocx service status`가 Task Scheduler 등록 상태를 ID가 검증된 OpenCodex 프록시
도달 가능성과 별도로 보고합니다. 로컬라이즈된 `schtasks` 표는 출력하지 않으므로, 요약은 Windows
코드 페이지에서도 읽기 쉽습니다.
Expand Down Expand Up @@ -260,8 +264,9 @@ Windows 상태 트레이 아이콘을 설치하고 제어합니다. Windows 로
npm에서 opencodex를 자체 업데이트합니다. 안정판 설치는 `@latest`를 사용하고, 미리보기 설치는
`--tag latest|preview`를 주지 않으면 `@preview`를 유지합니다. 소스 체크아웃을 감지하면 대신
`git pull && bun install`을 실행하라고 안내하고, 해당 태그에서 이미 최신 버전이면 아무 동작도 하지
않습니다. 실행 중인 프록시가 있으면 파일을 교체하기 전에 중지합니다. 설치된 서비스는 자동으로 다시
빌드해 시작하며, 포그라운드 설치에서는 다음 단계로 `ocx start`를 출력합니다.
않습니다. 실행 중인 프록시가 있으면 파일을 교체하기 전에 중지합니다. 기존 서비스는 다시 등록하지
않는 repair 경로로 새로 고친 뒤 자동으로 시작합니다. 서비스가 실제로 없을 때만 일반 install 경로를
사용하며, 포그라운드 설치에서는 다음 단계로 `ocx start`를 출력합니다.

```bash
ocx update
Expand Down
22 changes: 18 additions & 4 deletions docs-site/src/content/docs/reference/cli/lifecycle.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,12 @@ The same action is available from the web dashboard's **Stop** button (`POST /ap
Run `stop` followed by `ensure`: stop the proxy/service, restore native Codex, start the proxy in the
background, and sync the live port back into Codex.

### `ocx repair`

Alias of `ocx service repair`. Refresh and restart an installed background service without
re-registering it with launchd, systemd, or Windows Task Scheduler. Use this when the service
already exists but its generated launcher assets are stale or it is registered but not serving.

### `ocx ensure`

Idempotently ensure a background proxy is running, then sync its live model catalog. If
Expand Down Expand Up @@ -175,7 +181,7 @@ same stale-`app-server` warning and optional `--restart-codex` behavior as `ocx

## Background service

### `ocx service [install|start|stop|status|uninstall|remove]`
### `ocx service [install|repair|start|stop|status|uninstall|remove]`

Run opencodex as a login-managed background service (macOS **launchd**, Linux **systemd user unit**,
Windows **Task Scheduler**) that auto-starts on login and auto-restarts on crash. Service runs set
Expand All @@ -185,6 +191,7 @@ Windows **Task Scheduler**) that auto-starts on login and auto-restarts on crash
| --- | --- |
| none | Create/update and start the service. |
| `install` | Create and start the service. |
| `repair` | Refresh and restart an installed service without re-registering it. |
| `start` | Start an installed service. |
| `stop` | Stop the service and restore native Codex. |
| `status` | Report service and proxy diagnostics plus log paths. |
Expand All @@ -194,10 +201,16 @@ Windows **Task Scheduler**) that auto-starts on login and auto-restarts on crash
```bash
ocx service
ocx service install
ocx service repair
ocx service status
ocx service uninstall
```

Use `install` only to create or deliberately re-register a service. On Windows that registration
may require administrator approval. For an existing enabled service, use `start` when it is clean
but stopped, or `repair` when its generated assets are stale or it is registered but unhealthy.
The shorter `ocx repair` command is an alias of `ocx service repair`.

`install`, `start`, and `repair` confirm that a proxy actually answers on the port
baked into the installed service before reporting success — on all three platforms.
They wait up to 20 seconds and then print the serving port:
Expand Down Expand Up @@ -232,7 +245,7 @@ log named in the message, and use `ocx start` to serve in the foreground meanwhi
launchd is running an OLDER plist than the one on disk.
Fix: launchctl bootout gui/$(id -u)/com.opencodex.proxy && ocx service install
Log: ~/.opencodex/service.log
Repair: ocx service install
Repair: ocx service repair
Meanwhile: ocx start (serves in the foreground)
```

Expand Down Expand Up @@ -311,8 +324,9 @@ if it is not running.
Self-update opencodex from npm. Stable installs use `@latest`; preview installs stay on `@preview`
unless you pass `--tag latest|preview`. It detects a source checkout and tells you to
`git pull && bun install` instead, and is a no-op if you are already on the newest version for that
tag. A running proxy is stopped before files are replaced; an installed service is rebuilt and
started automatically, while a foreground installation prints `ocx start` as the next step.
tag. A running proxy is stopped before files are replaced; an existing service is refreshed through
the non-registering repair path and started automatically, while a foreground installation prints
`ocx start` as the next step. A genuinely missing service still uses the normal install path.

```bash
ocx update
Expand Down
Loading
Loading