Create a temporary, filtered snapshot of a local folder and publish it through a Cloudflare Quick Tunnel for short-lived code review. The source folder is never served directly.
Filter locally. Share deliberately. Review safely.
- Project Status
- Requirements
- Cloudflare / cloudflared Setup
- Protected Access
- Before You Share
- Quick Start
- Usage
- Desktop Integration
- Machine-Readable Lifecycle
- Safety Model
- Quick Tunnel Lifecycle
- Developer Verification
- Documentation
- License
No tagged release exists yet. Until the first release, the latest commit on
main is the supported line. Confirm the exact revision and GitHub Actions
checks before publishing or sharing a release candidate.
| Component | Documented support | Enforced check | Tested evidence |
|---|---|---|---|
| Windows | PowerShell 7; Python 3.9+ | #requires and runtime Python check |
PowerShell 7.6.3 and Python 3.14.6 on 2026-07-19 |
| macOS | macOS 14+ Homebrew path; Python 3.9+ | wrapper and Finder doctor check Python 3.9+ | macOS 15.7.7 x86_64 and Python 3.9.6 on 2026-07-19 |
cloudflared |
A release still inside Cloudflare's one-year support window | executable presence; Finder doctor also reports the version | 2026.6.1 in the macOS VM and 2026.7.1 on Windows |
qrencode |
Optional | no hard requirement | 4.1.1 in the macOS VM |
cloudflared must be available on PATH. Keep it updated to a release that is
still supported by Cloudflare. The Finder path additionally requires built-in
zsh, Terminal, Finder, Automator, AppleScript, and plutil.
See the macOS guide for Finder Quick Action installation, feature parity, and verification.
Quick Tunnel uses Cloudflare's cloudflared client to connect the local review
server to Cloudflare. The project uses Quick Tunnels / TryCloudflare by
default: cloudflared creates a random *.trycloudflare.com hostname and
forwards it to the local HTTP server. You do not need to add a domain to
Cloudflare DNS for this mode.
Official Cloudflare references:
cloudflareddownloads and installation- Quick Tunnels / TryCloudflare
- Create a managed Cloudflare Tunnel
Windows (PowerShell)
The official Cloudflare download page provides both the Windows executable and
MSI installer. For a command-line install, Windows Package Manager can install
the published Cloudflare.cloudflared package:
winget install --id Cloudflare.cloudflared --exact --source winget
cloudflared --versionIf WinGet is unavailable or its package is behind the current Cloudflare
release, use the MSI/executable links on the official Cloudflare download page
above. Cloudflare notes that Windows cloudflared installations do not
automatically update.
macOS
brew install cloudflared
cloudflared --versionCloudflare documents Homebrew as the standard macOS installation path.
If a local web server is already listening on port 8080, the Cloudflare
documentation's minimal test is:
cloudflared tunnel --url http://localhost:8080
cloudflared prints a temporary public https://<random>.trycloudflare.com
URL. Quick Tunnel is intended for testing and development; Cloudflare currently
limits it to 200 in-flight requests and does not support Server-Sent Events
(SSE). Quick Tunnel URLs are public unless the origin application adds its own
authentication layer.
The Quick Tunnel mode used by this project is unauthenticated and does not provide a shared-password option. Anyone who has the temporary URL can reach the published snapshot while the tunnel is active.
For access-controlled sharing, use a managed Cloudflare Tunnel + Cloudflare
Access. A public hostname requires a domain managed in Cloudflare. Human users
can authenticate through a configured identity provider or Email One-Time PIN.
Automated reviewers can use Cloudflare Access service tokens
(CF-Access-Client-Id and CF-Access-Client-Secret); the Access application
must include a matching Service Auth policy that allows the token.
| Mode | Authentication | Requirements | Use |
|---|---|---|---|
| Quick Tunnel | None | cloudflared |
Short-lived, low-sensitivity review |
| Managed Tunnel + Cloudflare Access | IdP / Email One-Time PIN for people; service token for machines | Cloudflare-managed domain, managed Tunnel, Access application and policies | Access-controlled review |
Official references:
- Publish a self-hosted application with Cloudflare Access
- One-Time PIN login
- Service tokens
- Authenticate coding agents
A local shared-password gate is not part of the supported runtime documented by this repository.
Warning
Quick Tunnel endpoints are unauthenticated and temporary. Anyone who obtains the generated URL can access the filtered snapshot while the process is live. Do not use this project for credentials, regulated data, or other high-sensitivity material.
Before opening a public tunnel:
- Inspect the selected folder carefully.
- Run
-ValidateOnlyto verify the filtered snapshot locally. - Add project-specific exclusions with
-AdditionalExclude. - Use
-Yesonly inside an already approved workflow.
Use the sharing and filtering matrix to understand what the default filter does—and does not—protect.
Windows — share a folder for 30 minutes:
.\share-codex-review.ps1 "D:\Projects\MyProject"macOS — share a folder for 30 minutes:
python3 ./macos/share-codex-review.py "/path/to/MyProject"Validate locally without opening a public tunnel:
# Windows
.\share-codex-review.ps1 "D:\Projects\MyProject" -ValidateOnly# macOS
python3 ./macos/share-codex-review.py "/path/to/MyProject" --validate-onlyThe default public lifetime is 30 minutes. Change it with -DurationMinutes,
or press Enter to stop early.
| Purpose | Option |
|---|---|
| Change lifetime | -DurationMinutes 10 |
| Select a local port | -Port 8080 |
| Limit copied file size | -MaxFileSizeMB 25 |
| Add a wildcard exclusion | -AdditionalExclude "private/*" |
| Disable QR output | -NoQrCode |
Skip the SHARE prompt |
-Yes |
| Change retry count | -QuickTunnelAttempts 3 |
| Change retry base delay | -QuickTunnelRetryBaseSeconds 5 |
| Emit versioned NDJSON | -Json |
Caution
-Yes creates an unauthenticated public endpoint without the interactive
confirmation. Use it only inside an already approved workflow.
python3 ./macos/share-codex-review.py "/path/to/MyProject"Validate only (no public tunnel):
python3 ./macos/share-codex-review.py "/path/to/MyProject" --validate-only
Double-click context-menu-setup.cmd, choose Install, and type INSTALL.
The command is installed for the current Windows user only. On Windows 11 it
may appear under Show more options. The installed entry is labelled
Make Q-Tunnel.
To remove:
.\manage-context-menu.ps1 -Action UninstallInstall the per-user Finder Quick Action:
/bin/zsh ./macos/manage-finder-quick-action.sh installRun the non-mutating compatibility and version check first, or choose
Run doctor from finder-quick-action-setup.command:
/bin/zsh ./macos/manage-finder-quick-action.sh doctorSelect one folder in Finder, then choose Quick Actions > Make Q-Tunnel.
Removal is recoverable: installed files are moved into sibling .del folders
instead of being permanently erased.
Use -Json on Windows or --json on macOS for versioned NDJSON lifecycle
events.
| Mode | Events emitted |
|---|---|
| Validate-only | validated, cleanup |
| Public mode | public_ready (while URL is live), cleanup |
| Error | error (nonzero exit code) |
JSON public mode requires -Yes or --yes so stdout cannot block on a prompt.
Version 1 fields: schema_version, event, mode, public_url,
expires_at, server_pid, tunnel_pid, staging_root, error.
The explicit JSON option permits disclosure of the local staging_root; do not
forward that field unnecessarily. See the
Agent integration contract.
- Copies permitted files into an isolated temporary staging directory.
- Excludes common dependency, VCS, environment, credential, and key paths.
- Blocks high-signal secret formats before opening the tunnel.
- Skips reparse points and files above the configured size limit.
- Serves source-controlled HTML, SVG, scripts, and markup as inert plain text.
- Adds restrictive browser security headers and disables caching.
- Binds the local origin to
127.0.0.1only. - Requires explicit
SHAREconfirmation unless-Yesis supplied. - Stops the local server and tunnel and removes staging files on exit.
Limitations: The secret scan is intentionally conservative and cannot guarantee that every credential or private datum has been detected. It scans only configured text extensions whose staged size is at most 2 MiB; larger or unknown-format files may still be copied when they are under the separate copy-size limit. Remote inert rendering also does not make a downloaded file safe to execute.
Cleanup is guaranteed for normal exit and handled failures. Force-killing the process, terminating the host, or an operating-system crash can leave temporary files behind. Follow the threat model for recovery and residual-risk guidance.
The Quick Tunnel is created only after local validation and explicit approval. The terminal displays the public URL, process IDs, verification result, and scheduled expiration time. When the lifetime expires, the tunnel is stopped and temporary files are removed. Context-menu launches keep the completion message visible until acknowledged.
Transient Cloudflare-side 500/1101 Quick Tunnel creation failures are retried
up to three times with exponential backoff; configuration errors and rate-limit
responses are not retried.
Note
Cloudflare Quick Tunnels are unauthenticated, temporary development endpoints. Anyone with the generated URL can access the filtered snapshot while the process is running.
Windows:
./windows/tests/test-share-codex-review.ps1
python -m unittest discover -s tests -vmacOS:
PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover -s macos/tests -v
PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover -s tests -vGitHub Actions runs the Windows suite, macOS Python and native syntax checks, shared safe-server tests, and a Python 3.14 compatibility job. CI never opens a public tunnel or installs desktop integrations.
| Resource | Link |
|---|---|
| Documentation index | docs/README.md |
| Threat model | docs/THREAT_MODEL.md |
| Sharing and filtering matrix | docs/SHARING_MATRIX.md |
| Agent integration contract | docs/AGENT_INTEGRATION.md |
| macOS guide | macos/README.md |
| Security policy | SECURITY.md |
| Contributing guide | CONTRIBUTING.md |
| Changelog | CHANGELOG.md |
Quick Tunnel Review Share is licensed under the
MIT License (SPDX-License-Identifier: MIT).