# Local Codex Bridge

> **Frozen experimental reference.** This repository is intended to remain
> read-only and is not production-ready or supported. It did not complete
> authenticated Tunnel, macOS real-device, or Android ChatGPT Work validation.
> See [EXPERIMENTAL.md](EXPERIMENTAL.md).

Local Codex Bridge is a narrow MCP control plane for Codex native sessions on a
user-approved Windows or macOS host. It is designed for authenticated access
through OpenAI Secure MCP Tunnel.

The bridge translates eight explicit operations. Codex native threads remain the
only source of truth for session identity, history, runtime state, and results.

## Status

Development is frozen. The source is published only to preserve the protocol,
security-boundary, and testing work as an experimental reference. No runnable
release artifact is provided.

## Security boundary

- No arbitrary shell, process, filesystem, archive, delete, fork, or rollback
  tool is exposed.
- Callers choose a locally approved workspace identifier, never an arbitrary
  machine path.
- Callers cannot override the configured permission profile, sandbox, network
  policy, model-provider configuration, or App Server configuration.
- The bridge has no session database, transcript mirror, task registry, or
  durable pending-request store.
- Secrets belong in Windows DPAPI-protected storage or macOS Keychain and must
  not enter repository files, command arguments, logs, screenshots, or fixtures.

See [the threat model](docs/threat-model.md) and
[protocol decisions](docs/protocol.md) before operating the bridge. The
[architecture notes](docs/architecture.md) describe state ownership, the fixed
process boundary, and restart behavior. [Platform setup](docs/platform-setup.md)
documents credentials, launchers, managed tunnel supervision, and recovery. The
[real-device acceptance runbook](docs/acceptance-runbook.md) defines the
Windows, macOS, Tunnel, and Android evidence procedure without retaining native
identities or private host metadata beyond its explicit public-version
allowlist. Its [sanitized report format](docs/acceptance-report.md) preserves a
historical, uncompleted runtime-release gate; it is not evidence for this frozen
source publication. The [release runbook](docs/release.md) defines the
fail-closed publication gate.

## Development

Requires Node.js 24 or newer, npm, Codex CLI, and gitleaks.

```sh
npm ci
npm run check
npm run secret:scan
```

The commands above are for source inspection and test reproduction, not an
installation or deployment recommendation.

## Non-goals

V1 does not wake dormant ChatGPT conversations, implement Workspace Agents API
triggers, control turns owned by another App Server runtime, or provide a
general remote shell.

## License

MIT.