<div align="center">

# Desktop Coworker for ChatGPT

Self-hosted MCP coding server and unified local Control Center for ChatGPT web.

[![CI](https://github.com/colin-dmme/desktop-coworker-for-chatgpt/actions/workflows/ci.yml/badge.svg)](https://github.com/colin-dmme/desktop-coworker-for-chatgpt/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)

</div>

> Independent community project; not affiliated with or endorsed by OpenAI.

Desktop Coworker for ChatGPT can read and change files, run commands, use Git, restore edit
checkpoints, and proxy optional upstream MCP tools. This is high-impact access:
read [SECURITY.md](SECURITY.md) before connecting it to a remote service.

## Windows quick start

For end users, download the latest `DesktopCoworker-Setup-*.exe` from
[GitHub Releases](https://github.com/colin-dmme/desktop-coworker-for-chatgpt/releases),
run it, and launch **Desktop Coworker for ChatGPT** from the Start menu. The
per-user installer includes Electron, the built application, and a verified
OpenAI Secure MCP Tunnel client; Node.js and npm are not required.

For source development, use Windows 10/11 and Git:

```powershell
git clone https://github.com/colin-dmme/desktop-coworker-for-chatgpt.git
cd desktop-coworker-for-chatgpt
.\run.bat
```

`run.bat` is the source checkout entrypoint. It installs or updates Node.js, installs the
locked npm dependencies, builds the TypeScript sources, downloads the official
OpenAI Secure MCP Tunnel client when missing, and opens the Electron Control Center.
The first launch requires network access; later launches reuse installed files.

## Connect an account

1. In ChatGPT, enable **Developer mode** under **Settings → Security and login**.
   Availability may depend on your account and workspace policy.
2. In [OpenAI Platform tunnel settings](https://platform.openai.com/settings/organization/tunnels),
   create a Secure MCP Tunnel, associate it with the ChatGPT workspace that will
   use it, and create a Runtime API key. Running and selecting the tunnel requires
   **Tunnels Read + Use** permission.
3. Open the installed app, or run `run.bat` from a source checkout.
4. Choose **Add account** and enter a workspace, tunnel ID, Runtime API key, and
   ports.
5. Start the account and wait until MCP, Admin, Tunnel, and Ready are green.
6. Open [ChatGPT Plugins](https://chatgpt.com/#settings/Connectors), select the plus
   button, choose **Tunnel** under Connection, and select the tunnel or paste its
   `tunnel_id`.
7. Review the discovered tools, create the connection, and add it to a new
   conversation from the tools menu. Refresh the connection after server metadata
   changes.

See the official OpenAI documentation for
[Secure MCP Tunnel](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels)
and [connecting an MCP server from ChatGPT](https://developers.openai.com/plugins/deploy/connect-chatgpt).

Profiles created by the former PySide dashboard are migrated automatically.
Profiles, telemetry, logs, runtime configuration, and upstream MCP settings live
outside the repository at `%LOCALAPPDATA%\DesktopCoworkerForChatGPT`.

The Control Center never returns a Runtime API key to browser JavaScript. The
generated tunnel YAML also contains no key; it is passed only to the tunnel child
process. The desktop build encrypts Runtime API keys with operating-system-backed
Electron safe storage; all application data must still be treated as sensitive.

## Conversation access control

Conversation access protection is off by default, preserving the original one-click
experience: ChatGPT can use tools as soon as the connector is ready. Owners of shared
accounts can opt in per account on the **Chat access** page. When enabled, a new
ChatGPT conversation cannot call computer tools until the local owner approves its
pending request or generates a short-lived one-time code.
Grants are scoped to one account and workspace, have a `read`, `edit`, or `execute`
tier, expire automatically, and can be revoked immediately.

The **Chat access history** keeps a local audit trail of pending requests,
approvals, denials, revocations, protection changes, and one-time-code outcomes.
It can be filtered by event, permission, date, fingerprint, label, or tool, and
entries can be deleted individually or in filtered batches.

ChatGPT conversation, subject, and organization identifiers are stored only as
keyed fingerprints. One-time codes are stored only as keyed hashes, are single-use,
expire after two minutes by default, and trigger a temporary lockout after repeated
failed attempts. Tool activity recursively redacts password, code, token,
authorization, credential, and cookie fields before persistence or streaming.

## One interface, three local services

```text
Electron window -> localhost Control Center :2999
  ├─ manages accounts, ports, logs, activity, settings and upstream MCP
  └─ starts one isolated pair per account
       ├─ MCP server :3000 (default)
       │    ├─ filesystem / patches / checkpoints
       │    ├─ shell / processes / Git
       │    ├─ project context / memory
       │    └─ optional upstream MCP servers
       ├─ Admin API :3001 (internal data source; /ui redirects to :2999)
       └─ OpenAI Secure MCP Tunnel health :8080
```

Electron supplies the native window, tray, lifecycle, encrypted secret storage,
installer, and updater. The existing web Control Center remains localhost-only
and is reused inside that desktop shell instead of being rewritten.

## Repository layout

```text
public/control/               Unified Control Center frontend
public/control/locales/       Extensible English/Vietnamese UI catalogs
public/ui/                    Legacy per-server fallback UI
src/control/                  Account supervisor, telemetry and Control API
src/desktop/                  Electron window, tray, secrets and updater
src/admin/                    Per-server localhost Admin API
src/lib/                      MCP services and infrastructure
src/tools/                    MCP tool registration
scripts/windows/              Bootstrap and lifecycle scripts
scripts/release/              Release validation scripts
scripts/development/          Maintainer utilities
config/examples/              Safe example configurations
docs/                         User and architecture documentation
third_party/                  Bundled dependency licenses and notices
tests/control/                Control Center tests
tests/server/                 MCP server tests
run.bat                       One-click Windows entrypoint
```

`public/ui` remains only as a standalone-server compatibility fallback. Normal
launches redirect its `/ui` route to the unified Control Center.

## Development

Node.js 22.5 or newer is required because local telemetry uses the built-in
SQLite module.

```powershell
npm ci
npm run build
npm test
npm run test:all
npm run desktop:dev
```

Useful entrypoints:

- `npm start` — Electron Control Center and account supervisor.
- `npm run start:web` — browser-only compatibility and diagnostics entrypoint.
- `npm run start:server` — one standalone MCP server without the supervisor.
- `npm run desktop:dev` — build and launch the Electron app from source.
- `npm run desktop:dist` — build a local Windows NSIS installer.
- `npm run dev` — browser Control Center in TypeScript watch mode.
- `npm run dev:server` — standalone MCP server in watch mode.
- `.\run.bat -SkipLaunch` — complete Windows bootstrap smoke test.

See [Desktop build and release guide](docs/development/desktop-release.md) for
source ownership, versioning, signing, packaging, and GitHub release automation.

The Control Center defaults to English and remembers a language selected in the
UI. To add another language, copy a catalog under `public/control/locales`, keep
the same message keys as `en.js`, and register it in `public/control/i18n.js`.
The i18n test fails when catalogs or referenced keys fall out of sync.

## Configuration

The Control Center writes per-account environment files under local app data.
For standalone server development, copy `.env.example` to `.env`.

| Variable | Default | Purpose |
|---|---:|---|
| `CONTROL_CENTER_PORT` | `2999` | Unified local UI and Control API |
| `HOST` | `127.0.0.1` | MCP bind address; keep loopback for tunnel use |
| `PORT` | `3000` | MCP HTTP port |
| `ADMIN_PORT` | `3001` | Per-server localhost Admin API |
| `WORKSPACE_PATH` | current directory | Default project directory |
| `CHATGPT_TOOL_PROFILE` | `slim` | `slim` or `full` exposed tool set |
| `SHELL_TIMEOUT` | `120` | Foreground command timeout in seconds |
| `CHECKPOINT_ENABLED` | `true` | Enable edit checkpoints and rewind |
| `MCP_UPSTREAM_CONFIG` | local app data | Shared upstream MCP configuration |
| `CHATGPT_ACCESS_CONTROL` | `off` | `off`, `observe`, or `enforce` conversation gate; Control Center sets it per account |
| `CHATGPT_ACCESS_DB` | local app data | Local SQLite access requests, grants, and hashed codes |

The workspace is a default working directory, not a sandbox. Absolute paths and
commands run with the current Windows user's permissions.

## Documentation

- [Control Center guide](docs/en/control-center.md)
- [Vietnamese Control Center guide / Hướng dẫn tiếng Việt](docs/vi/control-center.md)
- [Contributing](CONTRIBUTING.md)
- [Support](SUPPORT.md)
- [Code of Conduct](CODE_OF_CONDUCT.md)
- [Changelog](CHANGELOG.md)
- [Security](SECURITY.md)
- [Agent onboarding](AGENTS.md)

## License

[MIT](LICENSE)