Connect ChatGPT Web to your Linux VPS

Problem → Solution

Stop copying commands between ChatGPT and your terminal.

ChatGPT can reason about a server, but without a trusted execution path it cannot see the real state, run the authorized action, inspect the result and continue from the same conversation. Portico MCP closes that loop.

The friction

Manual server work breaks the conversation into pieces.

ChatGPT suggests a command, but cannot see what happened next.
You switch windows, copy commands, paste logs back and rebuild context.
Troubleshooting becomes a relay between chat, terminal and dashboards.
Giving an AI broad SSH-style access creates a much larger trust problem.

The bridge

Let ChatGPT work on the VPS inside rules you own.

From the conversation, ChatGPT can inspect files, diagnose services, analyze logs, work with Docker and perform other operations you explicitly enable.

Standard, Project or Whole Host sets the physical perimeter. Filesystem, shell, systemd, Docker, network and administrative capabilities remain separate policy decisions.

ChatGPT Web→OAuth→MCP Gateway→Policy Broker→Your VPS

GitHub's role

Distribution and source, not a runtime relay.

GitHub hosts the open-source project, documentation, releases and update source. After installation, GitHub is not in the operational path between ChatGPT Web and your VPS.

No VPS password handed to ChatGPT.
No SSH private key handed to ChatGPT.
No Docker socket exposed to the model.
Privileged operations are re-authorized by the Broker and auditable.

Connect. Ask. Inspect. Operate. Audit.

Authority

You choose the delegated perimeter.

Standard, Project and Whole Host define the physical filesystem ceiling. Filesystem, shell, systemd, Docker, network and administrative capabilities remain separate policy decisions.

Privilege

Root stays behind the Broker.

The Gateway is non-root and receives neither /host nor the Docker socket. The Broker is local-only, privileged and policy-authoritative.

Completion

Proof before “installed”.

Healthy containers are a checkpoint. Installation completes only after a real authenticated ChatGPT MCP call reaches policy, execution and Broker audit.

Architecture

Small public surface, explicit trust boundaries.

ChatGPT WebOAuth + HTTPS MCP

→

Gatewaynon-root

→

Brokerlocal privileged boundary

→

VPSLinux · systemd · Docker · files

Security

The LLM is not the authorization engine.

Deny-by-default policy, secure path resolution, isolated shell/jobs, bounded requests, exact-subject checks, operation journals, locks/fencing and a Broker-owned audit hash chain keep authority in server code.

Identity

Integrated OAuth, self-hosted.

The supported public path runs ZITADEL + PostgreSQL beside the service, with a dedicated operator, MCP audience, private RFC 7662 introspection, DCR and PKCE. ZITADEL telemetry is disabled.

Requirements

What you need before installation.

VPS

Linux VPS. Ubuntu 24.04 LTS is the release-candidate validated target.
Docker Engine 24+ and Docker Compose v2.
At least 2 GB RAM for the bundled ZITADEL OAuth path.
Git, OpenSSL, Python 3 and curl.
A public DNS hostname pointing to the VPS, TCP 80/443 available and valid HTTPS.

ChatGPT

A ChatGPT Web account/workspace where Developer Mode and custom MCP app creation are actually available.
OpenAI controls plan/workspace availability and rollout, so a subscription label alone is not a compatibility guarantee.
Current official OpenAI documentation lists full MCP write/modify support for Business, Enterprise and Edu; Pro can connect custom MCPs with read/fetch permissions in developer mode.

Quick Start

Three commands to enter the guided flow.

git clone https://github.com/josemirmoura/mcp-vps-agent-gateway.git
cd mcp-vps-agent-gateway
bash scripts/install.sh

The terminal runs a prerequisite preflight, asks for Standard / Project / Whole Host, displays the effective authority, starts the runtime, verifies it, configures public OAuth and then guides the real ChatGPT completion call.

Standard is the recommended default. It uses /opt as the physical ceiling with no project root authorized initially. Whole Host sets the filesystem ceiling to /, but does not enable Full or unrestricted network.

Transparent components

The guided flow does not hide the machinery.

Advanced operators can run the same components individually:

bash scripts/init.sh --scope /opt --dynamic-baseline
docker compose up -d --build
bash scripts/verify.sh
bash scripts/setup-integrated-auth.sh
bash scripts/connect-chatgpt.sh

No VPS or SSH credentials are given to ChatGPT. The dedicated OAuth operator credential belongs to the integrated identity service and is entered locally through the supported auth flow.

connect-chatgpt.sh records an audit baseline, lets you complete the ChatGPT app/OAuth setup at your own pace, and verifies the real authenticated system.info call when you return and press Enter. Only then can it print INSTALLATION COMPLETE.

Operations

Diagnose.

bash scripts/diagnose.sh status
bash scripts/diagnose.sh health
bash scripts/diagnose.sh bundle

Lifecycle

Update or remove.

bash scripts/update.sh
bash scripts/remove.sh safe

Stable SemVer tags are the default update channel. Backup, migration validation and rollback stay in the existing updater.

Maturity

Scoped first.

The Scoped path has automated and real ChatGPT E2E evidence. Full/R5 remains an advanced path and is not presented as production-ready.

Privacy

Self-hosted, no marketing telemetry.

State, policy, audit and identity data stay on the VPS unless the operator exports them. Diagnostic bundles redact configured secrets. See the repository privacy document for details.

Release integrity

SemVer, checksums, SBOM and provenance.

Release tags must match VERSION. GHCR images are built for amd64/arm64 with SBOM/provenance; source packages carry SHA-256 checksums. Dedicated project-managed signing is not yet claimed.