Documentation
Run ChatGPT on your Mac or a remote Sprite.
Start with Local for trusted direct execution on an Apple Silicon Mac, or Sprite for a remote Linux workspace with explicit GitHub autonomy controls. Shared architecture, tools, and maintainer material live under Reference.
Local
Quick Start
Run ChatGPT directly on your trusted Linux, macOS, or Windows machine with your normal files, credentials, and developer tools.
Open guideSetup
Provision the OpenAI Secure MCP Tunnel, create a least-privilege runtime key, run zodex local setup, and add the tunnel to ChatGPT.
Open guideDaily use
Start, inspect, observe, and stop Zodex Local while one or more ChatGPT conversations work on your trusted Linux, macOS, or Windows host.
Open guideWatch
Open the Local Liveboard in your browser or use the terminal viewer on Linux, macOS, and Windows.
Open guideObservability API
Build read-only Local clients with the versioned localhost HTTP/SSE API, canonical timeline, bounded output views, audit checkpoints, and recovery.
Open guideConfiguration
Configure Zodex Local context injection, skill discovery, history retention, and tunnel metadata.
Open guideCommand reference
A compact reference for every public zodex local command, argument, option, and common example.
Open guideTroubleshooting
Diagnose Zodex Local setup, tunnel, ChatGPT app, credential storage, startup, host permissions, Agent, history, and shutdown problems.
Open guideSprite
Sprite
Run ChatGPT on a wake-on-demand remote Linux Sprite through Zodex's canonical Cloudflare Worker front door.
Open guideConnect ChatGPT
Use the canonical Cloudflare Worker front door, understand the secret capability URL, and add a Sprite deployment to ChatGPT.
Open guidePermissions and autonomy
Understand the Sprite boundary between remote workspace execution, GitHub reads, PR publishing, temporary repo grants, and scoped YOLO.
Open guideWrite modes
Choose PR publishing, a temporary repo push grant, operator-granted push, or scoped YOLO for a Sprite coding session.
Open guideGitHub Apps
Create the narrow reader and writer GitHub Apps used by Sprite mode for clone/fetch, PR publishing, push grants, and YOLO.
Open guidePRs and push grants
Publish PRs from a Sprite, request temporary direct-push access, use normal Git after approval, and revoke grants independently of YOLO.
Open guideOperator controls
Open, inspect, and revoke Sprite direct-push access from the operator machine, including repo grants and scoped YOLO.
Open guideConfiguration
Understand the Sprite runtime, GitHub policy, service port, MCP capability key, and publisher settings in /etc/zodex/config.toml.
Open guideOperations
Check end-to-end health, inspect Sprite Service logs, restart/reconcile services, upgrade the runtime, and maintain the canonical Worker.
Open guideCommand reference
A compact reference for Sprite setup, connection, status, health, logs, restart, sync, upgrade, Worker, GitHub policy, and guest commands.
Open guideTroubleshooting
Diagnose the Sprite wake origin, managed services, canonical Worker, MCP capability, GitHub reader, publisher, push grants, and YOLO policy.
Open guideReference
Architecture
Understand Zodex's two first-class execution modes, their different trust/connection models, and the three-tool MCP contract they share.
Open guideTools
Learn the three tools ChatGPT gets from Zodex and the command, process-session, workdir, and patch patterns that work in both Sprite and Local modes.
Open guideDevelopment
Maintainer reference for building, testing, and releasing Zodex itself; not required to operate Sprite or Local.
Open guideDocs site
Maintainer reference for running, validating, and deploying the Zodex documentation site.
Open guideChangelog
Release notes for zodex.
Open guide