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.

An independently installed Memory MCP is available with a repository-owned self-hosted Mem0 backend as an optional workstation sidecar integration. It is not a fourth core service and never participates in Gateway startup or readiness.

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

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.

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.

1. Follow the Deployment guide to install the Gateway and tunnel-client on a Linux host.
2. Follow the ChatGPT setup to create the Secure MCP Tunnel, configure the PickleShell plugin, and run the connection test.
3. Send a test message: Reply exactly: pong. Do not use tools or modify files.
4. Poll session-status until state: "completed", then read the result with session-output.

ChatGPT can reason about a project, while PickleShell's Agent service (running OpenCode by default, with Codex as a supported alternative) can operate inside a local development environment. PickleShell provides the secure, explicit boundary between them:

• no public Gateway endpoint;
• no inbound port forwarding;
• operator-controlled workspaces and model allowlists;
• authenticated requests and auditable local execution;
• file transfer with path, symlink, and overwrite protection;
• workspace isolation that prevents cross-chat state mixing.

PickleShell Workstation gives ChatGPT a local environment equipped with an agent, a browser, and a terminal.

flowchart TD
    A["ChatGPT"] --> B["OpenAI Secure MCP Reverse Tunnel"]
    B --> C["tunnel-client"]
    C --> D["PickleShell MCP server"]
    D --> E["PickleShell Gateway"]

    subgraph SVC["PickleShell Workstation"]
        direction TB
        subgraph SVCB["Browser"]
            PW["Playwright"]:::impl
        end
        subgraph SVCA["Agent"]
            OC["OpenCode"]:::impl
            CX["Codex"]:::impl
        end
        subgraph SVCT["Terminal"]
            TTY["Interactive PTY"]:::impl
        end
    end

    E --> SVC
    SVC --> WS["Configured workspace"]

    classDef cloud fill:#e9f3ff,stroke:#1677c8,color:#102a43
    classDef bridge fill:#fff4d6,stroke:#d48806,color:#3d2b00
    classDef local fill:#e8f7ec,stroke:#2f855a,color:#173d2a
    classDef impl fill:#e8f7ec,stroke:#2f855a,color:#173d2a
    class A,B cloud
    class C,D bridge
    class E,SVC,WS local

All three core service boxes are implemented. Terminal E2E has been verified across ordinary and privileged reference profiles through the six-operation contract. The clean external release-installation gate remains open.

The tunnel is initiated from the local machine over outbound HTTPS. The Gateway remains reachable only inside the trusted local environment.

The three mandatory core services all run locally on your machine:

One ChatGPT can act as the main orchestrator and use PickleShell to coordinate different machines and capabilities: a development agent, a dedicated interactive terminal, parallel agents on one server, and the Browser tool directly. Tasks are sent to workers, while browser actions, progress, and results are returned to ChatGPT for the next coordination step.

flowchart TB
    C["ChatGPT Orchestrator"]
    P["PickleShell"]

    C <--> P

    subgraph S1["Server 1"]
        A1["Development Agent"]
    end

    subgraph S2["Server 2"]
        T["Interactive Terminal"]
    end

    subgraph S3["Server 3 — Parallel Execution"]
        A2["Agent A"]
        A3["Agent B"]
        A4["Agent C"]
    end

    subgraph S4["Server 4 — Browser"]
        A5["Testing Agent"]
        B["Browser"]
    end

    P <--> A1
    P <--> T
    P <--> A2
    P <--> A3
    P <--> A4
    P <--> A5
    P <--> B

send-chat returns immediately with a request_id and state: "busy". Poll session-status to track progress, then read the result with session-output. Cancel in-flight work with cancel-request at any time.

send-chat ──▸ { request_id, state: "busy", next_action: "session-status" }
                    │
                    ▼
              session-status ──▸ { state: "busy", progress: [...] }
                    │                retry_after_ms: 2000
                    ▼
              session-status ──▸ { state: "completed", next_action: "session-output" }
                    │
                    ▼
              session-output ──▸ { reply, trace, session_id, timestamps }

Each response includes next_action (which tool to call next) and retry_after_ms (suggested polling interval). Pass the returned session_id in subsequent send-chat calls to continue the same runtime conversation. Omit it to start a fresh session that runs independently and in parallel.

Idempotency: when a client provides an explicit idempotency key, duplicate send-chat requests are detected and the original result is returned instead of re-executing the command.

