Pickleshell

PickleShell

Give ChatGPT a local machine to work with

[](#release-history) [](#development) [](LICENSE) [](#requirements)

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](docs/deployment.md) and [docs/chatgpt.md](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.4; use it only with trusted users and a dedicated service > account. Read > [SECURITY.md](SECURITY.md) before deployment.

Quick Start

1. Follow the [Deployment guide](docs/deployment.md) to install the Gateway and

tunnel-client on a Linux host.

1. Follow the [ChatGPT setup](docs/chatgpt.md) to create the Secure MCP Tunnel,

configure the PickleShell plugin, and run the connection test.

1. Send a test message: Reply exactly: pong. Do not use tools or modify files.
2. Poll session-status until state: "completed", then read the result with

session-output.

Why PickleShell?

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.

Architecture

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

Core services

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

| Service | Status | Notes | | --- | --- | --- | | Agent | Implemented on OpenCode and Codex | send-chat, session-status, session-output, cancel-request with session continuity via session_id. OpenCode remains the supported default; Codex is a first-class alternative backend behind the same MCP interface. Codex defaults to the exec transport; the experimental MCP transport is selected internally with codex.transport and requires the Codex 0.143.0 codex/codex-reply MCP tool surface. | | Browser | Implemented | Playwright browser automation, exposed through the PickleShell MCP server. | | Terminal | Implemented, E2E verified across reference profiles | Separate unprivileged node-pty runtime with persistent PTY sessions and six MCP tools. The clean external release-installation gate remains open. |

Use Case Example

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

Async Workflow

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.

File Transfer

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

| Constraint | Limit | | --- | --- | | Files per request | 20 | | Size per file | 2 MiB | | Total payload | 10 MiB | | Overwrite | Disabled by default; explicit opt-in per file |

Destination resolution: files[].dest_dir > destination_dir > .inbox//.

> [!WARNING] > Important limitation: the current ChatGPT custom MCP integration does not > expose ChatGPT attachments or Library files to custom tools as redeemable > opaque references or short-lived URLs. PickleShell therefore receives file > contents inline as Base64 in the send-chat tool arguments. This increases > the payload size by approximately 33% and can consume substantial > model-context and token budget, especially for images and larger files. There > is currently no simple alternative that avoids this limitation. For anything > beyond a very small attachment, place the file in the workspace outside MCP; > use MCP file transfer only when the additional overhead is acceptable.

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

Capabilities

| Capability | Behaviour | | --- | --- | | Async execution | Non-blocking tasks with request_id tracking and structured polling | | Session continuity | Continue an OpenCode or Codex conversation across multiple ChatGPT messages using session_id | | Cancellation | Abort in-flight tasks with cancel-request | | Model selection | Choose only from an operator-controlled model allowlist | | File transfer | Transfer up to 20 files per request with size, path, symlink, and overwrite protection | | Destination control | Place files in an explicit workspace-relative directory | | Session locking | Reject concurrent work on the same explicit session | | Parallel work | Run independent sessions concurrently without state mixing | | Structured metadata | Timestamps (created_at, started_at, completed_at), queue_ms, execution_ms, and full execution traces in every completed result |

Security Model

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](SECURITY.md) for the trust model, file-delivery invariants, availability guarantees, and vulnerability reporting.

Requirements

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

Development

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

Documentation

• [ChatGPT setup](docs/chatgpt.md) — connect the plugin and run the connection test
• [Deployment guide](docs/deployment.md) — install, upgrade, verify, and troubleshoot the Gateway, tunnel, Browser, and Terminal services
• [API reference](docs/api.md) — MCP tool schemas, async protocol, and Gateway endpoints
• [Model allowlist](docs/models.md) - maintained model IDs and runtime selection guidance
• [Security policy](SECURITY.md) — trust model, threat boundaries, and vulnerability reporting
• [Roadmap](docs/roadmap.md) — v1 production checklist and deferred features

Contact

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](mailto:pickleshell.plugin@gmail.com)

Project Status

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.

Release History

v0.1.4

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

v0.1.2

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

v0.1.1

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

[v0.1.0](https://github.com/pickleshell/pickleshel

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: pickleshell
• Source: pickleshell/pickleshell
• License: MIT

Install and usage instructions live in the source repository linked above.