PickleShell

Give ChatGPT a local machine to work with

Website: pickleshell.github.io

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.

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 will reach the Terminal service once it is implemented.

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]
PickleShell is pre-release software (0.1.0). Use it only with trusted
users and a dedicated service account. Read
SECURITY.md before deployment.

Quick Start

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.

Why PickleShell?

ChatGPT can reason about a project, while PickleShell's Agent service (running
OpenCode today) 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

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

    subgraph SVC["PickleShell local services"]
        direction LR
        subgraph SVCA["Agent"]
            OC["OpenCode"]:::impl
            CX["Codex"]:::planned
        end
        subgraph SVCB["Browser"]
            PW["Playwright"]:::impl
        end
        subgraph SVCT["Terminal"]
            TTY["Interactive PTY"]:::planned
        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
    classDef planned fill:#fffdf5,stroke:#7b8794,color:#102a43,stroke-dasharray: 6 5
    class A,B cloud
    class C,D bridge
    class E,SVC,WS local

Solid boxes are implemented; dashed boxes (Codex and the Terminal) are planned.

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:

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

File Transfer

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.

Capabilities

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

Requirements

• Linux;
• Node.js 20 or newer;
• the Agent backend (currently OpenCode) installed and configured;
• OpenAI Secure MCP 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 — connect the plugin and run the connection test
• Deployment guide — install the Gateway, tunnel, and systemd units
• API reference — MCP tool schemas, async protocol, and Gateway endpoints
• Security policy — trust model, threat boundaries, and vulnerability reporting
• Roadmap — 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: [email protected]

Project Status

PickleShell 0.1.1 is the latest release. It adds the Playwright browser
runtime and browser automation documentation, hardens agent isolation and
service runtime security, and updates the ChatGPT Assistant setup and product
documentation.

This is pre-1.0 software. Interfaces may change before a stable 1.0 release.

Release History

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

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

Authors

• Me
• Big Pickle
• Codex
• Grok
• ChatGPT

License

PickleShell is available under the MIT License.