Completed results are retained for 24 hours and can be read repeatedly through session-output.

Session locking: concurrent send-chat requests to the same explicit session_id receive a 409 session_busy response. Independent sessions run in parallel without interference.

For Codex MCP transport, new sessions call the Codex MCP codex tool and continuations call codex-reply with the returned thread id. Cancelled or timed out MCP calls recycle the affected worker; there is no automatic fallback to exec when mcp is explicitly configured.

flowchart LR
    C["ChatGPT file attachment"] --> M["Base64 decode & validate"]
    M --> F["Path + symlink + size checks"]
    F --> W["Workspace-safe write"]

Destination resolution: files[].dest_dir > destination_dir > .inbox/<request-id>/.

The Gateway writes through directory file descriptors with O_NOFOLLOW, rejects symbolic links as destinations, and publishes results atomically.

PickleShell is a controlled bridge to a local coding agent, not a general-purpose public shell. Deployments should use a dedicated unprivileged service account, strict workspace permissions, a narrow model allowlist, and environment-backed credentials.

See SECURITY.md for the trust model, file-delivery invariants, availability guarantees, and vulnerability reporting.

• Linux;
• Node.js 20 or newer;
• Playwright Chromium installed for the deployed MCP package version;
• an Agent backend installed and configured (OpenCode by default, or Codex);
• OpenAI Secure MCP Reverse Tunnel access;
• a dedicated local service account is strongly recommended.

Install dependencies, run the complete test suite, build both components, and audit dependencies:

npm --prefix gateway ci
npm --prefix mcp-server ci
npm test
npm run build
npm run audit

• ChatGPT setup — connect the plugin and run the connection test
• Deployment guide — install, upgrade, verify, and troubleshoot the Gateway, tunnel, Browser, and Terminal services
• API reference — MCP tool schemas, async protocol, and Gateway endpoints
• Optional Memory MCP — Mem0 transport, policy, audit, errors, and discovery
• Model allowlist - maintained model IDs and runtime selection guidance
• Security policy — trust model, threat boundaries, and vulnerability reporting
• Roadmap — v1 production checklist and deferred features

Open a GitHub issue to report a bug, suggest an improvement, or ask for help. Include the relevant setup details and steps to reproduce the problem.

• Create an issue
• Browse existing issues
• Email: pickleshell.plugin@gmail.com

PickleShell 0.1.4 is the latest release. It adds the public settings tool, scoped persisted runtime settings, and optional supervised Codex MCP transport.

This is a complete, fully functional, and stable release of the integrated PickleShell system. Gateway, MCP, Agent, Browser, Terminal, tunnel, and immutable deployment workflows are implemented and work together as one system. The project is now in controlled pre-release testing: this validation stage is the final step before a broader stable release, while the current version is already suitable for real-world testing and use with trusted users. Interfaces may still change before the stable 1.0 release.

• Added optional, supervised Codex MCP transport through codex mcp-server, with new-thread and continuation support and no automatic fallback; this is limited to the Codex CLI 0.143.0 MCP tool surface.
• Added the public settings tool with describe, get, set, and reset.
• Added persisted global and per-chat scopes for runtime, model, agent_timeout_sec, and codex_transport. Resolution precedence is explicit request > persisted chat override > persisted global setting > static config > default; operator security policy remains immutable.

• Added the native Codex runtime as a first-class alternative to OpenCode, verified through the reference test tunnel.
• Added a persistent interactive Terminal PTY with six MCP operations, plus isolation, lifecycle, and delegated cgroup safeguards for ordinary and ChatGPT profiles.
• Added automated Terminal reconnect E2E coverage and a consistent bounded terminal-close reason contract.
• Verified Terminal E2E across ordinary and privileged reference profiles.
• Added immutable release migration, rollback, isolated systemd unit, and production smoke verification gates.
• Added the project Philosophy statement.

• Added Playwright MCP browser automation runtime and setup documentation.
• Hardened agent isolation, authentication, and systemd service runtime.
• Updated ChatGPT Assistant positioning, plugin setup, and async workflow docs.
• Added project contact guidance and release metadata.

• First production-ready release.
• Added asynchronous request_id execution with status polling and full output.
• Added session continuity, cancellation, explicit idempotency, file transfer, structured metadata, and operator-controlled workspace/model scoping.

• Me
• Big Pickle
• Codex
• Grok
• ChatGPT

PickleShell is available under the MIT License.