# ChatGPT Orchestrator Operations

## Execution Continuity

See [`EXECUTION-CONTINUITY.md`](./EXECUTION-CONTINUITY.md) for Auto Resume, operator controls, stall behavior, checkpoint/live-steering semantics, dead-man recovery, privacy boundaries and the backend/executor responsibility split.

## Runtime services

The orchestrator uses two user services.

### MCP/executor service

Install the checked-in unit:

```bash
mkdir -p ~/.config/systemd/user ~/.config/chatgpt-orchestrator ~/.local/state/chatgpt-orchestrator
cp deploy/systemd/chatgpt-orchestrator.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now chatgpt-orchestrator.service
```

Verify:

```bash
systemctl --user is-active chatgpt-orchestrator.service
curl -fsS http://127.0.0.1:8764/healthz
```

`/healthz` reports the executor bridge address and whether a browser executor is currently authenticated.

### OpenAI Secure MCP Tunnel

The dedicated tunnel profile is named `chatgpt-orchestrator` and points at:

```text
http://127.0.0.1:8764/mcp
```

The tunnel should use a normal runtime API key with tunnel-use permission, not an Admin API key. Keep the API key and the MCP bearer header outside Git under `~/.config/chatgpt-orchestrator/`.

Install the launcher and unit:

```bash
install -m 755 deploy/tunnel/run-tunnel.sh ~/.local/lib/chatgpt-orchestrator/run-tunnel.sh
cp deploy/systemd/chatgpt-orchestrator-tunnel.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now chatgpt-orchestrator-tunnel.service
```

Verify:

```bash
systemctl --user is-active chatgpt-orchestrator-tunnel.service
health_url="$(cat ~/.local/state/chatgpt-orchestrator/tunnel-health.url)"
curl -fsS "$health_url/readyz"
```

A healthy startup log includes an MCP session initialized against `@platform-modules/chatgpt-orchestrator-mcp`.

In ChatGPT, create/select the MCP app using the dedicated **chatgpt-orchestrator** tunnel. Do not configure ChatGPT to call `127.0.0.1` directly.

## Firefox / LibreWolf deployment

Build a locally paired XPI without printing or committing the executor token:

```bash
CHATGPT_ORCHESTRATOR_EXECUTOR_TOKEN="$(cat ~/.config/chatgpt-orchestrator/executor-token)" \
  node apps/extension/scripts/build.mjs --package
```

For a private unsigned LibreWolf deployment, the profile may require:

```text
xpinstall.signatures.required = false
extensions.autoDisableScopes = 0
extensions.enabledScopes = 15
```

Place the XPI at the profile extension ID path:

```text
<profile>/extensions/chatgpt-orchestrator@alexcodeplace.xpi
```

Keep a paired XPI mode `0600`, because it contains the local executor credential.

Do not terminate or restart an active user browser automatically as part of deployment. Stage the updated XPI first; if browser activation requires a restart/reload, leave that action to the user.

## Chromium deployment

Chromium 142+ protects loopback/local-network requests with Local Network Access (LNA) permission. The extension service worker cannot itself display the LNA prompt reliably. The Chromium options page therefore exposes **Allow local executor access**. Use that control once and approve Chromium's loopback/local-network permission prompt; the executor connection then retries automatically.

This permission belongs to Chromium/browser policy and is not part of the worker Agent Skill.

## Security boundaries

- MCP and executor listeners are loopback-only.
- MCP and executor authentication secrets never enter prompts or URLs.
- The extension controls only tabs it created and persisted as managed bindings.
- The extension sends conversation ID/URL and coarse lifecycle state, not full conversation contents.
- The executor has no generic arbitrary-DOM or `window.postMessage` privileged bridge.
- ChatGPT communication uses the OpenAI Secure MCP Tunnel rather than a public inbound listener.