zodexChatGPT-native coding on real machines

Local

Quick Start

Run ChatGPT directly on your trusted Apple Silicon Mac with your normal shell, files, and developer tools.

Zodex Local lets ChatGPT work directly on a trusted Apple Silicon Mac. It uses the same three Zodex tools as Sprite mode, but commands run with the logged-in Mac user’s normal shell environment and filesystem permissions.

Local is intentionally not a sandbox. There is no Zodex confinement boundary around the repository you start from. If your user account can read, write, execute, or authenticate to something, a Local tool call can generally do the same, subject to normal macOS privacy controls.

If you want an isolated remote Linux workspace with scoped GitHub write permissions instead, use Quick Start: Zodex (Sprite).

Local quick start

1. Install the Zodex operator CLI

curl -fsSL https://zodex.ashray.xyz/install.sh | bash
export PATH="$HOME/.local/bin:$PATH"
zodex --help
zodex local --help

Local is supported on Apple Silicon macOS.

The normal non-root install uses ~/.local/bin; add the PATH line above to your shell profile to keep it available in new terminals. An explicitly root-run install uses /usr/local/bin instead.

2. Create an OpenAI Secure MCP Tunnel

Open OpenAI Platform tunnel settings and sign in with the same OpenAI account/email you use for ChatGPT.

  1. Choose the Platform organization you want to use.
  2. Create a tunnel in Organization settings → Tunnels.
  3. Associate the tunnel with the ChatGPT workspace that should use Zodex Local.
  4. Copy the tunnel ID. It looks like tunnel_....

Creating or editing the tunnel requires Tunnels Read + Manage. That is an administrative setup permission; Zodex does not need to keep a Manage-capable key afterward.

Local needs no Sprite proxy, Cloudflare Worker, public inbound port, or separate proxy URL. The OpenAI Secure MCP Tunnel is the ChatGPT connection path for Local.

Most OpenAI paid plans support custom MCP servers.

3. Create a runtime API key with only tunnel Read + Use

Create a scoped Platform API key for the runtime. Give it only:

  • Tunnels: Read
  • Tunnels: Use

Do not give the runtime key Manage unless you independently need that permission. Zodex Local uses the key to read the selected tunnel and run the tunnel client; it does not need an OpenAI admin key.

Keep both values handy:

Tunnel ID:   tunnel_...
Runtime key: sk-...

4. Run Local setup

The easiest setup is interactive:

zodex local setup

Zodex prompts for the tunnel ID and runtime key. It stores the runtime key in macOS Keychain, installs and verifies the managed OpenAI tunnel client, and creates the Local state it needs. Setup does not leave your Mac remotely accessible when it exits.

Setup also enables the lightweight Zodex menu bar app by default. The menu app returns when you log in and gives you Start Zodex, Stop Zodex, Open Liveboard, and a persistent Start Folder, but it never starts the Local runtime on its own. Use zodex local setup --no-menu-bar if you prefer to leave the bundled menu app disabled.

For automation, use one of the non-argv secret inputs:

printf '%s\n' "$OPENAI_TUNNEL_RUNTIME_KEY" \
  | zodex local setup \
      --tunnel-id tunnel_<id> \
      --runtime-key-stdin

or:

zodex local setup \
  --tunnel-id tunnel_<id> \
  --runtime-key-env OPENAI_TUNNEL_RUNTIME_KEY

See Local setup and ChatGPT connection for the full setup flow and every setup flag.

5. Start Local from the repo you want ChatGPT to use

cd ~/code/my-project
zodex local start

Or choose a path explicitly:

zodex local start ~/code/my-project

Add a wall-clock TTL when you want access to expire automatically:

zodex local start ~/code/my-project --ttl 4h

start waits until the Local runtime and OpenAI tunnel are ready, then returns. You can close that terminal; Local keeps running until you stop it, its TTL expires, you log out/reboot, or the runtime fails.

The directory you start from is published to ChatGPT as the suggested initial explicit workdir. It is a convenience for the model, not a filesystem boundary. Every exec_command and apply_patch request still carries an explicit absolute workdir, and an Agent can intentionally use another accessible path later.

ChatGPT caches MCP server instructions and tool descriptions in the app definition. If you stop Local and restart it from a different directory, open the Zodex Local app in ChatGPT app settings and choose Refresh before starting a fresh conversation. Restarting Local alone cannot invalidate ChatGPT’s app cache.

6. Add the tunnel to ChatGPT

ChatGPT developer-mode access and Platform tunnel permissions are separate.

In ChatGPT on the web:

  1. Enable developer mode for your account/workspace if needed.
  2. Open Settings → Apps → Create (or the developer-mode Plugins page).
  3. Choose Tunnel as the connection method.
  4. Select your tunnel, or paste its tunnel_... ID.
  5. Scan the tools and create the app.
  6. Open a fresh chat, enable/select the Zodex app, and ask ChatGPT to inspect or work on the repo you started Local from.

