{"id":51281342,"url":"https://github.com/amxv/zodex","last_synced_at":"2026-06-30T02:00:48.035Z","repository":{"id":345350385,"uuid":"1185191626","full_name":"amxv/zodex","owner":"amxv","description":"now chatgpt can code on your VPS with codex-style tools","archived":false,"fork":false,"pushed_at":"2026-06-27T07:54:24.000Z","size":572,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-27T08:16:28.490Z","etag":null,"topics":["coding-agent","github-app","mcp","model-context-protocol","remote-development","sprites","vps"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/amxv.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-18T10:30:07.000Z","updated_at":"2026-06-27T07:54:27.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/amxv/zodex","commit_stats":null,"previous_names":["amxv/computer-mcp","amxv/zodex"],"tags_count":38,"template":false,"template_full_name":null,"purl":"pkg:github/amxv/zodex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amxv%2Fzodex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amxv%2Fzodex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amxv%2Fzodex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amxv%2Fzodex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/amxv","download_url":"https://codeload.github.com/amxv/zodex/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amxv%2Fzodex/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34949234,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-30T02:00:05.919Z","response_time":92,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["coding-agent","github-app","mcp","model-context-protocol","remote-development","sprites","vps"],"created_at":"2026-06-30T02:00:37.615Z","updated_at":"2026-06-30T02:00:48.027Z","avatar_url":"https://github.com/amxv.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# zodex\n\n`zodex` is a Sprite-first remote coding runtime plus operator CLI.\n\nIt gives a coding agent three remote tools:\n\n- `exec_command`\n- `write_stdin`\n- `apply_patch`\n\nThe product model is:\n\n- read-only GitHub access is always available through a reader app\n- the agent can inspect, edit, test, and commit without GitHub write access\n- write access is off by default\n- the operator grants temporary repo-scoped push access only when a push is intended\n- the default Sprite-side push path uses GitHub App user access tokens obtained with device flow on the Sprite\n- the operator revokes that access after the push\n\n`zodex` is designed for Sprites.dev and assumes a proxy-backed public MCP front door.\n\nThe supported repository slug for this project is `amxv/zodex`.\n\n## Why It Exists\n\n`zodex` is for the case where you want a coding agent to work inside a real remote Linux environment without handing it permanent GitHub write credentials.\n\nThat is enough for the normal coding loop:\n\n1. clone and inspect a repo\n2. edit code and rerun checks\n3. commit locally\n4. grant push access briefly\n5. push normally with `git push`\n6. revoke write access again\n\n## Supported Workflow\n\n1. Set up the two GitHub Apps once:\n   - a read-only reader app\n   - a publisher / push-grant app with `Contents: write`, PR write, and device flow enabled\n2. Install `zodex` on a Sprite.\n3. Point MCP clients at the proxy-backed public URL.\n4. Let the agent clone, inspect, edit, test, and commit.\n5. After committing locally, publish a generated branch and open a PR without `gh` or a direct push grant:\n\n```bash\nzodex-agent github publish-pr \\\n  --repo \u003cowner/repo\u003e \\\n  --title \"Title\" \\\n  --base main \\\n  --body \"Optional description\"\n```\n\n`publish-pr` bundles the current committed `HEAD`, sends it to the local publisher daemon, and lets that daemon mint a short-lived publisher-app token. The daemon pushes only a generated branch using the configured branch prefix, opens the PR, and never exposes the write token to the agent shell.\n\nDirect `git push` remains available only when an operator intentionally starts a temporary repo-scoped grant:\n\n```bash\nzodex-agent github request-push --repo \u003cowner/repo\u003e\nzodex-agent github revoke-push --repo \u003cowner/repo\u003e\n```\n\nThe default active grant TTL is `30m`. Disable the TTL with `--no-ttl`, change it with `--ttl 2h`, and opt into refresh-token caching with `--cache-refresh-token`.\n\nWhen an operator wants to activate a grant remotely from their own machine instead, run:\n\n```bash\nzodex github grant-push --sprite \u003csprite\u003e --repo \u003cowner/repo\u003e\n```\n\nIf the push-grant app client ID is not present in config, pass it directly:\n\n```bash\nzodex github grant-push \\\n  --sprite \u003csprite\u003e \\\n  --repo \u003cowner/repo\u003e \\\n  --publisher-client-id \u003cpush-grant-app-client-id\u003e\n```\n\nThen revoke the remote grant:\n\n```bash\nzodex github revoke-push --sprite \u003csprite\u003e --repo \u003cowner/repo\u003e\n```\n\nThat temporary repo-scoped grant flow is the supported write path.\n`zodex-agent github request-push` and `zodex github grant-push` both use the GitHub App device-flow path.\nBy default, `request-push` does not persist refresh-token state and writes a repo-scoped local grant that expires after `30m`.\nExpired grants stop working in the credential-helper path even if a stale grant file still exists.\nBy default, `revoke-push` removes the active repo grant and keeps the local device-flow refresh state so the remote operator path usually avoids a full reauth on the next grant.\nIf you want to fully forget the local cached auth state too, add `--forget-local-auth`.\n\n\n## Documentation Site\n\nThis repository includes an Astro documentation site for zodex. It covers the Sprite runtime architecture, GitHub App access model, setup flow, temporary push grants, proxy and MCP front door, direct HTTP API, command reference, troubleshooting, and docs maintenance.\n\nRun it locally with:\n\n```bash\nbun install\nbun run dev\n```\n\nValidate the docs site with:\n\n```bash\nbun run check\nbun run build\n```\n\nDeploy the docs worker with:\n\n```bash\nbun run deploy:docs\n```\n\nProduction routing keeps `zodex.ashray.xyz` on the existing Cloudflare proxy worker. That worker forwards `/mcp`, `/mcp/*`, and `/health` to the live Sprite and sends all other paths to the `zodex-docs` worker origin.\n\nThe Astro docs content lives in `src/content/docs`, with site-wide navigation and metadata in `src/data/docs.ts`.\n\n## Setup\n\nThe one canonical setup document is [docs/setup.md](docs/setup.md).\n\nThe install path is the Rust operator CLI:\n\n```bash\nzodex sprite setup \\\n  --sprite \u003csprite\u003e \\\n  --repo amxv/zodex \\\n  --reader-app-id \u003creader-app-id\u003e \\\n  --reader-pem /absolute/path/to/reader.pem \\\n  --publisher-app-id \u003cpush-grant-app-id\u003e \\\n  --publisher-pem /absolute/path/to/push-grant-app.pem \\\n  --url-auth sprite\n```\n\nFor day-to-day push grants, set `publisher_client_id` in `/etc/zodex/config.toml` or export `ZODEX_PUBLISHER_CLIENT_ID` in the environment where you run the command.\nThe publisher app key remains available for the internal `zodex-prd` publish flow.\nAfter setup, the Sprite guest keeps `zodex-agent`, `zodexd`, and `zodex-prd` on-box; the full `zodex` operator CLI remains an operator-machine tool.\nThe Sprite agent should use `zodex-agent`, not the full `zodex` operator CLI, for `show-url`, Git credential helper access, and local push auth.\n\n## Proxy Front Door\n\nUseful commands:\n\n```bash\nzodex proxy inspect --sprite \u003csprite\u003e\nzodex proxy verify-origin --sprite \u003csprite\u003e\ncd proxy/cloudflare-worker\n# set vars.SPRITE_ORIGIN in wrangler.jsonc first\nnpx wrangler deploy\n```\n\nTreat the proxy or its custom domain as the default public MCP front door for Sprite deployments unless the raw Sprite URL has been re-validated against the MCP clients you care about.\n\n## Core Commands\n\n```bash\nzodex sprite status --sprite \u003csprite\u003e\nzodex sprite logs --sprite \u003csprite\u003e --service zodexd --lines 100\nzodex sprite sync --sprite \u003csprite\u003e --force-recreate\nzodex sprite upgrade --sprite \u003csprite\u003e\nzodex-agent github request-push --repo \u003cowner/repo\u003e\nzodex github grant-push --sprite \u003csprite\u003e --repo \u003cowner/repo\u003e\nzodex-agent github list-grants\nzodex-agent github publish-pr --repo \u003cowner/repo\u003e --title \"Title\"\nzodex-agent github revoke-push --repo \u003cowner/repo\u003e\nzodex-agent show-url --host \u003cpublic-host\u003e\n```\n\n## Access Model\n\n- Read access comes from the reader GitHub App.\n- Write access is temporary, explicit, and repo-scoped.\n- The preferred write grant path is `zodex-agent github request-push`, which uses GitHub App device flow directly on the Sprite with a repo-scoped local grant and a default `30m` TTL.\n- The remote operator path `zodex github grant-push --sprite ...` remains supported and keeps local refresh-token cache behavior unless explicitly forgotten.\n- The agent should not run as root.\n- The operator or agent should treat `zodex-agent github request-push` or `zodex github grant-push`, followed by revoke, as part of every push.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famxv%2Fzodex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famxv%2Fzodex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famxv%2Fzodex/lists"}