# Homeport

### Your projects. Your Mac. A private MCP connection.

[简体中文](README.zh-CN.md) · [Install](docs/INSTALL.md) · [Architecture](docs/ARCHITECTURE.md) · [Security](SECURITY.md) · [Attribution](THIRD_PARTY.md)

Homeport keeps a local development runtime available to ChatGPT through **official OpenAI Secure MCP Tunnels**. Give each folder its own connection name, then read and edit files, run commands, and manage local Git from a conversation.

It combines a small Python project gateway and macOS background supervisor with the separately installed [WebCodex](https://github.com/yyjeqhc/webcodex) Server + Runner. No always-open browser, public inbound port, or custom cloud relay is required.

> **Alpha · macOS / Apple silicon.** This is an operator tool with real write and shell access, **not an OS sandbox**. Use only with trusted users and projects. Read [Security](SECURITY.md) before connecting it to a model.

## Why Homeport?

- **One folder, one connection.** Names such as `App` and `Notes` map to fixed project roots. Separate local credentials and session/job checks reduce accidental cross-project calls.
- **Visible connection and operation state.** Read scoped health observations and look up an operation ID without rerunning it. Missing or old observations stay explicitly unknown or stale.
- **A headless lifecycle.** One login LaunchAgent supervises one Server, one shared Runner, and a tunnel client per connected project. Crashed components restart with backoff.
- **Recoverable structured edits.** Bounded preimage backups and a durable operation ledger help with guarded overwrites and ambiguous retries.
- **Resource-conscious defaults.** One managed Job slot, two-thread build hints, bounded HTTP concurrency, rotating logs, and passive CPU/RSS sampling.
- **Official connection path.** Uses OpenAI's documented Tunnel client. No browser cookies, unofficial ChatGPT endpoints, subscription-to-API conversion, or quota bypass logic.
- **Inspectable by design.** Python standard library at runtime; no bundled native executables, telemetry SDK, auto-updater, or hidden scheduler.

## What you can do

| Workflow | Available tools and behavior |
| --- | --- |
| Inspect a project | File listings, project overview, bounded text reads and search |
| Edit files | Create files, apply patches or exact edits, and use SHA-guarded overwrites with selected preimage backups |
| Run development work | Native commands, scripts, persistent session shells, and structured Cargo / Go validation |
| Follow long tasks | Start a Job, observe its state, read bounded log segments or wait for updates, and explicitly stop it |
| Review local Git | Status, diffs, history, selected-path commits/restores and workspace checkpoints |
| Diagnose a connection | `homeport_connection_status` reports gateway, backend, project and Tunnel observations, their age, and historical acceptance separately |
| Inspect an uncertain operation | `homeport_operation_status(operation_id)` returns only the current connection's admission metadata |

Execution comes from the WebCodex contract; Homeport is not a drop-in proxy for arbitrary MCP backends. Search results are bounded: a truncated single search requires a narrower query, not an invented cursor. [Detailed capability matrix and limits →](docs/DESKTOP_COMMANDER_ADOPTION.md)

## How it works

```mermaid
flowchart LR
  chat[ChatGPT private connections] --> control[OpenAI Secure MCP Tunnel]
  subgraph mac[Your Mac · signed-in user]
    tunnel[Official tunnel clients] --> gateway[Homeport project gateway]
    gateway --> ledger[(Operation ledger + preimages)]
    gateway --> server[WebCodex Server]
    server --> runner[Shared WebCodex Runner]
    runner --> app[App folder]
    runner --> notes[Notes folder]
    launch[Login LaunchAgent] -. supervises .-> tunnel
    launch -. supervises .-> server
    launch -. supervises .-> runner
  end
  tunnel -- outbound HTTPS polling --> control
  control -. MCP requests on established connection .-> tunnel
```

The gateway binds to loopback. Each private tunnel targets one `/<profile>/mcp` route and injects that route's bearer credential. WebCodex provides the actual file, process, session and Git tools; Homeport supplies routing, lifecycle policy and the two local diagnostic tools. Requests and responses pass through OpenAI-managed Tunnel infrastructure; this is not a guarantee that data stays on the Mac or is end-to-end encrypted against the provider. [Read the implementation walkthrough →](docs/ARCHITECTURE.md)

## Quick start

Prerequisites: macOS on Apple silicon, Python 3.9+ (a maintained Python 3.11+ is recommended), Git, the official `tunnel-client`, and an eligible OpenAI organization / ChatGPT workspace. Account access is separate from installing this repository.

Download `webcodex-v0.4.0-darwin-arm64.tar.gz` from the [WebCodex v0.4.0 release](https://github.com/yyjeqhc/webcodex/releases/tag/v0.4.0). Homeport checks the pinned SHA-256 before extracting its three executables. Install the official Tunnel client using [OpenAI's instructions](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels).

From a downloaded or cloned Homeport checkout:

```sh
python3 -m venv .venv
source .venv/bin/activate
python -m pip install .

# Replace these example folders with existing absolute paths on your Mac.
homeport init \
  --archive "$HOME/Downloads/webcodex-v0.4.0-darwin-arm64.tar.gz" \
  --project "App=$HOME/projects/app" \
  --project "Notes=$HOME/projects/notes"
```

In OpenAI Platform, create one private Secure MCP Tunnel per profile. Then configure the returned IDs locally:

```sh
homeport configure-tunnel App tunnel_REPLACE_WITH_APP_ID
# Enter a dedicated Tunnels Read + Use key at the hidden terminal prompt.
homeport configure-tunnel Notes tunnel_REPLACE_WITH_NOTES_ID
homeport install
homeport start
homeport doctor
```

`init` does not start the background service. `install` creates its login LaunchAgent; `start` starts it now. Keep the Python environment at the same path while the service is installed.

Finally, create private connections in ChatGPT developer mode, select the matching Tunnel IDs, and name them `App` and `Notes`. These names are examples, not reserved names. Start with **Always Ask** approvals and a disposable test folder. [Complete installation and acceptance steps →](docs/INSTALL.md)

## Everyday use

Select the intended connection in ChatGPT and ask:

> Inspect this project's instructions and Git status. Explain the current changes without editing anything.

For connection trouble, ask:

> Call homeport_connection_status. Explain which observations are current, stale or unknown, and keep historical acceptance separate from current readiness.

For an ambiguous write response, query its existing `operation_id` with `homeport_operation_status`. `pending` means execution or outcome is unknown; `complete` means a response was recorded, not that the command succeeded or a Job finished. Do not generate a new ID and rerun the task to recover output. A disconnected Tunnel requires local CLI diagnosis.

For a write test, explicitly name a new disposable file, ask for a readback, then a SHA-256-guarded overwrite. For real changes, state exactly what may be edited and whether committing or pushing is authorized.

```sh
homeport connection-status App # Scoped local observations; no repair
homeport operation-status App REPLACE_WITH_OPERATION_ID  # Admission metadata only
homeport doctor                 # Live readiness, plus separately labeled historical evidence
homeport metrics --minutes 30  # CPU/RSS samples; not an electrical power measurement
homeport backup-databases       # Bounded, SQLite-consistent local backups
homeport stop                   # Refuses to stop if it cannot establish a safe job inventory
homeport start
```

The connection also exposes read-only `homeport_connection_status` and `homeport_operation_status`. They report fresh/stale/unknown observations and scoped admission metadata without executing or replaying a task. A recorded response is not proof of command success or Job completion. [Capability review and adoption decisions](docs/DESKTOP_COMMANDER_ADOPTION.md).

[Operations, recovery and removal →](docs/OPERATIONS.md)

## Boundaries worth knowing

| Topic | What this alpha actually provides |
| --- | --- |
| File and Git access | Real logged-in-user access through WebCodex; shell commands can reach beyond the chosen folder |
| Retry safety | Completed results replay by operation ID; interrupted outcomes require inspection, not blind reruns |
| Backups | Selected structured file-edit preimages; **not** arbitrary shell edits, all Git actions, ACLs or xattrs |
| Background operation | Starts after user login, not before FileVault unlock or while fully asleep |
| Sleep | Optional AC idle-sleep prevention; no closed-lid or true-sleep availability guarantee |
| Performance | Bounded orchestration and cooperative build hints, not hard process CPU/RAM quotas |
| Distribution | Open-source software each user deploys privately; **not** a public ChatGPT marketplace plugin |
| Account policy | Documented integration path, not OpenAI endorsement, a compliance certification or an account-risk guarantee |

Official tunnels currently serve private/developer-mode use; public marketplace distribution requires a suitable public HTTPS endpoint. See the [official scope and limitations](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels). Homeport has no software license fee; upstream service access, eligibility and pricing remain the providers' responsibility.

## Development and verification

```sh
PYTHONPATH=src python -m unittest discover -s tests -v
python scripts/release_check.py

# Optional: real native backend, disposable folders, no OpenAI connection or API key.
PYTHONPATH=src python scripts/native_smoke.py \
  --archive /absolute/path/webcodex-v0.4.0-darwin-arm64.tar.gz
```

CI runs deterministic tests and package checks without credentials. The opt-in native test exercises initialization, MCP discovery, file read/write, backups, commands, local Git and project-boundary checks. It does not certify a user's ChatGPT connection, login/reboot behavior, or long-duration uptime. See [verification and roadmap](docs/VERIFICATION.md).

## Related projects and credit

[WebCodex](https://github.com/yyjeqhc/webcodex) is the execution engine, and [OpenAI Tunnel client](https://github.com/openai/tunnel-client) provides connectivity. Homeport is independently maintained and is not affiliated with either project.

We also reviewed FastMCP, Desktop Commander, the MCP reference servers, CodexPro and codex-chatgpt-web to clarify the scope and documentation. They are not runtime dependencies, and their application code or branding is not bundled. [Comparison and provenance →](THIRD_PARTY.md)

Licensed under [Apache-2.0](LICENSE). Contributions are welcome; start with [CONTRIBUTING.md](CONTRIBUTING.md).