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.

Direct ChatGPT Memory provides private/shared memory CRUD, search, history and discovery, plus credential-authorized administration through the Memory broker. Normal and admin surfaces use the same implementation; policy changes remain operator-owned and ChatGPT never receives backend credentials.

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:

PickleShell now separates what an agent may do from where that authority stops. Execution requests can be constrained by an operator-approved profile (isolated, agent, privileged, or full-control) and boundary (host, container, or vm). A boundary is enforced by a concrete provider, not treated as a label: unavailable VM/container providers fail closed before a process or concurrency slot is created.

The optional Memory stack now supports multiple principals with isolated private scopes and explicit shared project scopes. This lets different agent runtimes exchange durable knowledge without sharing their private memory or backend credentials.

See Deployment for the execution-profile and boundary-provider contract, and Memory principals for the shared-memory trust model.

Execution profiles and Memory grants are independent. Selecting an execution profile, including full-control, does not grant Memory administration.

Only the host boundary provider is currently implemented. Container/VM requests fail closed; profile selection does not create a sandbox or elevate the running service. See the Execution Profile Contract.

The credential-bound broker policy determines Memory authority. Exposing admin tool schemas cannot promote an ordinary principal. See Memory principals and Direct ChatGPT Memory.

PickleShell can add a durable memory layer for ChatGPT and agent runtimes. This is an optional sidecar, not part of the Agent/Browser/Terminal core. The current backend is Mem0, run behind PickleShell's own Memory broker and MCP interface.

The idea is simple: each runtime keeps its own private memory, while operator-approved shared scopes let different runtimes exchange durable knowledge. A production handoff has been validated between Codex and OpenCode using the same shared Mem0 store while their private scopes and credentials remained separate.

flowchart TB
    CX["Codex"] --> CM["PickleShell Memory MCP"]
    OC["OpenCode"] --> OM
    CH["ChatGPT"] --> HM

    CM --> B["Multi-principal Memory broker"]
    OM["PickleShell Memory MCP"] --> B
    HM["PickleShell Memory MCP"] --> B

    B --> PRIV["Private scopes\nPer principal"]
    B --> SHARED["Shared project scopes\nSelective read / write"]
    B --> M0["Self-hosted Mem0"]

    M0 --> QD["Qdrant vector store"]
    M0 --> SQL["Local metadata / history store"]

The trust boundary is intentionally at the broker:

• Codex, OpenCode, ChatGPT, and future runtimes can use different principals.
• A principal cannot select another principal, raw user_id, or backend scope through MCP tool arguments.
• Private scopes remain isolated; shared scopes are explicit operator policy.
• The backend bearer is owned by the broker and is not delivered to ChatGPT, Codex, OpenCode, or the Memory MCP client.
• The Memory stack can be deployed, restarted, and rolled back independently of the main PickleShell Gateway.

The normal MCP surface provides capability discovery, target discovery, semantic search, get, add, update, history, and delete. The ChatGPT-facing implementation also supports a separate, credential-authorized admin surface for status, health, principal and sanitized policy inspection, inventory, and scoped administrative record operations. Admin authority cannot be selected by a tool argument.

PickleShell keeps this diagram separate from the core Agent/Browser/Terminal architecture because Memory is an optional integration. See Memory MCP, self-hosted Mem0 backend, Memory principals, and Direct ChatGPT Memory.

After an operator installs the Memory stack and connects its MCP surface, run these tools in order. The examples use shared/project/pickleshell; substitute an approved alias returned by target discovery if your deployment uses another.

An empty search result can mean the approved target has no matching memories. For an optional write test, first confirm that private has write: true and that your ChatGPT workspace permits write tools:

1. Call memory_add with {"target":"private","text":"Disposable Memory quick-start test <unique marker>","infer":false}; replace the marker with a unique value.
2. Read the newly returned ID with memory_get, using target: "private".
3. Delete only that test ID with memory_delete, using the same target.
4. Call memory_get again; expect memory_not_found.

Use a returned test ID rather than a pre-existing record. These are setup/test instructions, not a claim that the ChatGPT UI integration has passed validation.

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.2.1 is the latest release. It includes the first-class execution authority profiles with enforced boundary providers, a dedicated networked OpenCode agent surface, and multi-principal shared Memory for controlled knowledge exchange between agent runtimes.

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.

• Expanded the integrated-system architecture and release guidance.
• Added a focused quick start and explicit permission tables for optional shared Memory.
• Clarified private and operator-approved shared Memory scopes without changing the v0.2.0 runtime behavior.

• Added the first-class Execution Profile Contract: execution resolves as runtime + execution_profile + boundary + boundary_provider. Operator policy controls which profiles and boundaries are available; sessions cannot silently resume with different authority, and there is no automatic upward privilege fallback.
• Added enforced boundary providers. host is implemented; container and vm fail closed until a real provider is configured. A requested VM/container boundary can never fall back to direct host execution. full-control + host remains denied by default.
• Added a dedicated networked OpenCode agent + host execution surface with an unprivileged service identity, NoNewPrivileges=true, controlled Internet networking, and isolated writable runtime state. The ordinary Terminal remains a separate, stricter AF_UNIX-only surface.
• Added managed multi-principal PickleShell Memory on the optional Mem0 sidecar: separate private scopes, operator-approved shared scopes, one credential-projecting broker, broker-only backend credentials, deterministic policy ownership/mode checks, immutable release activation, and rollback/recovery support.
• Validated a real Codex → shared Mem0 → OpenCode handoff using separate unprivileged OS identities and principals. OpenCode discovered Codex-written project knowledge semantically without receiving the originating transcript or memory ID; private scopes remained isolated and the handoff survived a broker restart.
• These execution and memory primitives are designed to be reusable by higher-level orchestration systems such as Core; PickleShell remains the execution/integration layer.

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