GPT Harness

A self-hosted MCP gateway that lets ChatGPT Web run shell commands on a server you control.

Why this exists

ChatGPT Web reasons about code well. With the GitHub connector it reads and edits a repository. What it cannot do is run anything, because its own environment has no network access. It cannot install a dependency or execute a test suite.

Codex can do both, but agentic usage is billed and capped separately from chat. Chat runs out much later, or not at all.

The gateway closes that gap. ChatGPT decides what to do, and your server does it. Your message quota becomes the limit instead of an agent allowance.

@gpt-harness work this ticket
  git clone, write code, npm ci, npm test, repeat until green

@gpt-harness review this PR <link>
  gh pr checkout, run its tests, report back

Related MCP server: Personal AIVA MCP Bootstrap

What it exposes

Four tools: bash, bash_output, bash_kill, and write_file. Tool reference documents the arguments, results, and limits.

There is no workspace tool and no workspace concept. Projects are directories under HARNESS_ROOT, and ChatGPT uses ls and mkdir like anyone else.

Three of the four tools exist because of one constraint. A single tool call cannot stay open for the several minutes npm ci takes, so bash returns a handle once a command outlives its 20 second wait, bash_output reads from a cursor, and bash_kill stops a command that will not finish.

Commands are not interactive. stdin reads end of file immediately, so ChatGPT has to pass flags such as npm ci and gh --yes. Each command runs in its own process group, so stopping one stops everything it started.

Requirements

• A Linux server with systemd, a domain, and TLS

• Node.js 24

• An Auth0 tenant

• A ChatGPT account with developer mode available

Run it locally

git clone https://github.com/salman-frs/gpt-harness.git
cd gpt-harness
npm ci
cp .env.example .env

Point HARNESS_ROOT at a directory you can throw away, fill in the Auth0 values from Connect ChatGPT to the gateway, then start it:

npm run dev
curl -fsS localhost:8787/healthz

/healthz needs no token. Every request to /mcp needs a valid token for the configured owner, including initialize.

Running the gateway locally gives you no confinement. ProtectSystem=strict and the rest come from the systemd unit, which only applies on the server.

Prove it works

npm run build && npm run prove

scripts/prove.mjs starts dist/main.js as its own process from environment variables alone. It serves a real HTTPS JWKS endpoint that the gateway fetches over the network, mints a real RS256 token, and drives the result with the ordinary MCP client. It writes a project, installs a dependency from the registry, runs the tests, and checks that killing a command also kills the processes that command started.

Nothing in the script imports src/.

Documentation

• Connect ChatGPT to the gateway covers Auth0, the metadata endpoints, and the connector.

• Deploy the gateway on a server covers the systemd unit, the reverse proxy, Git credentials, and updates.

• Tool reference covers arguments, results, limits, and error codes.

• About the security model covers the boundaries and what you accept by running this.

License

MIT