PiLink

# PiLink <p align="center"> <img src="docs/assets/logo.png" width="640" alt="PiLink"> </p> PiLink is a self-hosted, OAuth-protected MCP bridge that gives authorized AI clients controlled access to a project you choose. The normal path is **project-scoped by default**; broader execution and Full machine access require separate operator decisions. ## Choose your route PiLink has three distinct workflows. Pick the one that matches where you want the model and tools to run. ### 1. VS Code MCP bridge → ChatGPT Work Use this when you want a small graphical launcher for a selected project and a remote ChatGPT client. **First install** - Use VS Code 1.106 or newer and choose the project folder PiLink may access. - Download the matching bundle from [PiLink GitHub Releases](https://github.com/roccoangelella/PiLink/releases), keep the installer, VSIX, and `SHA256SUMS` together, then run `./install.sh` on Linux/macOS or `.\install.ps1` in Windows PowerShell. The release installer provisions the supported private sidecar Node.js runtime when necessary. - In Remote SSH, run that release installer in the **remote** VS Code integrated terminal because the extension, sidecar, project, and hosting process belong on the remote workspace host. - For remote ChatGPT Work use, configure a public HTTPS endpoint. A temporary Quick Tunnel is available for evaluation; stable use needs an HTTPS origin you control. Cloudflare fixed-domain provisioning requires **Account -> Cloudflare Tunnel -> Edit**, **Zone -> DNS -> Edit**, and **Zone -> Zone -> Read**; see [Installation](docs/INSTALLATION.md#cloudflare-fixed-domain-token-permissions). - The intended private PiLink plugin must already be provisioned for your ChatGPT workspace or created/imported through controls your account is permitted to use. PiLink cannot grant those ChatGPT workspace controls. If the PiLink CLI is **already installed** on the workspace host, `pilink install-vscode-plugin` is an alternate extension install/update path. After installation, reload VS Code and open **PiLink** from the Activity Bar. The graphical setup always uses **Single agent + Project-folder access**. When the endpoint is healthy, select **Connect ChatGPT**, complete local owner verification and OAuth, then begin with a read-only task that confirms the project boundary. See [Getting started](docs/GETTING_STARTED.md), [PiLink for VS Code](docs/VSCODE_EXTENSION.md), and [Connect ChatGPT Work](docs/CONNECT_CHATGPT.md). ### 2. CLI MCP bridge Use this when you do not need the VS Code launcher. Start the project-scoped single-agent bridge directly: ```bash pilink start --mode single ``` For remote MCP clients, configure a reachable HTTPS origin. For a local server behind an existing reverse proxy, use: ```bash pilink serve --mode single ``` Collaboration is an explicit operator workflow, not part of the default bridge: ```bash pilink start --mode collaboration ``` See [Installation](docs/INSTALLATION.md), [Runtime mode selection](docs/operations/mode-selection.md), and the [Security model](docs/SECURITY_MODEL.md). ### 3. ChatGPT-backed loopback LLM Gateway Use this when a local coding agent should receive model responses from a connected ChatGPT conversation through a loopback OpenAI-compatible API. This is separate from the VS Code **Local only** endpoint: the API is local, but the gateway still requires a compatible ChatGPT MCP connection and active worker. ```bash pilink gateway start # equivalent launch surface: pilink start --mode cli # after setup, launch Pi Agent in the current project: pilink-cli ``` The gateway requires a compatible ChatGPT MCP connection, OAuth/Dynamic Client Registration support, and an active worker conversation. The local API normally binds to `127.0.0.1:3210` and requires its bearer key. Important limits: - `stream: true` is **buffered SSE**: PiLink receives the complete ChatGPT result before emitting OpenAI-style stream events. It is not token streaming. - Tool calls are returned to the local caller harness; **PiLink does not execute caller-advertised tools**. The harness executes them with its own permissions. - Common generation controls such as `temperature`, `top_p`, `max_completion_tokens`, and `store` are accepted only for compatibility and are ignored there; strict mode rejects unsupported controls. - Browser auto-wake is optional and requires one-time extension approval. On Linux, PiLink may enable wake after detecting the approved Chromium extension. On Windows, passive profile detection is not trusted: verify the extension in the browser/profile reached by a normal HTTPS link and explicitly confirm it; headless setup requires manual verification before `pilink gateway browser-extension --enable`. See [ChatGPT LLM Gateway](docs/operations/llm-gateway.md) for the full protocol, wake, retry, and security contract. ## Install from source ```bash git clone https://github.com/roccoangelella/PiLink.git cd PiLink node --version # v24.18.0 npm --version # 11.16.0 npm ci npm run build ``` `npm run build` compiles PiLink and may create or repair a PiLink-owned launcher in an existing user-writable directory already on `PATH`. It never uses `sudo`, edits shell startup files, or replaces an unrelated command. If no safe launcher location exists, run: ```bash npm run cli -- start ``` Private OAuth state, tunnel credentials, provider credentials, and PiLink data must stay outside the project exposed to MCP clients. ## Security boundaries Project-folder access is the baseline. Filesystem tools are confined to the canonical selected project; repository execution is a separate opt-in. Public MCP OAuth, local owner administration, and optional provider authentication are separate trust boundaries. ### Full machine access Full access removes the project boundary and enables process execution as the PiLink OS user. It is remote code execution by design and is **not** part of the normal VS Code workflow. Use it only after reviewing the OAuth client and the [Security model](docs/SECURITY_MODEL.md): ```bash pilink clients list PI_FULL_ACCESS_CLIENT_IDS=pi_your_client_id \ pilink start --allow-unsafe-full-access ``` Compatibility shortcuts such as `pilink agents`, `pilink-agents`, `pilink single-agents`, and `pilink-single-agent` enter Full-access workflows; they are not synonyms for ordinary project-scoped mode selection. ## Hosting choices | Choice | Intended use | URL behavior | | --- | --- | --- | | Cloudflare fixed domain | Regular remote use | Stable | | Existing HTTPS domain | Operator-managed reverse proxy | Stable | | Cloudflare Quick Tunnel | Evaluation | Changes when recreated | | Local only | Same-machine MCP clients | Not reachable by ChatGPT web | **Local only** describes the VS Code/MCP endpoint reachability. It is not the ChatGPT-backed LLM Gateway, whose OpenAI-compatible API is loopback-only while its model responses still depend on ChatGPT connectivity. A public URL is not authorization. Remote access still requires the configured OAuth flow and the relevant client/plugin capability. ## Documentation **Start here** - [Documentation by task](docs/README.md) - [Installation](docs/INSTALLATION.md) - [Getting started](docs/GETTING_STARTED.md) - [Connect ChatGPT Work](docs/CONNECT_CHATGPT.md) - [PiLink for VS Code](docs/VSCODE_EXTENSION.md) - [Troubleshooting](docs/TROUBLESHOOTING.md) **Reference / operator** - [Security model](docs/SECURITY_MODEL.md) - [Architecture](docs/ARCHITECTURE.md) - [Runtime mode selection](docs/operations/mode-selection.md) - [ChatGPT LLM Gateway](docs/operations/llm-gateway.md) - [Usage, models, and costs](docs/USAGE_AND_COSTS.md) ## Development ```bash npm ci npm run dev # compile/watch only npm run dev:server # run the raw development server npm run test:all npm run release:check ``` PiLink uses the [MIT License](LICENSE) and the [`@earendil-works/pi-coding-agent`](https://www.npmjs.com/package/@earendil-works/pi-coding-agent) harness. Repository history and [NOTICE](NOTICE.md) retain attribution.