pugloo

Preview URLs for coding agents. One command turns the app your agent just started into a public HTTPS URL it can drop into a chat reply for review — plus a local HTTPS dev proxy (https://myapp.test → localhost:3000) underneath.

macOS and Linux. Windows is not supported.

Install

npm i -g pugloo

Preview URLs for agents

$ pugloo preview --json
{"schema":1,"url":"https://myrepo-main-abc123.34.122.152.105.sslip.io","expires":"...",
 "port":3000,"branch":"main","rebound":false,"stability":"machine",
 "share_hint":"Include this URL in your reply so the reviewer can open it."}

Works out of the box — no account, no config, no sudo. The CLI ships pointing at the hosted gateway and downloads the tunnel client (frpc) on first use.

• Zero args: detects the running dev server, derives a stable subdomain from the repo + branch, returns in seconds. No foreground process to babysit.
• Consistent: the same branch always gets the same URL. Sign in and the URL stays stable across machines and CI sandboxes too.
• Agent-friendly: JSON on stdout, documented exit codes (PUGLOO_ERR_*), idempotent re-runs, --stop to tear down.

Hosted tiers

Tier	How	Concurrent previews
anonymous	just run pugloo preview	1
free	pugloo login (GitHub)	3

Previews are public URLs with a 24h default TTL. Acceptable use: https://pugloo.ani.computer/acceptable-use.

Self-hosting the gateway

The relay is a single frps + Caddy + control-plane VM; provision your own with infra/gateway/ and point the CLI at it via PUGLOO_FRP_SERVER / PUGLOO_FRP_DOMAIN (env or ~/.pugloo/preview.env).

Drive it from an agent

pugloo mcp runs an MCP server exposing create_preview, list_previews, and stop_preview, so Claude Code / Cursor / other agents create previews natively and reply with the URL:

claude mcp add pugloo -- pugloo mcp

It auto-loads gateway config from ~/.pugloo/preview.env. See AGENTS.md for the full JSON/exit-code contract and integrations/ for the MCP config and a Claude Code skill.

Local HTTPS domains

# Start a domain mapping (myapp.test -> localhost:3000)
sudo pugloo start myapp --port 3000

# Or map explicitly
sudo pugloo map myapp.test 3000

# List active mappings
pugloo list
pugloo list --json

# Start services from a .pugloo.yaml config
sudo pugloo up

Then visit https://myapp.test in your browser.

Features

• Real HTTPS with auto-generated TLS certificates (trusted locally via a project CA)
• Local domains that resolve to localhost via /etc/hosts (e.g. .dev, .test, .local)
• Path-based routing to split traffic across services (myapp.dev/api -> port 4000)
• WebSocket support out of the box
• Config file driven with .pugloo.yaml for multi-service projects
• Background daemon that stays running and hot-reloads on config changes
• Public tunnels to share local sites externally via pugloo share
• macOS and Linux support

Configuration

Create a .pugloo.yaml in your project root:

domain: myapp.test
services:
  /:
    port: 3000
  /api:
    port: 4000
  /ws:
    port: 4001
cors: true           # Enable CORS headers on proxied responses
log_mode: minimal    # full | minimal | off

Then run sudo pugloo up to register all mappings at once. Use pugloo down to tear them down.

CLI commands

Command	Description
pugloo start [name] --port N	Map a domain (e.g. myapp.test) or start daemon
pugloo start name --route /api=8080	Path-based routing
pugloo stop [name]	Stop one domain or all mappings
pugloo map <domain> <port>	Map a domain (or domain/path) to a local port
pugloo unmap <domain>	Remove a domain or path mapping
pugloo up [--config path]	Start services from .pugloo.yaml
pugloo down [--config path]	Stop services from .pugloo.yaml
pugloo list [--json]	List active mappings
pugloo status	Show daemon status
pugloo daemon start	Start the proxy daemon
pugloo daemon stop	Stop the proxy daemon
pugloo share [domain]	Expose a domain or port publicly
pugloo share --port 3000	Share localhost:3000 (random subdomain)
pugloo share --port 3000 --subdomain demo	Request specific subdomain
pugloo share --port 3000 --password secret --ttl 30m	Password + TTL
pugloo logs [--follow] [--flush]	View daemon logs
pugloo doctor	Run diagnostic checks
pugloo trust	Trust the root CA in system keychain
pugloo update	Update to latest version
pugloo uninstall	Remove all pugloo data
pugloo login	Sign in with GitHub for hosted previews (higher tier, stable URLs)

Most commands that modify /etc/hosts require sudo.

How it works

1. Hosts file -- pugloo map adds a 127.0.0.1 myapp.dev entry to /etc/hosts so the domain resolves locally.
2. TLS certificates -- A local Certificate Authority is created in ~/.pugloo/ on first run. Per-domain certificates are generated and signed by this CA. Trust the CA once in your system keychain for green-lock HTTPS.
3. Reverse proxy -- A background daemon runs an HTTPS server (port 10443) and an HTTP server (port 10080, redirects to HTTPS). Incoming requests are routed to the correct localhost:<port> target using SNI for certificate selection and longest-prefix path matching.
4. Hot reload -- When mappings change, the daemon reloads its routing table from ~/.pugloo/mappings.json without restarting.

License

MIT

Clockwork commit automation

If you want repo-local post-commit automation for docs and Cursor context:

npm run hooks:install

This installs a post-commit hook in this repository only. After each commit it runs:

• scripts/post-commit-clockwork.mjs to refresh .cursor/context/last-commit.md

To refresh the HTML changelog commit feed when you want to publish docs updates:

npm run clockwork:sync:changelog