Most OpenAI paid plans support custom MCP servers.

For workspace-specific steps and tunnel visibility troubleshooting, see Local setup and ChatGPT connection.

What Local gives ChatGPT

The model sees exactly three Zodex tools:

  • exec_command — run a command in an explicit absolute workdir;
  • write_stdin — continue, poll, type into, or kill a long-running process;
  • apply_patch — apply a patch in an explicit absolute workdir.

See MCP tools for the shared tool contract.

The Local trust model

Local is for a machine you intentionally trust ChatGPT to operate.

Commands run as your logged-in macOS user with the environment captured when you run zodex local start. That means Homebrew, language toolchains, user-installed CLIs, credentials, Git configuration, and filesystem access work like they do from your normal shell.

This also means the start directory is not a permission boundary. A command can use absolute paths, cd elsewhere, read another repo, or use credentials available to your account.

macOS remains in charge of its own privacy permissions. Protected locations such as Desktop, Documents, Downloads, iCloud Drive, or app data may require a normal Files & Folders or Full Disk Access grant. Zodex does not edit TCC databases or bypass macOS privacy controls.

If you want remote isolation and a GitHub-specific autonomy boundary, use Sprite permissions and autonomy instead.

One runtime, many ChatGPT Agents

One Local runtime can serve multiple ChatGPT conversations at the same time. You do not start another daemon or tunnel for each chat.

ChatGPT supplies _meta["openai/session"] automatically with tool calls. Zodex uses it to group calls from a conversation and assigns a short four-character Agent ID such as k7m2. The model does not need to send an Agent ID in tool arguments.

Each Agent can work in a different repository or Git worktree as long as every command/patch supplies the intended absolute workdir.

One runtime-wide TTL

One runtime-wide TTL controls access for the entire Local service.

There is exactly one TTL for the whole Local runtime. Starting another chat, creating another Agent, running commands, or opening watch never extends it.

Examples:

zodex local start --ttl 30min
zodex local start --ttl 4h
zodex local start --ttl 2d

The TTL is wall-clock time. Sleep does not pause it.

See what ChatGPT is doing now

Local exposes a first-class localhost observability API for viewing ChatGPT tool activity in real time. The default first-party viewer is Liveboard:

zodex local watch

watch starts a temporary loopback capability host and opens the read-only multi-Agent board in your default browser. The board can show up to eight Agent columns, persistent local aliases/order/widths, command lifecycle/output, structured file diffs, stdin/kill interactions, older history on demand, and lazy audit detail.

The terminal viewer remains available explicitly:

zodex local watch --tui
zodex local watch --tui --agent k7m2
zodex local watch --tui --all

--agent and --all are TUI-only filters. Liveboard manages visible Agents through its All Agents drawer instead.

watch is only a viewer. Opening or closing it does not start, stop, or extend Local. The browser never receives the observer Bearer: native Zodex proxies an allowlisted read-only surface through the temporary same-origin capability URL.

See Watch and Liveboard for the full first-party interface, or Local observability API to build your own client.

Inspect durable history

History remains available after watch closes and after Local stops:

zodex local history --last 20
zodex local history --agent k7m2 --since 1h
zodex local history --workdir /absolute/repo/path
zodex local history --id <invocation-id> --raw
zodex local history --format json

The default history is compact and readable. --raw is for exact logical tool input/result evidence when you need to audit a specific invocation.

By default Local keeps history for 60 days or 500 MB, whichever requires cleanup first. See Local configuration.

Stop access

zodex local stop

Stopping Local closes new MCP work, removes the tunnel connection, and attempts to kill everything normally spawned by Zodex across all Agents. Deliberately self-daemonized or separately launchd-registered processes are outside the containment promise.

stop is safe to run again if Local is already stopped.

Your normal Local workflow

A typical day looks like this:

cd ~/code/my-project
zodex local start --ttl 4h

# Use one or more ChatGPT conversations.
# Optional: open the browser Liveboard.
zodex local watch

# When finished:
zodex local stop

You only need zodex local setup again when you want to replace tunnel credentials/configuration or repair/update the managed tunnel setup.

Local guides

  • Setup and connect ChatGPT — Platform tunnel, runtime key, setup flags, and ChatGPT app creation.
  • Daily use — start, status, watch, history, logs, stop, multiple Agents, and TTLs.
  • Configuration — retention and non-secret Local settings.
  • Local command reference — every zodex local command and flag.
  • Local troubleshooting — tunnel, startup, Keychain, privacy, Agent, and history problems.
  • Watch and Liveboard — browser Liveboard by default, explicit terminal TUI, board controls, output/diff behavior, and recovery.
  • Local observability API — build your own web dashboard, Swift/menu-bar client, terminal UI, editor integration, or other read-only observer.