Quick start: experience the first real remote development loop

This page is the shortest path from “I have Herdr locally” to “ChatGPT can inspect my workstation and keep working after the current browser turn ends.”

For every installation detail, use Installation. For the architecture, read Overview and Architecture.

What you are building#

CopyChatGPT / Web AI
  ↓ MCP + OAuth
Cloudflare Edge
  ↓ authenticated workstation routing
herdr-link
  ↓
local herdr-mcp
  ↓
Herdr + Git + shell + agents

Optionally, the browser extension adds both a return path and a local Side Panel:

CopyHerdr progress / settled
  ↓
browser extension → current Web conversation
        ↘ Browser Control Center

The extension also adds ChatGPT Queue, which saves the next user instruction without interrupting a live reply.

Prerequisites#

You need:

• a working Herdr installation;
• the native herdr-mcp binary from GitHub Releases;
• a Cloudflare account if ChatGPT will connect over the Internet.

A custom domain is not required. Start with workers.dev.

Node.js is not required to run the local MCP runtime. You may still need Node when deploying Edge with Wrangler.

1. Install the local runtime#

Download the current release binary for your platform, place herdr-mcp on your PATH, then verify:

Copyherdr-mcp doctor
herdr-mcp status

Check that something is listening:

Copycurl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8772/

200 or 401 proves the local HTTP process is alive. Prefer top-level doctor / status / update ... commands; do not use herdr-mcp service install as the normal install path.

2. Verify Herdr before adding the Internet#

Do not debug Cloudflare while the local runtime cannot see Herdr.

Check:

Copyherdr --version
herdr api schema >/dev/null

The first real MCP-side check should ultimately be herdr_inspect: it should show actual workspaces, panes and managed Git roots from your machine.

3. Deploy the public Edge#

Copy the local Wrangler template:

Copycp edge/cloudflare/wrangler.user.example.toml edge/cloudflare/wrangler.user.toml

Generate a DNS-safe Worker name:

Copynode scripts/cloudflare-worker-name.mjs "$(hostname)"

Configure the Worker name, workstation identity and OAuth issuer, then deploy:

Copycd edge/cloudflare
npx wrangler deploy --config wrangler.user.toml

The public origin looks like:

Copyhttps://<worker>.<account-subdomain>.workers.dev

MCP URL:

Copyhttps://<worker>.<account-subdomain>.workers.dev/mcp

Keep the origin stable after ChatGPT is connected.

4. Start the workstation link#

The workstation connects outward to Edge over authenticated WSS. You do not expose port 8772 publicly.

Use the repository herdr-link installation/status flow for your local environment, then verify Edge can see the workstation online.

If OAuth works but tools report workstation offline, this is the layer to investigate.

5. Add the ChatGPT Connector#

In ChatGPT Web:

1. enable the available Developer/custom MCP capability for your Workspace;
2. create a custom MCP App/Connector;
3. use https://<edge-origin>/mcp;
4. complete OAuth in the browser;
5. open a new conversation for validation.

Do not paste HERDR_MCP_TOKEN or a Cloudflare API token into ChatGPT.

The current production public contract is epoch 2 / 18 tools, including herdr_skill.

6. Run the first read-only task#

Use a prompt such as:

CopyInspect the current Herdr workspaces and Git status. Read only; do not modify anything.

A healthy first loop looks like:

Copyherdr_inspect
  ↓
herdr_skill
  ↓
select a managed Git root
  ↓
herdr_git status
  ↓
herdr_fs_read / grep
  ↓
answer

This proves more than a green “connected” badge: it proves the public path reaches the real workstation.

7. Try one deterministic edit#

After the read-only path is correct, choose a disposable or safe file and ask ChatGPT for a small change plus a verification command.

The desired behavior is:

Copyinspect Git
  ↓
read target file
  ↓
edit/patch
  ↓
run test
  ↓
show diff

The Web model should not start a local coding agent merely to edit one known line.

8. Try one delegated task#

Now choose a task that actually benefits from independent reasoning, for example:

CopyInvestigate why this test is failing and implement the narrowest fix. Keep unrelated files unchanged.

The Web planner can dispatch a Herdr-native worker, then use herdr_since, Git and tests to verify the result.

The agent's final prose is not the source of truth; the repository is.

9. Add the browser extension for long work#

Use the versioned extension asset from the same GitHub Release as the native runtime, extract it to the stable managed extension directory, and load that directory through chrome://extensions → Load unpacked. The full path is documented in Browser extension.

Then install the Native Messaging host:

Copyherdr-mcp native-host install
herdr-mcp native-host status

Bind the current Web scope to the Herdr workspace doing the work. New Auto scopes default off. First confirm:

• the correct workspace is bound;
• the HUD shows the expected state;
• clicking the Herdr toolbar icon opens Browser Control Center directly and shows the real workspace / panes;
• pane create/remove and working/settled changes appear live;
• ChatGPT Queue can save a next-turn instruction without interrupting the current reply.

Then enable Auto where appropriate.

Manual handoff, where supported, can be started with Auto on or off. During transfer, automatic wakes from the source pause and the target conversation inherits the source Auto state.

See Browser continuity, Browser Control Center, and Wake, recovery and handoff.

Three supported usage routes#

ChatGPT with public Connector#

Best when you want a Web model to orchestrate local development from anywhere.

CopyChatGPT → Edge → workstation

Web AI plus browser bridge#

For sites such as z.ai / DeepSeek that do not provide the same native custom MCP connector, the extension can provide a local JSON→MCP compatibility path.

CopyWeb page → extension → Native Messaging → local MCP

See JSON → MCP bridge.

Local MCP client only#

Cursor/curl can connect directly to:

Copyhttp://127.0.0.1:8772/mcp

No Cloudflare Edge is required when the client runs on the same machine.

What “working” means#

A useful acceptance checklist is:

• local runtime is healthy;
• herdr_inspect sees real Herdr state;
• Edge sees the workstation online;
• OAuth succeeds;
• a new ChatGPT conversation gets the current tool catalog;
• a read-only real tool call succeeds;
• a small write/test/diff loop succeeds;
• browser continuity can wake the conversation after a long local task if you install the extension.

At that point you have the intended product experience: a Web planner operating a persistent local development workshop rather than a one-shot remote command endpoint.

Next:

• Installation — detailed setup
• ChatGPT Connector — OAuth, tool snapshots and compatibility
• Best practices — daily orchestration
• Troubleshooting — layer-by-layer diagnosis