PickleShell

Give ChatGPT a local machine to work with

Website: pickleshell.github.io · Quick Notes

Want to give your ChatGPT a gift? Give it PickleShell.

PickleShell connects ChatGPT to a local host running three mandatory core services: an Agent, a Browser, and a Terminal. ChatGPT can inspect repositories, edit files, run tests, automate a browser, transfer small files, and coordinate long-running tasks. The connection uses an outbound-only OpenAI Secure MCP Tunnel, while execution remains inside your selected workspace.

The Agent exposes four MCP tools—send-chat, session-status, session-output, and cancel-request—and receives structured results with full traces. The Browser exposes Playwright automation tools. Continue local coding sessions, delegate to an operator-approved model, and transfer files into a controlled workspace.

Philosophy

"Any task can be solved in a single prompt." — Author

PickleShell provides autonomous agents with a secure, deterministic, and low-latency environment to achieve complete task completion without constant manual intervention.

What PickleShell Is For

PickleShell solves a practical problem: ChatGPT can analyze tasks, but it normally cannot work directly with a local repository.

Through PickleShell, ChatGPT sends instructions and small files to a local Agent, follows the execution, reads the result, and can continue in the same session when it passes the session ID. The same connection reaches the Browser service and the Terminal service.

The services run on your machine, inside a selected workspace, through a protected outbound-only tunnel. PickleShell removes the human relay between ChatGPT and your machine, while you remain the owner and observer.

PickleShell is for developers and experienced users. Installation is designed to be guided by Codex: ask it to clone the repository, read AGENTS.md, and walk you through the setup step by step using docs/deployment.md and docs/chatgpt.md. AGENTS.md is the contributor guide for the development workflow, architecture, security invariants, and change boundaries.

Use Case

Create three PickleShell tunnels to three different machines, then give the plugins unique names: PickleShell Mars, PickleShell Moon, and PickleShell Starbase. The first tunnel connects to a machine on Mars, the second to a machine on the Moon, and the third to a machine at Starbase. Tell your ChatGPT Assistant which named plugin belongs to which machine, and it can route each task to the right destination.

With this setup, your ChatGPT Assistant can manage colonies on Mars and the Moon, as well as coordinate launches from Starbase to them—the big rockets Elon launches. The same pattern is useful today for everything from saving a technical specification to asking the Agent on a selected machine to carry out a complex task directly from ChatGPT.

[!WARNING] The main branch may contain unreleased changes. The latest stable release is v0.1.2; use it only with trusted users and a dedicated service account. Read SECURITY.md before deployment.

Quick Start