Skip to content
Back to search

chatgpt2localbridge

Codex/ChatGPT plugin app and OAuth MCP connector for approved local workspaces.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/harzva--chatgpt2localbridge/badge.svg)](/listings/harzva--chatgpt2localbridge)

HTML

<a href="/listings/harzva--chatgpt2localbridge"><img src="/api/listings/harzva--chatgpt2localbridge/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 604 lines · 4 findings marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. <img src="./docs/assets/logo.png" alt="ChatGPT2LocalBridge logo" width="180" />
  3. <h1>ChatGPT2LocalBridge</h1>
  4. <p><strong>Codex / ChatGPT Plugin App for approved local workspaces.</strong></p>
  5. <p>
  6. <img alt="Codex Plugin App" src="https://img.shields.io/badge/Codex-Plugin%20App-7c3aed.svg" />
  7. <img alt="ChatGPT Plugin App" src="https://img.shields.io/badge/ChatGPT-Plugin%20App-10a37f.svg" />
  8. <img alt="License" src="https://img.shields.io/badge/license-MIT-blue.svg" />
  9. <img alt="Node" src="https://img.shields.io/badge/node-%3E%3D20-339933.svg" />
  10. <img alt="Rust" src="https://img.shields.io/badge/rust-native%20preview-b7410e.svg" />
  11. <img alt="MCP" src="https://img.shields.io/badge/MCP-Streamable%20HTTP-1769e0.svg" />
  12. <img alt="Status" src="https://img.shields.io/badge/status-alpha-f59e0b.svg" />
  13. <img alt="GitHub stars" src="https://img.shields.io/github/stars/Harzva/chatgpt2localbridge?style=social" />
  14. </p>
  15. <p>
  16. <a href="./docs/index.html">Pages source</a>
  17. ·
  18. <a href="./docs/showcase.html">Showcase</a>
  19. ·
  20. <a href="./docs/human-tutorial.html">Human tutorial</a>
  21. ·
  22. <a href="./docs/agent-computer-use.html">Agent tutorial</a>
  23. ·
  24. <a href="./docs/authentication-modes.md">Auth modes</a>
  25. ·
  26. <a href="./docs/linux-deploy.md">Linux deploy</a>
  27. ·
  28. <a href="./docs/alternatives.md">Alternatives</a>
  29. ·
  30. <a href="./docs/sync-flows.md">Sync flows</a>
  31. ·
  32. <a href="./docs/skill-runtime-roadmap.md">Skill runtime</a>
  33. ·
  34. <a href="./docs/handoff-spec.md">Handoff spec</a>
  35. ·
  36. <a href="./docs/codex-analytics.md">Codex analytics</a>
  37. ·
  38. <a href="./docs/evidence.md">Evidence</a>
  39. ·
  40. <a href="./docs/promo/xhs-note.md">Promo copy</a>
  41. ·
  42. <a href="./docs/promo/mobile-codex-runner.md">Mobile promo</a>
  43. ·
  44. <a href="./ROADMAP.md">Roadmap</a>
  45. </p>
  46. </div>
  47. ## Linux One-Click Prompt
  48. Repository: `https://github.com/Harzva/chatgpt2localbridge`
  49. Copy this prompt to a Linux shell agent:
  50. ```text
  51. Install ChatGPT2LocalBridge from https://github.com/Harzva/chatgpt2localbridge on this Linux host.
  52. Use one command, keep secrets local, and do not print .env.local, OAuth tokens,
  53. ngrok authtokens, cookies, or unlock codes into chat.
  54. Run:
  55. curl -fsSL https://raw.githubusercontent.com/Harzva/chatgpt2localbridge/main/scripts/linux-one-click-install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 60 on GitHub
  56. After install, report the local health result, the ChatGPT Connector fields, and
  57. the tunnel choice. If ngrok is selected, ask me for NGROK_AUTHTOKEN and optional
  58. NGROK_DOMAIN. If Cloudflare is selected, explain quick tunnel vs named tunnel.
  59. ```
  60. Or run it yourself:
  61. ```bash
  62. curl -fsSL https://raw.githubusercontent.com/Harzva/chatgpt2localbridge/main/scripts/linux-one-click-install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 70 on GitHub
  63. ```
  64. The installer prints every Connector field you need to fill in ChatGPT, plus
  65. ngrok and Cloudflare registration links, tunnel tradeoffs, and an agent-safe
  66. setup prompt.
  67. ![ChatGPT2LocalBridge cover](./docs/assets/cover.png)
  68. <!-- showcase:start -->
  69. <p align="center">
  70. <img src="./docs/assets/thumbnail-responsive.png" alt="ChatGPT2LocalBridge responsive preview" width="900" />
  71. </p>
  72. <!-- showcase:end -->
  73. ChatGPT2LocalBridge is a self-hosted **Codex / ChatGPT Plugin App**: a local desktop/operator app plus an MCP connector that lets ChatGPT access approved local workspaces after authorization. It is designed for people who want ChatGPT or Codex-style agents to inspect, bundle, download, trace, or operate on local project files without uploading the whole workspace elsewhere.
  74. The TypeScript build is the full OAuth MCP connector. A small Rust native
  75. preview also lives in [`rust/chatgpt2localbridge-rs`](./rust/chatgpt2localbridge-rs)
  76. for the local operator console, health checks, activity APIs, and a minimal MCP
  77. smoke surface.
  78. In this repository, **plugin app** means a small agent-facing product surface: a local app, a policy file, a tool catalog, trace records, and one or more ChatGPT/Codex-visible MCP tools. It is not a legacy ChatGPT plugin. It is best described as:
  79. - **Codex Plugin App**
  80. - **ChatGPT Plugin App**
  81. - **MCP Server**
  82. - **ChatGPT Custom Connector**
  83. - **OAuth Local Workspace Bridge**
  84. > Unofficial project. Not affiliated with OpenAI.
  85. ## Build Your Own Plugin App
  86. This project is also an invitation to build more agent-facing plugin apps. A good plugin app should give ChatGPT or Codex a focused tool surface, keep risky operations behind policy, and give the human operator a clear local console.
  87. | Layer | What to build | Example in this repo |
  88. | --- | --- | --- |
  89. | Agent interface | MCP tools with concise names, schemas, and safe defaults | `project.bundle`, `policy.read`, `codex.task_start` |
  90. | Skill runtime | Local skills are discovered through approved roots, manifests, and stable registry tools | `skill.list`, `skill.route`, planned `skill.invoke` |
  91. | Human control | A local app that shows status, policy, traces, and cancel buttons | Native macOS console |
  92. | Safety policy | Approved roots, deny globs, auth mode, shell restrictions | `bridge.policy.json` |
  93. | Distribution | README, GitHub Pages, screenshots, setup prompts, install scripts | `docs/`, `npx github:...`, macOS app bundle |
  94. If you build your own plugin app, keep the default workflow narrow and readable: one clear problem, one safe tool surface, one local control panel, and one copyable ChatGPT test prompt.
  95. The next product direction is a **Local Skill OS**: local skills stay in approved
  96. skill roots, the bridge exposes a stable registry surface, and the app shows
  97. which skills are readable, routable, invokable, or blocked. See the
  98. [Skill Runtime Roadmap](./docs/skill-runtime-roadmap.md).
  99. The main execution path is moving toward **Handoff -> Codex Runner**: ChatGPT
  100. creates a structured handoff, the bridge validates and stores it, then local
  101. Codex CLI performs the project work. See the [Handoff Spec](./docs/handoff-spec.md).
  102. ## Route
  103. ```text
  104. ChatGPT
  105. -> OAuth MCP Connector
  106. -> HTTPS tunnel
  107. -> http://127.0.0.1:3838/mcp
  108. -> ChatGPT2LocalBridge
  109. -> approved local workspace roots
  110. ```
  111. ChatGPT does not directly mount your disk. It calls MCP tools, and every file operation is checked against `bridge.policy.json`.
  112. ## Architecture
  113. <p align="center">
  114. <img src="./docs/assets/architecture-horizontal.png" alt="ChatGPT2LocalBridge horizontal architecture diagram" width="900" />
  115. </p>
  116. The intended product shape is a control plane, not just a raw shell bridge:
  117. - **ChatGPT Web** makes structured MCP calls.
  118. - **Connector auth** should use OAuth or Secure MCP Tunnel for public access.
  119. - **Bridge policy** gates roots, deny globs, shell mode, timeouts, and traces.
  120. - **Tool tiers** guide ChatGPT toward safer project and Codex Runner workflows.
  121. - **Local app** shows policy, tool calls, logs, diffs, downloads, and cancellable tasks.
  122. ## 30-Second Install
  123. Linux one-click installer:
  124. ```bash
  125. curl -fsSL https://raw.githubusercontent.com/Harzva/chatgpt2localbridge/main/scripts/linux-one-click-install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 157 on GitHub
  126. ```
  127. Optional Linux tunnel helpers:
  128. ```bash
  129. curl -fsSL https://raw.githubusercontent.com/Harzva/chatgpt2localbridge/main/scripts/linux-one-click-install.sh | TUNNEL=cloudflare bash
  130. curl -fsSL https://raw.githubusercontent.com/Harzva/chatgpt2localbridge/main/scripts/linux-one-click-install.sh | TUNNEL=ngrok NGROK_AUTHTOKEN=... NGROK_DOMAIN=my-bridge.ngrok-free.app bash
  131. ```
  132. Temporary GitHub npx install, no clone required:
  133. ```bash
  134. npx github:Harzva/chatgpt2localbridge init --root ~/Projects
  135. set -a; source .env.local; set +a
  136. npx github:Harzva/chatgpt2localbridge --http 3838
  137. ```
  138. Local clone flow:
  139. ```bash
  140. git clone https://github.com/harzva/chatgpt2localbridge.git
  141. cd chatgpt2localbridge
  142. npm install
  143. npm run build
  144. node dist/index.js init --root ~/Projects
  145. set -a; source .env.local; set +a
  146. node dist/index.js --http 3838
  147. ```
  148. Health check:
  149. ```bash
  150. curl -sS http://127.0.0.1:3838/health
  151. ```
  152. Local operator console:
  153. ```text
  154. http://127.0.0.1:3838/app
  155. ```
  156. Rust native preview:
  157. ```bash
  158. cargo run --manifest-path rust/chatgpt2localbridge-rs/Cargo.toml -- --http 3842
  159. ```
  160. The Rust preview intentionally exposes a smaller MCP surface today:
  161. `initialize`, `tools/list`, `bridge.health`, `bridge.activity`, and `file.list`.
  162. Native macOS app:
  163. ```bash
  164. npm run macos:install
  165. open /Applications/ChatGPT2LocalBridge.app
  166. ```
  167. The macOS app is a native AppKit/SwiftUI desktop console that embeds the Rust
  168. engine, uses the repository logo as its `.icns` icon, manages the local `3842`
  169. service, and shows the ChatGPT-visible MCP tool catalog, browser bundle prompts,
  170. approved roots, editable policy, logs, connector tool calls, skill reads, write
  171. events, and cloud-download trace records without needing the browser console.
  172. The native **Policy Center** edits the local policy safely:
  173. - workspace roots stay separate from skill roots
  174. - the default skill root is `~/.codex/skills`
  175. - saving creates `bridge.policy.backup.json`
  176. - policy changes are written to local audit trace
  177. - the app warns if you expose broad paths such as `~/.codex`
  178. ## Downloads And Releases
  179. GitHub Releases provide prebuilt artifacts for local testing:
  180. - `ChatGPT2LocalBridge-macos-*.dmg`: drag-and-run macOS native control
  181. console with the Rust companion binary bundled inside the app.
  182. - `ChatGPT2LocalBridge-macos-*.app.zip`: native macOS control console with the
  183. Rust companion binary bundled inside the app.
  184. - `ChatGPT2LocalBridge-windows-x64-rust-preview.zip`: Windows Rust-native local
  185. console preview.
  186. - `chatgpt2localbridge-*.tgz`: npm package for the full TypeScript OAuth MCP
  187. bridge.
  188. The Windows artifact is currently a Rust preview, while the full OAuth connector
  189. surface remains the Node/TypeScript package. Release builds are generated by
  190. `.github/workflows/release.yml` when a `v*` tag is pushed.
  191. See [Windows Roadmap](./docs/windows-roadmap.md) for the current preview scope.
  192. Release route:
  193. ```bash
  194. npm run typecheck
  195. npm test
  196. npm run macos:app
  197. git tag v0.1.x
  198. git push origin v0.1.x
  199. ```
  200. The release workflow attaches macOS `.dmg` / `.app.zip`, a Windows Rust preview
  201. zip, an npm tarball, and SHA256 files.
  202. ## ChatGPT Connector Setup
  203. ### Choose An Auth Mode
  204. ChatGPT's custom connector UI may offer OAuth, No Authentication, and Mixed Authentication. This project supports more than one path, but the safe default depends on where the endpoint is reachable.
  205. | Connector auth | Use when | Notes |
  206. | --- | --- | --- |
  207. | OAuth | Any public HTTPS tunnel, including Mac mini with ngrok/Cloudflare or a Linux server tunnel | Recommended default. ChatGPT completes an OAuth code flow and later calls `/mcp` with a bearer token. |
  208. | No Authentication | Short-lived loopback-only or private-network tests | Works only if the bridge is intentionally running without OAuth. Do not use this on a public tunnel. |
  209. | Mixed | Advanced per-tool policy where public tools are anonymous and privileged tools require OAuth | Useful later if you split tools by risk. The current public-safe guide keeps the whole connector OAuth-protected. |
  210. If both OAuth and No Authentication appear to work, prefer OAuth for anything reachable from ChatGPT over the internet. No Authentication means the URL itself is the control surface.
  211. Expose the local server through HTTPS:
  212. ```bash
  213. ngrok http 3838 --url=your-fixed-domain.ngrok-free.dev
  214. ```
  215. Then create a ChatGPT Custom Connector:
  216. | Field | Value |
  217. | --- | --- |
  218. | Name | `ChatGPT2LocalBridge` |
  219. | URL | `https://your-fixed-domain.ngrok-free.dev/mcp` |
  220. | Auth | OAuth |
  221. When the authorization page opens, enter the unlock code from `.env.local`. Do not paste unlock codes or tokens into public chats, issues, screenshots, or commits.
  222. ### Linux Server Setup
  223. Linux works the same way as Mac mini: run one bridge next to the files you want ChatGPT to see, expose that bridge through HTTPS, then create a separate ChatGPT connector for that machine.
  224. One-click install directly on the Linux host:
  225. ```bash
  226. curl -fsSL https://raw.githubusercontent.com/Harzva/chatgpt2localbridge/main/scripts/linux-one-click-install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 297 on GitHub
  227. ```
  228. Common options:
  229. ```bash
  230. curl -fsSL https://raw.githubusercontent.com/Harzva/chatgpt2localbridge/main/scripts/linux-one-click-install.sh | WORKSPACE_ROOT=/srv/workspace BRIDGE_PORT=3900 bash
  231. ```
  232. The installer prints the exact ChatGPT Connector fields, local health checks,
  233. ngrok registration requirements, Cloudflare registration requirements, and a
  234. longer agent prompt for safe remote setup.
  235. Deploy from an existing local clone to a remote Linux host:
  236. ```bash
  237. REMOTE=linux-box \
  238. REMOTE_WORKSPACE=/srv/workspace \
  239. REMOTE_ALLOWED_ROOTS="/srv/workspace,/home/agent/projects" \
  240. PUBLIC_BASE_URL=https://linux-bridge.example.com \
  241. bash scripts/deploy-linux-bridge.sh
  242. ```
  243. Create a second connector such as `ChatGPT2LocalBridge Linux` with:
  244. | Field | Value |
  245. | --- | --- |
  246. | URL | `https://linux-bridge.example.com/mcp` |
  247. | Auth | OAuth |
  248. Use separate connectors for separate machines so each policy can stay narrow. See [Linux deployment](./docs/linux-deploy.md).
  249. ## Screenshot Walkthrough
  250. | Step | Preview |
  251. | --- | --- |
  252. | Initialize local policy | ![Initialize](./docs/assets/screenshots/01-init.png) |
  253. | Run local MCP server | ![Run](./docs/assets/screenshots/02-run.png) |
  254. | Review Policy Center | ![Policy Center](./docs/assets/screenshots/09-policy-center.png) |
  255. | Check `/health` | ![Health](./docs/assets/screenshots/03-health.png) |
  256. | Create connector | ![Connector](./docs/assets/screenshots/05-connector.png) |
  257. | Authorize | ![Authorize](./docs/assets/screenshots/06-authorize.png) |
  258. | Test file listing | ![Success](./docs/assets/screenshots/07-success.png) |
  259. ## macOS Screenshot CLI
  260. Use the Mac mini helper when you need real screenshots for README, GitHub Pages,
  261. release notes, or social posts. Outputs default to `docs/assets/app_screenshots`.
  262. ```bash
  263. npm run shot:selection # choose any screen area
  264. npm run shot:window # click any window
  265. npm run shot:full # capture the full screen
  266. npm run shot:app # capture the ChatGPT2LocalBridge window bounds
  267. ```
  268. Direct usage:
  269. ```bash
  270. scripts/mac-screenshot.sh --rect 100,120,1280,760 --out docs/assets/app_screenshots/dashboard.png
  271. scripts/mac-screenshot.sh --app "ChatGPT2LocalBridge" --open --copy-path
  272. ```
  273. If macOS blocks capture, grant Screen Recording permission to Terminal, iTerm,
  274. or the agent process in System Settings.
  275. Full guides:
  276. - [Human setup tutorial](./docs/human-tutorial.html)
  277. - [Agent + Computer Use tutorial](./docs/agent-computer-use.html)
  278. - [Visual showcase gallery](./docs/showcase.html)
  279. - [Markdown human tutorial](./docs/tutorial-human.md)
  280. - [Markdown agent tutorial](./docs/tutorial-agent-computer-use.md)
  281. ## Main MCP Tools
  282. ### Tool Tiers
  283. | Tier | Default use | Tools |
  284. | --- | --- | --- |
  285. | High-level agent workflow | Recommended entry point for Web ChatGPT once Codex Runner lands | `codex.task_start`, `codex.status`, `codex.result` |
  286. | Mid-level project workflow | Preferred today for reading context, checking policy, inspecting diffs, and running tests | `project.bundle`, `policy.read`, `git.diff`, `test.run` |
  287. | Low-level debug primitives | Advanced local troubleshooting only; avoid as the Web ChatGPT path | `file.read_path`, `file.write`, `shell.exec` |
  288. The roadmap tracks the move from low-level primitives toward a safer Codex Runner surface. See [ROADMAP.md](./ROADMAP.md).
  289. ### Tool Profiles
  290. ChatGPT2LocalBridge already uses a profile gate to progressively expose tools:
  291. a small public connector surface, a standard daily surface, and a full debug
  292. surface. For clearer public docs, it now accepts both product-facing profile
  293. names and the earlier internal aliases:
  294. | Profile | Alias | Use |
  295. | --- | --- | --- |
  296. | `minimal` | `chatgpt-app` | Small ChatGPT connector surface with compatibility aliases. Raw shell execution is intentionally not exposed. |
  297. | `standard` | `normal` | Recommended default for project, policy, skills, git, tests, traces, and Codex task workflows. |
  298. | `full` | `debug` | Trusted local debugging with low-level file, process, shell, and service tools exposed. |
  299. | `codex-runner-only` | `codex-runner-only` | High-level Codex task control plane without general project tools. |
  300. Set it with:
  301. ```bash
  302. LOCALBRIDGE_TOOL_PROFILE=standard
  303. ```
  304. Use `minimal` for the first public connector test, `standard` for daily work,
  305. and `full` only for focused local debugging where you want every raw primitive
  306. visible.
  307. `shell_exec` is **not supported in the Web ChatGPT connector profile**. Hosted
  308. ChatGPT safety checks can block shell-like actions before they ever reach your
  309. local bridge, especially commands that enumerate files, use pipes, or combine
  310. multiple shell operators. For a smoother connector experience, use
  311. `file_list` / `local_list_dir` for directories, `batch_read` for bounded
  312. multi-file reads, and `handoff_create` -> `codex_task_start` when local Codex
  313. CLI should run commands. The raw shell tools remain debug-only under the `full`
  314. / `debug` profile for trusted local troubleshooting.
  315. This profile model is part of the bridge's own tool router and progressive
  316. disclosure roadmap: expose only the tools needed for the current trust level,
  317. then let the local app and trace records explain what happened.
  318. | Area | Examples |
  319. | --- | --- |
  320. | Project | `project.snapshot`, `project.bundle`, `project.index`, `project.scripts` |
  321. | Handoff | `handoff.create` |
  322. | Policy | `policy.read`, `policy.validate` |
  323. | Skills | `skill.list`, `skill.search`, `skill.read`, `skill.bundle`, `skill.route` |
  324. | Code | `code.read`, `code.read_range`, `code.search` |
  325. | Files | `file.list`, `file.read_path`, `batch_read`, `file.stat`, `file.write`, `file.patch`, `file.delete` |
  326. | Shell/tests | `shell.exec` for local debug only; `test.detect`, `test.run` |
  327. | Git | `git.status`, `git.diff`, `git.checkpoint`, `git.revert` |
  328. | Runtime | `workspace.*`, `task.*`, `process.*`, `port.check` |
  329. | Cloud sync | `cloud.download` |
  330. | Bridge | `bridge.status`, `bridge.health`, `bridge.logs`, `bridge.activity`, `service.restart` |
  331. The full debug-profile MCP tool catalog is generated from MCP `tools/list` into
  332. [`assets/mcp-tools.json`](./assets/mcp-tools.json):
  333. ```bash
  334. npm run tools:catalog
  335. ```
  336. `project.bundle` is the recommended multi-file context tool. It returns a
  337. directory summary, selected text files, and optional git diff in one read-only
  338. call, so ChatGPT can read local first and then create a cloud-side downloadable
  339. copy from the returned content.
  340. `skill.*` tools make local Codex skills readable through the connector without
  341. turning the whole Codex runtime directory into a workspace. Configure:
  342. ```json
  343. {
  344. "skillRoots": [
  345. "/Users/YOUR_USERNAME/.codex/skills"
  346. ]
  347. }
  348. ```
  349. Project-local skills are also discovered from approved project roots at
  350. `.codex/skills`. Reference files are gated: call `skill.read` on a `SKILL.md`
  351. first, then pass the returned `activationId` to `skill.bundle` so it can include
  352. referenced local files such as `references/*.md`.
  353. Do not approve the whole `~/.codex` directory. It can contain sessions,
  354. attachments, local configuration, and other private runtime files.
  355. ## Codex Provider Profiles
  356. Codex Runner can use either the normal Codex CLI login or an OpenAI-compatible
  357. API endpoint. This keeps sub2api optional: run sub2api separately, then point
  358. the bridge at its `/v1` endpoint.
  359. ```bash
  360. LOCALBRIDGE_CODEX_BIN=/Users/YOUR_USERNAME/.local/bin/codex
  361. LOCALBRIDGE_CODEX_PROVIDER=sub2api
  362. LOCALBRIDGE_CODEX_BASE_URL=http://127.0.0.1:4999/v1
  363. LOCALBRIDGE_CODEX_API_KEY_ENV=SUB2API_KEY
  364. SUB2API_KEY=...
  365. ```
  366. The native app has a Codex Provider page for editing these local settings.
  367. Trace output records the provider kind and base URL host only; API keys are not
  368. written into tool results or audit logs.
  369. If ChatGPT shows `spawn codex ENOENT`, the connector and handoff tools are
  370. working, but the background service cannot find the Codex CLI. Set
  371. `LOCALBRIDGE_CODEX_BIN` to the absolute `codex` path, or install Codex in one
  372. of the service-friendly locations such as `~/.local/bin`, `/opt/homebrew/bin`,
  373. or `/usr/local/bin`.
  374. ## File Sync And Activity
  375. - Local files can be read by ChatGPT through approved MCP tools.
  376. - Multiple local files can be bundled with `project.bundle`.
  377. - MCP-read local file content can be re-emitted by ChatGPT as a cloud-side downloadable artifact when the user wants a copy in the conversation.
  378. - For stable Trace Studio grouping, ask ChatGPT to call `trace.session_start` at the beginning of each conversation, and `task.start` before long multi-step work.
  379. - ChatGPT/App-provided cloud file download URLs can be written back to local disk with `cloud.download`.
  380. - Tool calls are persisted to `tool-calls.jsonl`.
  381. - File writes, downloads, tasks, processes, and service restarts are persisted to `audit.jsonl`.
  382. - The local console at `/app` and native macOS app show status, tool calls, and audit events.
  383. See [file sync flows](./docs/sync-flows.md).
  384. ## Field Evidence
  385. The current release includes sanitized evidence from local and ChatGPT connector
  386. tests: build/test output, macOS app installation, tool catalog counts, write
  387. smoke tests, and connector troubleshooting notes. See
  388. [`docs/evidence.md`](./docs/evidence.md).
  389. Latest connector proof: after recreating the ChatGPT custom connector as
  390. `attachlocal2chatgpt-v3`, ChatGPT's action list exposed the high-level handoff
  391. and Codex Runner entry points:
  392. <p align="center">
  393. <img src="./docs/assets/evidence/chatgpt-v3-codex-runner-tools.svg" alt="ChatGPT connector evidence showing handoff_create, codex_task_start, codex_status, and codex_result" width="900" />
  394. </p>
  395. Public-safe safety evidence from field testing:
  396. <p align="center">
  397. <img src="./docs/assets/evidence/batch-read-safety-note.svg" alt="Evidence card explaining hosted safety checks can over-block large batch reads and the bridge now prefers bounded batch_read" width="49%" />
  398. <img src="./docs/assets/evidence/shell-exec-safety-block.svg" alt="Evidence card showing shell_exec can be blocked by hosted ChatGPT safety checks and is not exposed in the Web ChatGPT connector profile" width="49%" />
  399. </p>
  400. Field note: keep `xhigh` / `XHigh` mode off by default. In local testing it
  401. produced more connector/tool-call errors than the normal profile, so use it only
  402. for focused debugging with trace capture enabled.
  403. Field note: `codex.result` and `codex_result` return compact summaries by
  404. default. Full logs, diffs, and handoff metadata are opt-in with `includeLog`,
  405. `includeDiff`, and `includeHandoff` because hosted ChatGPT safety checks can
  406. block large execution records or structured payloads.
  407. ## Star History
  408. <a href="https://www.star-history.com/?repos=Harzva%2Fchatgpt2localbridge&type=date&legend=top-left">
  409. <picture>
  410. <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=Harzva/chatgpt2localbridge&type=date&theme=dark&legend=top-left" />
  411. <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=Harzva/chatgpt2localbridge&type=date&legend=top-left" />
  412. <img alt="Star History Chart for Harzva/chatgpt2localbridge" src="https://api.star-history.com/chart?repos=Harzva/chatgpt2localbridge&type=date&legend=top-left" />
  413. </picture>
  414. </a>
  415. ## Security Defaults
  416. - Do not run unauthenticated on a public URL.
  417. - Keep `allowedProjectRoots` narrow.
  418. - Keep `skillRoots` narrow; prefer `~/.codex/skills`, not `~/.codex`.
  419. - Never commit `.env.local`, `bridge.policy.json`, OAuth stores, tokens, cookies, or unlock codes.
  420. - Prefer OAuth over URL tokens.
  421. - Set `LOCALBRIDGE_DASHBOARD_TOKEN` before using `/app`.
  422. - Review shell deny rules before enabling shell access for broad workspaces.
  423. See [security model](./docs/security.md).
  424. ## Alternatives
  425. OAuth + fixed HTTPS tunnel is the default because it fits ChatGPT Custom Connectors well. Other options exist:
  426. - OpenAI Secure MCP Tunnel, when available to your workspace
  427. - Cloudflare Tunnel
  428. - VPS reverse proxy
  429. - Static bearer token for private clients
  430. - Loopback-only no-auth testing
  431. See [alternatives](./docs/alternatives.md).
  432. ## GitHub Pages
  433. The static product site lives in [`docs/`](./docs/index.html). The repository includes a GitHub Actions workflow that deploys it to GitHub Pages after pushing to `main`.
  434. ## Development
  435. ```bash
  436. npm install
  437. npm run typecheck
  438. npm run tools:catalog
  439. npm test
  440. npm pack --dry-run
  441. cargo test --manifest-path rust/chatgpt2localbridge-rs/Cargo.toml
  442. cargo build --manifest-path rust/chatgpt2localbridge-rs/Cargo.toml
  443. cargo build --release --manifest-path rust/chatgpt2localbridge-rs/Cargo.toml
  444. npm run macos:app
  445. npm run macos:install
  446. ```
  447. Render README and docs assets:
  448. ```bash
  449. npm run docs:assets
  450. npm run docs:preview
  451. ```
  452. ## Public Release Checklist
  453. - [ ] Enable GitHub Pages with the included workflow.
  454. - [ ] Confirm `npm test` passes in GitHub Actions.
  455. - [ ] Confirm the macOS `.dmg` and `.app.zip` download, unzip/mount, and launch.
  456. - [ ] Confirm the Windows Rust preview starts `http://127.0.0.1:3842/app`.
  457. - [ ] Keep `.env.local` and `bridge.policy.json` untracked.
  458. - [ ] Verify the ChatGPT connector uses OAuth and the correct `/mcp` URL.
  459. ## License
  460. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.