# Share a preview from each git worktree

> Parallel agents in git worktrees (Claude Code, Codex, Cursor, Conductor): give each dev server a fixed port and share each branch with its own qURL link.

Source: https://layerv.ai/guides/share-previews-from-git-worktrees/

---

[← All guides](https://layerv.ai/guides/) 

# Share a preview from each git worktree

## Why qURL here

Give each worktree its own fixed port and named qURL™ resource so parallel branches stay separate. Review the running app without deploying a copy, and delete its resource before reusing the port.

Copies a prompt for any agent that runs commands. 

## What you need

- Two or more git worktrees of one repository, each running its own dev server
- A qURL CLI release from 3.6.0 on, which has qurl preview set

Content updated November 4, 2026.

## Steps

When parallel coding agents each work in a git worktree, give each worktree’s dev server its own fixed port, publish each port with qURL, and name each resource after its branch with `qurl preview set`. Each port gets its own CRID, so a link from `qurl share` opens that branch only. Delete a branch’s resource before another worktree reuses its port: the CRID belongs to the address, not the code.

1. ### Install the qURL CLI  
On macOS, install it with Homebrew. On Linux and Windows, download the package for your platform from the latest release; the CLI page lists each one. Nothing asks you to sign up.  
```  
brew install layervai/tap/qurl
qurl --version
```
2. ### Give each worktree a fixed port  
Start each worktree’s dev server on a port of its own, and make it fail rather than move when that port is taken. Vite moves to the next free port unless --strictPort is set, so a busy port would put one branch on another branch’s address. For other dev servers, set the port explicitly and check the address the server prints. Claude Code, Codex and Cursor create the worktree but don’t document a port for it, so name the port in your prompt; Conductor sets CONDUCTOR\_PORT for each local workspace, as the table below shows.  
```  
git worktree add ../app-checkout checkout-flow
cd ../app-checkout && npm run dev -- --port 5174 --strictPort
```
3. ### Publish each worktree’s port  
Run one publish per port. Each address gets its own CRID, and the background service serves them all. The Access line of each says private.  
```  
qurl publish http://127.0.0.1:5173
qurl publish http://127.0.0.1:5174
```
4. ### Name each resource after its branch  
The name is what people see on the page before they open it, so a reviewer can tell the branches apart. It is public metadata: use the branch’s purpose, not a ticket title with customer details in it.  
```  
qurl preview set <CRID> --name "checkout-flow"
```
5. ### Make a link for each reviewer and branch  
A link opens one resource once. Run `qurl share` with the CRID of the branch that reviewer should see.  
```  
qurl share <CRID> --ttl 1h
```
6. ### Send the link to one person  
Send it in a direct message, not a public channel: whoever opens it first uses it. Avoid email and apps that preview links, because a scanner that runs the page could use its one opening. Don’t open it yourself to check it, for the same reason. Run `qurl share` again whenever you need a fresh link.
7. ### Check which CRID serves which branch  
`qurl list` shows each resource with its target address. Match the port to the worktree before you make another link.  
```  
qurl list --status active
```
8. ### Retire a branch’s resource before its port is reused  
Publishing an address again returns the same CRID, with the same people allowed. If the next worktree starts on a merged branch’s port, everyone who had access to that branch can open the new code. Delete the old resource first; it asks you to confirm, and its CRID never works again. To keep a CRID and move it to a new port instead, use `qurl restart` with --target.  
```  
qurl delete <CRID>
# or keep the CRID and move it:
qurl restart <CRID> --target http://127.0.0.1:5180
```

## What the recipient sees

Each reviewer opens their link and sees the branch it was made for, at its own qurl.site address.

Hot reload works through the link, so they see the agent’s edits to that worktree as they land.

## Where each coding agent puts a worktree, and which port to publish

From each tool’s docs, checked on 2026-11-04\. None of the agents below documents a dev-server port per worktree except Conductor, so pick the port yourself and publish that address.

__Where each coding agent puts a worktree, and which port to publish__
| Tool        | How it starts a worktree                                                                                      | Port for the dev server                                                                            | What to publish                                                                               |
| ----------- | ------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| Claude Code | claude --worktree <name> (or -w): a worktree under .claude/worktrees/<name>/ on a new branch worktree-<name>  | Not documented; tell Claude which port to use                                                      | qurl publish http://127.0.0.1:<port>                                                          |
| Codex app   | Choose Worktree beneath the composer in a new chat; an optional local environment runs setup scripts          | Not documented; set it in the prompt or the setup script                                           | qurl publish http://127.0.0.1:<port>                                                          |
| Cursor      | /worktree in a chat, or start the agent in a worktree from the Agents Window; setup in .cursor/worktrees.json | Not documented; set it in the prompt or the setup commands                                         | qurl publish http://127.0.0.1:<port>                                                          |
| Conductor   | Each workspace is a separate, git-backed copy of the project on its own branch                                | CONDUCTOR\_PORT: the first of 10 ports assigned to a local workspace (not set in cloud workspaces) | npm run dev -- --port "$CONDUCTOR\_PORT", then qurl publish http://127.0.0.1:$CONDUCTOR\_PORT |
| git         | git worktree add <path> <branch>: one repository, several working trees                                       | Whatever you start there                                                                           | qurl publish http://127.0.0.1:<port>                                                          |

Sources: [Claude Code: worktrees](https://code.claude.com/docs/en/worktrees) , [Codex: git worktrees](https://learn.chatgpt.com/docs/environments/git-worktrees) , [Cursor: worktrees](https://cursor.com/docs/configuration/worktrees) , [Conductor: workspaces and branches](https://www.conductor.build/docs/concepts/workspaces-and-branches) , [Conductor: environment variables](https://www.conductor.build/docs/reference/environment-variables) , [git worktree](https://git-scm.com/docs/git-worktree).

## Troubleshooting

__Troubleshooting__
| If you see                                                     | Do this                                                                                                                                                                                         |
| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| A reviewer sees the wrong branch                               | Two dev servers swapped ports, or one moved because its port was busy. Stop both, start each with its fixed port and --strictPort, and check qurl list --status active before making new links. |
| The recipient sees “Blocked request. This host is not allowed” | Vite rejects qURL’s hostname. Add .qurl.site to server.allowedHosts in the shared Vite config; it covers every worktree and every link.                                                         |

__More troubleshooting__
| If you see                                                                                                             | Do this                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| qurl publish says the local app is not accepting TCP connections                                                       | Start the app first and check that curl works on the same address. qurl publish connects to localhost as 127.0.0.1, so if your app listens only on IPv6 (on macOS or Linux, lsof -iTCP -sTCP:LISTEN -nP shows \[::1\]), publish 'http://\[::1\]:PORT' instead, or start the dev server with --host 127.0.0.1 and publish that address. Neither requires listening on your LAN. Keep the quotes: zsh treats the brackets as a pattern. |
| The recipient sees “Access link invalid”                                                                               | The link was already used or has expired. Run qurl share again and send the new link.                                                                                                                                                                                                                                                                                                                                                 |
| The recipient sees “Resource not found”                                                                                | The resource was deleted after the link was made. Publish the app again, then run qurl share and send the new link.                                                                                                                                                                                                                                                                                                                   |
| publish rejects http://127.0.0.1 with “only HTTPS URLs are allowed”, asks you to log in, or prints no Access: line     | Your qURL CLI is out of date. On macOS run brew update, then brew upgrade qurl; elsewhere install the latest release. After updating, qurl --version prints 3.4.1 or later, and every publish is private by default.                                                                                                                                                                                                                  |
| publish says this Linux session “can’t reach a systemd user manager”                                                   | You are in a container or sandbox without a user service manager. Run qurl publish with --foreground; sharing lasts as long as that process runs. [Container and CI setup →](https://layerv.ai/guides/share-from-a-container-or-ci/)                                                                                                                                                                                                  |
| publish says “Quota Exceeded” with “protected resource limit reached”, or “Your qURL account has reached a plan limit” | You can see this without an account: a device with no account can keep up to 3 active resources, with links that last up to 24 hours. Run qurl list --status active, then qurl delete <CRID> for any you no longer need (it asks you to confirm; --yes skips that). qurl stop keeps the resource, so it does not free a slot.                                                                                                         |

## Frequently Asked Questions

How many branches can I share at once? 

Without an account, this machine can keep up to 3 active resources, with links that last up to 24 hours, and a stopped resource still counts. Delete resources for merged branches, or link a free LayerV account with qurl account setup, which raises the limit to 10.

Can each coding agent publish its own worktree? 

Yes. Every agent that runs as your user on this machine uses the same qURL identity, so you can list, share or delete any of their resources. Tell each agent its port, and ask it to report the CRID and the name it set.

Does claude --worktree give each session its own port? 

No. Claude Code’s docs say --worktree creates an isolated worktree on its own branch and can copy gitignored files such as .env into it with a .worktreeinclude file; they say nothing about ports. Two sessions that both run npm run dev can collide, so give each one a port, and use --strictPort with Vite.

How is this different from Vercel branch previews? 

Vercel builds a preview deployment when you push a commit to a branch other than production, and its branch URL follows the latest push. qURL shows the worktree as it is right now, including edits the agent has not committed, served from your machine with nothing deployed.

Why not one link that switches branches? 

A link opens one resource, and a resource is one address. Switching the branch behind a port would show it to everyone who already has access to that port, which is the mistake the last step guards against.

Who else can reach my app while the link is open? 

Opening the link starts a session for that browser, which lasts 1 hour by default. After a browser opens it, another browser on the same public IP cannot use its access. A script or agent that opens the link without a browser is admitted by its network address instead, which other devices on that public IP share until the session ends. A link admits whoever opens it: the API’s IP and country rules do not apply to the signed links qurl share issues. Keep your app’s own sign-in for anything sensitive.

Does my computer have to stay on? 

Yes. The app is served from your machine, so the machine and the app must be running and connected. The background service reconnects after sleep, but the app is unavailable while the machine is asleep.

## Related Resources

[Guide: Give every pull request a private preview from GitHub Actions →](https://layerv.ai/guides/private-pull-request-previews-on-github-actions/) [Guide: Share an app from a GitHub Codespace privately →](https://layerv.ai/guides/share-a-codespace-privately/) [Guide: Share an app from a remote dev server over SSH →](https://layerv.ai/guides/share-from-a-remote-dev-server/) [Guide: Fix Vite’s “Blocked request” through a tunnel →](https://layerv.ai/guides/fix-vite-blocked-request-host-not-allowed/) [Guide: Fix hot reload through a tunnel →](https://layerv.ai/guides/fix-hot-reload-through-a-tunnel/) [Guide: Share from Claude Code →](https://layerv.ai/guides/share-localhost-from-claude-code/) [Guide: Share from Codex →](https://layerv.ai/guides/share-localhost-from-codex/) [Guide: Share from Cursor →](https://layerv.ai/guides/share-localhost-from-cursor/) [Claude Code docs: worktrees ↗](https://code.claude.com/docs/en/worktrees) [Vite docs: server.strictPort ↗](https://vite.dev/config/server-options#server-strictport)

## Publish your app now

Install the CLI, then run one command. No sign-up, no API key.

[Install the CLI →](https://layerv.ai/cli/)



---

*This markdown version is auto-generated from [https://layerv.ai/guides/share-previews-from-git-worktrees/](https://layerv.ai/guides/share-previews-from-git-worktrees/) for AI agents. Curated agent resources: [llms.txt](https://layerv.ai/llms.txt). For the full interactive experience, visit the HTML version.*

