# Coding Local

**Bring ChatGPT into selected local projects—with file tools, command execution, and reviewable diffs.**

A self-hosted distribution of [DevSpace](https://github.com/Waishnav/devspace). Ask ChatGPT to inspect a project, make a change, run tests, and show the result. Execution takes place in a Linux container on your machine; requested code and tool results return to the ChatGPT host.

![Coding Local: request a change, execute in a local workspace, inspect the diff and test output.](docs/assets/coding-local-workflow.svg)

[Try the example](#a-concrete-example) · [Architecture](#how-it-connects) · [Quick start](#quick-start) · [Validation](#validation-and-current-limits) · [Provenance](#provenance-and-contributions)

## A concrete example

> Open `/workspaces/demo`, read the project instructions, add a `multiply` function and tests for positive, negative, and zero inputs. Run the tests and build, then show the diff.

The repository includes a [small demo project](examples/coding-local-demo). A recorded ChatGPT acceptance session on **September 30, 2026** completed this flow: four tests passed, the build succeeded, and the host rendered a two-file diff. The files were checked again on the Mac. This is a recorded acceptance result, not a promise that every host configuration works identically.

[Read the walkthrough and evidence](docs/coding-local-demo.md).

## How it connects

![ChatGPT connects through a user-owned tunnel and authenticated MCP endpoint to a Docker workspace.](docs/assets/coding-local-boundaries.svg)

| Boundary | Behavior |
| --- | --- |
| Host | ChatGPT chooses tool calls and presents results. `tools.mode: codex` names a tool interface; it does not start Codex or transfer a subscription. |
| Authentication | OAuth with PKCE protects the custom `/chatgpt-for-local` MCP endpoint. |
| Files and commands | Selected project directories are mounted into the container. File tools enforce allowed roots; shell commands have the container user's authority. |
| Network | The coding container uses an internal network. A separate HTTP(S) proxy permits public destinations on ports 80/443 and blocks private-network targets; it is not a dependency-domain allowlist. |
| Persistence | Project files and service state survive service restarts. Running commands do not. |

See [the Compose configuration](compose.yaml) and [security boundaries](docs/coding-local-security.md) (Chinese). Container isolation has limits; allowed-root checks alone do not sandbox arbitrary shell commands.

## Quick start

You need Docker with Compose, Git, and Node 24+ for the preparation scripts. Remote ChatGPT access also requires your own domain, Cloudflare Tunnel, and an account with usable ChatGPT developer mode.

The recorded deployment target is Apple Silicon. The container pins Node **24.21.0** and pnpm **11.25.0** and limits the coding service to **4 CPUs / 6 GiB**. Allow additional memory for Docker and the access/egress services.

```bash
git clone https://github.com/Syx403/ChatGPT-4-Local.git
cd ChatGPT-4-Local
# Use your own domain and a dedicated project directory, not your entire home.
node scripts/local/init.mjs https://mcp.example.com "$HOME/CodingLocal/workspaces"
node scripts/local/seed-demo.mjs "$HOME/CodingLocal/workspaces"
bash scripts/local/start.sh
```

Initialization preserves existing private configuration. It generates an owner password in `.local/config/auth.json` with restricted permissions; it does not print that password, create DNS records, or expose a public endpoint. Keep that file private.

After startup, `http://127.0.0.1:7676/healthz` should return `ok: true`; an unauthenticated MCP request should return `401`.

Follow the [operations guide](docs/coding-local-operations.md) (Chinese) to configure your own tunnel and DNS. Connect ChatGPT to `https://mcp.example.com/chatgpt-for-local` using OAuth, then try the example above. The machine must remain awake with Docker and the tunnel running. Use one modifying session per project.

## Validation and current limits

[![CI](https://github.com/Syx403/ChatGPT-4-Local/actions/workflows/ci.yml/badge.svg)](https://github.com/Syx403/ChatGPT-4-Local/actions/workflows/ci.yml)

The [acceptance record](docs/coding-local-changes.md) (Chinese) documents real HTTP MCP/OAuth, reads and patches, tests/builds, diff rendering, restart persistence, and rejected access attempts. It also records what was not established: the ChatGPT UI was checked with that account's existing CSP setting, and concurrent shell writes are not automatically made mutually exclusive.

```bash
# Source checks: use the complete dependency set, including optional native binaries.
pnpm install --frozen-lockfile
pnpm typecheck
pnpm test
pnpm build
pnpm test:package-install
```

The live [smoke script](scripts/local/smoke.mjs) operates on a configured deployment and writes temporary verification files. Review the operations guide before using it. No npm package is published from this repository; the documented deployment uses source and the lockfile.

## Provenance and contributions

DevSpace **v1.1.0-beta.4**, upstream revision `8e4669ca1fdd4796c5aec3b2e9541242c023e594`, provides the underlying MCP tools, workspace mechanics, OAuth implementation, and review UI.

The Coding Local changes maintained by **Syx403 / Ewan Su** include:

- A configurable MCP endpoint and route-validation/OAuth regression tests.
- Docker deployment, fixed-target local ingress, and controlled egress configuration.
- Initialization, demo, and real HTTP smoke scripts; persistent state and operations documentation.
- Authentication error handling and compatible dependency fixes described in the [implementation record](docs/coding-local-changes.md).

See [the implementation commit](https://github.com/Syx403/ChatGPT-4-Local/commit/60aa1977) for the separation from upstream. This is independently maintained and is not an official OpenAI product.

Original DevSpace sources retain their [MIT license](licenses/devspace-MIT.txt). Original Coding Local additions retain the repository's [Apache-2.0 license](LICENSE). [NOTICE](NOTICE) preserves upstream attribution; [upstream documentation](docs/upstream-README.md) describes the baseline.