PiLink

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, 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.

• 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, PiLink for VS Code, and Connect ChatGPT Work.

2. CLI MCP bridge

Use this when you do not need the VS Code launcher. Start the project-scoped single-agent bridge directly:

pilink start --mode single

For remote MCP clients, configure a reachable HTTPS origin. For a local server behind an existing reverse proxy, use:

pilink serve --mode single

Collaboration is an explicit operator workflow, not part of the default bridge:

pilink start --mode collaboration

See Installation, Runtime mode selection, and the Security model.

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.

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 for the full protocol, wake, retry, and security contract.

Related MCP server: ChatGPT2LocalBridge

Install from source

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:

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:

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

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

• Installation

• Getting started

• Connect ChatGPT Work

• PiLink for VS Code

• Troubleshooting

Reference / operator

• Security model

• Architecture

• Runtime mode selection

• ChatGPT LLM Gateway

• Usage, models, and costs

Development

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 and the @earendil-works/pi-coding-agent harness. Repository history and NOTICE retain attribution.