Documentation
Connect ChatGPT to a real coding machine and choose the right GitHub write policy.
These guides explain zodex from the ChatGPT and operator perspectives: Sprite setup, MCP exposure, GPT-friendly tools, PR-only publishing, request-push grants, operator-side grants, scoped YOLO mode, GitHub App boundaries, proxy verification, service logs, upgrades, and local docs maintenance.
Start
Quickstart
Set up zodex for ChatGPT: install the operator CLI, create a Sprite, install the guest runtime, expose the MCP URL, add it to ChatGPT, and choose a GitHub write mode.
Open guideWrite modes
Choose how much GitHub autonomy ChatGPT gets in a zodex session: PR-only, one-off push approval, operator-granted push, timed YOLO, repo-scoped YOLO, or no-TTL YOLO.
Open guideArchitecture
Runtime architecture
Understand how ChatGPT, the operator CLI, Sprite services, server routes, HTTP API, agent helper, GitHub Apps, and publisher daemon fit together.
Open guideConfiguration
Configure bind addresses, TLS, API keys, workspace defaults, session limits, GitHub App credentials, publisher settings, and grant behavior.
Open guideGitHub Access
Access and autonomy model
Learn how zodex separates read access, local workspace writes, PR publishing, one-off push grants, and scoped YOLO mode for ChatGPT sessions.
Open guideGitHub Apps setup
Create the reader and writer GitHub Apps with the narrow permissions zodex expects for ChatGPT clone/fetch, PR publishing, push grants, and YOLO mode.
Open guidePush modes and PRs
Publish pull requests, request temporary push access, use normal Git commands after approval, list active grants, and understand when to use YOLO mode instead.
Open guideOperator write controls
Activate, inspect, and revoke direct-push access from the operator machine, including one-off push grants and scoped YOLO mode for trusted ChatGPT sessions.
Open guideOperations
Proxy and MCP front door
Expose the Sprite-hosted zodexd server through a proxy-backed MCP URL that normalizes paths, warms cold Sprites, retries edge failures, and preserves streaming responses.
Open guideSprite operations
Check runtime health, inspect logs, resync Sprite Services, upgrade binaries, verify the proxy origin, and diagnose older installs.
Open guideHTTP API and client
Use zodex-client or raw HTTP calls against the direct JSON API for command execution, stdin writes, and patch application.
Open guideReference
MCP tools
Document the three ChatGPT-facing tools exposed by zodexd, their inputs, outputs, annotations, and expected usage patterns.
Open guideCommand reference
A complete command map for the operator CLI, Sprite commands, proxy commands, GitHub grant commands, agent helper, local service helpers, and direct HTTP client.
Open guideTroubleshooting
Diagnose ChatGPT connection issues, setup failures, push-grant problems, YOLO mode mismatches, stale credentials, Sprite service failures, TLS errors, and proxy routing issues.
Open guideDevelopment and release checks
Build, test, inspect, and release the Rust runtime and the embedded Astro documentation site.
Open guideDocs site maintenance
Run, edit, validate, and deploy the Astro documentation site that lives inside the zodex repository.
Open guideChangelog
Release notes for zodex.
Open guide