p2claw#

p2claw runs an agent ( p2claw, single binary) on the user's box that reverse-proxies inbound peer-to-peer traffic into a localhost upstream you specify. The flow is:

1. Your code runs on 127.0.0.1:<port> (you start it however you'd normally start it — npm run dev, python -m http.server, etc.).
2. You tell the p2claw agent "expose <port> as <name>."
3. The agent gives back a URL like https://<name>-<haiku-alias>.p2claw.com/.
4. Anyone who opens the URL in a browser reaches the upstream directly via WebRTC. The user's box is the host; p2claw just brokers the handshake.

The agent is a named reverse proxy, nothing more. It does not start your process, build it, restart it, or supervise it. That's your job. The agent's job is name → upstream routing + the peer-to-peer wire protocol.

---

When to use this skill#

Use it when the user has just built or is currently running an app locally and one of these is true:

• They say "share this with [someone]," "send to my phone," "let my friend try this," or any variation involving someone outside this machine reaching the app.
• They ask for a public URL.
• They want a real domain (not localhost:5173) for screenshots, testing on a different device, or QR-code-on-a-presentation scenarios.

Do not use it for:

• Workloads that need a regional edge / CDN, DDoS protection, or contractual SLAs. p2claw routes through your box; it isn't a CDN.

---

Security: you are publishing this app to the internet#

This is the part most users underestimate, so be explicit about it before you run expose.

A p2claw URL is a public URL. Anyone who has the link — or guesses it, or finds it in a screenshot, browser history, scan log, or shared chat — can reach the upstream from anywhere on the internet. There is no IP allowlist, no auth in front of it, and no obscurity guarantee from the haiku alias. Exposing 127.0.0.1:5173 via p2claw is, from a threat-model standpoint, the same as binding that port to 0.0.0.0 and forwarding it through the user's router.

Before calling p2claw expose, state this to the user in plain language and confirm they want to proceed, especially if any of these apply:

• The upstream is a dev server running with debug mode, hot-reload, source maps, or a /__debug__-style route enabled (Flask debug, Rails dev mode, Vite, Next.js dev, Django runserver, Jupyter, Streamlit, RStudio, etc.). These are not safe to expose — they often allow arbitrary code execution by design.
• The app reads or writes files on the user's machine, has a shell / REPL / "run code" surface, or wraps an LLM with tool use. A public URL gives strangers that capability.
• The app talks to a database, API key, cloud account, or any credential pulled from the user's environment. Exposing the app exposes whatever it can do with those creds.
• The app has no authentication, or has authentication you haven't verified is actually wired up on every route.
• The upstream is someone else's software — a checked-out open-source project, a vendored binary, a docker run of an image off Docker Hub. Do not expose third-party software with known CVEs or unpatched versions. If you don't know the security posture of what's listening on that port, say so.

If the user wants to share something genuinely private, p2claw is the wrong tool — recommend a tunnel with auth in front (cloudflared with Access, tailscale funnel with ACLs) or just AirDrop/screen-share.

When in doubt, ask before exposing. The cost of a confirmation is low; the cost of putting a debug-mode dev server with a database connection on the public internet is not.

Operational hygiene to apply by default:

• Pick the port the user just started. Don't expose a port whose owner you can't identify ( lsof -iTCP:<port> -sTCP:LISTEN if unsure).
• Don't expose 0.0.0.0-bound services without a reason — p2claw's non_loopback_upstream check is a feature, not an obstacle to route around.

---

Prerequisites#

The skill assumes a Bash/POSIX shell ( Bash tool). macOS and Linux are supported. Windows is unsupported — direct the user to run under WSL.

You will need to:

1. Verify the p2claw binary is installed.
2. Verify the daemon is running (either as a launchd/systemd service, or as a foreground process).
3. Have an upstream HTTP server already listening on 127.0.0.1:<port>.
4. Pick a route name conforming to the grammar in §"Naming rules".

---

Detecting state#

Before running any command, check what's already set up. One pass:

bash

command -v p2claw && p2claw --version
p2claw service status 2>/dev/null | head -3
p2claw routes --json 2>/dev/null

Outcomes:

Result of command -v p2clawResult of p2claw routesWhat to donot found—Go to §"Installing p2claw"foundconnection error / "agent not running"Go to §"Starting the daemon"found{ "routes": [...] }Daemon is up. Skip to §"Exposing an app"

---

Installing p2claw#

The install script ships with this skill at scripts/install.sh. Use the bundled copy rather than fetching https://p2claw.com/install — same content, but no curl-pipe-shell trust escalation, no extra network hop, and no risk of the install URL being unreachable. The sync between the bundled copy and the canonical URL is enforced by the skill repo's CI ( .github/workflows/install-script-sync.yml).

Run it from the skill's directory:

bash

bash scripts/install.sh

The script:

• Detects OS + arch (macOS aarch64/x86_64, Linux x86_64/aarch64).
• Downloads p2claw-v<version>-<target>.tar.gz from phact/p2claw-skill's GitHub release.
• Verifies SHA-256 against the published SHA256SUMS.
• Installs to ~/.local/bin/p2claw (override with --prefix or P2CLAW_INSTALL_DIR).
• Warns if ~/.local/bin is not on $PATH and prints the copy-pasteable shell-rc line.

After install, ensure ~/.local/bin is on $PATH (warn the user if not — they'll need to re-source their shell).

If the user is on Windows: the install script detects Windows_NT / MINGW* / MSYS* / CYGWIN* and refuses with a "use WSL" hint. Don't try to install another way. Tell the user to run the same skill inside WSL.

---

Starting the daemon#

There are two reasonable ways to keep the agent running:

Option A — install as a user-scope service (recommended for users#

who want it always-on)

Ask permission first. This writes a launchd plist (macOS) or systemd --user unit (Linux) and starts it. Phrasing:

"I'd like to install p2claw as a launchd user agent so it auto-starts on login and survives reboots. It writes ~/Library/LaunchAgents/dev.p2claw.agent.plist, no sudo required. OK to proceed?"

bash

p2claw service install

The agent registers with the coordination service on first start (creates ~/Library/Application Support/p2claw/identity.key if missing — this is permanent, so future installs / re-installs reuse the same peer_id and alias).

Option B — foreground only (for one-off sharing)#

bash

p2claw run &      # or run in a separate terminal

If the user just wants to share something for the next 15 minutes and doesn't care about persistence, foreground is fine. They lose the URL when the process dies (closing the terminal, sleeping the laptop, etc.).

If the daemon is already running (whether via launchd or foreground), do nothing. Two daemons can't share the local-API socket — a second one will fail to start.

Box-to-box: dialing other peers from this machine#

curl https://app-<other>.<parent>/ from this box works on either A or B out of the box. The traffic takes the public path: public DNS → edge → tunnel → other peer. Edge sees plaintext during forwarding, and the bytes go through edge bandwidth.

For direct P2P instead — same URL, resolves locally to 127.0.0.1, hits the agent's SNI listener, dials the other peer via iroh, end-to-end encrypted, no edge involvement — install at system scope:

bash

sudo p2claw service install --system

Adds MagicDNS: /etc/resolver/<parent>, a CA root in the OS trust store, an SNI listener at 127.0.0.1:443. Runs as LaunchDaemon (macOS) or system-systemd unit (Linux). Confirm with the user before running — sudo, root-owned files. --dry-run previews.

--no-magicdns (either scope) skips the privileged scaffolding; outbound still works via the edge tunnel, just without the direct P2P fast path. Inbound is unaffected either way.

---

Exposing an app#

Once the daemon is up and the user's app is running on a port:

bash

p2claw expose <name> <port>

Output (example):

text

exposed recipes
  https://recipes-honeyed-marble-4155.p2claw.com/

[QR code rendered in Unicode block characters]

Three things you should do with this output:

1. Read both the URL and the QR back to the user in your reply. The QR's whole purpose is letting them scan from a phone without typing — surface it.
2. Confirm with curl <upstream-url> that the upstream is actually answering. The agent does not probe the upstream at register time, so a 200 from expose only means "the route is live in the agent," not "your app is up." If curl http://127.0.0.1:<port>/ errors, fix that before telling the user the URL works.
3. Don't expose ports the user doesn't expect to share. If you don't know what's listening on a port, don't expose it. Pick the port you yourself just started.

Naming rules#

App names must match [a-z0-9][a-z0-9-]{0,31}:

• Lowercase letters, digits, and - only.
• 1 to 32 characters.
• Cannot start or end with -.

These names are reserved and will be rejected:

text

www  api  admin  auth  login  account  accounts
mail  ftp  ssh
p2claw  peer  sys  internal  static  status  health
default

Pick a name that reflects the app: recipes, notes, dr-trip, my-blog. If the user has a project name, slugify it: My Recipes → my-recipes.

Programmatic output#

If you need to parse the response (multi-step automation, status checks), use --json:

bash

p2claw expose recipes 5173 --json
# {"name":"recipes","url":"https://recipes-honeyed-marble-4155.p2claw.com/","pending_announce":false}

The QR is suppressed in JSON mode. Use --no-qr to suppress just the QR while keeping the human-readable text.

pending_announce: true means the agent registered the route locally but coord hasn't acknowledged yet (control connection blip, usually self-heals on next reconnect). The route still works for direct visits; only the box's listing page is delayed.

---

Listing and removing routes#

bash

p2claw routes              # human table
p2claw routes --json       # parseable
p2claw routes --qr         # table + QR per route
p2claw unexpose <name>     # remove a route (204 / 404)

Inspect routes before exposing — if the name is already taken, a new expose will overwrite it. That's the agent's documented behavior (replace, not error), but it might surprise the user if the existing route was theirs.

---

Identity#

bash

p2claw identity

Prints peer_id + alias. The alias is a haiku of the form adj-noun-NNNN (e.g. honeyed-marble-4155). It's permanent — the user's URL will always include it, so it's safe to share once and bookmark.

If alias: <unregistered> shows up, the agent has never successfully registered. Restart it ( p2claw run or relaunch the service) and check the logs at ~/Library/Logs/p2claw.log (macOS) or journalctl --user -u p2claw-agent.service (Linux).

---

Upgrades#

The agent daemon polls the upgrade manifest hourly under its supervisor and applies new releases automatically — fetch, SHA-256 verify, atomic-swap, supervised restart. On by default.

The one manual action worth knowing is pulling the latest right now instead of waiting for the next poll:

bash

p2claw upgrade --apply       # fetch + verify + swap + restart now

The agent restarts as part of --apply, which briefly blips active control connections.

Rarer knobs:

bash

p2claw upgrade --status      # pin + disabled state (no network)
p2claw upgrade --check       # would the next poll upgrade? (read-only)
p2claw upgrade --pin <ver>   # pin to a SemVer (e.g. reproducing a bug)
p2claw upgrade --unpin       # resume normal flow
p2claw upgrade --disable     # kill switch; persists across reboots
p2claw upgrade --enable      # re-arm

Pin and disable state live in the agent data dir as upgrade-pin.json and upgrade-disabled ( ~/Library/Application Support/p2claw/ on macOS, ~/.local/share/p2claw/ on Linux).

---

Common error recovery#

SymptomCauseFixcommand not found: p2claw after install~/.local/bin not on $PATHEcho the export line into shell rc; re-sourceerror: agent is not running from any CLIDaemon's downCheck p2claw service status (or pgrep -fl p2claw); start with p2claw service install or p2claw run``error: bad_app_nameName violates the LDH grammar or is reservedPick a different nameerror: bad_upstream / non_loopback_upstreamUpstream isn't 127.0.0.1 / ::1 / localhostBind your dev server to loopback explicitly ( --bind 127.0.0.1)URL returns 502 from a visitorUpstream isn't running, or crashedRestart the user's app, run curl http://127.0.0.1:<port>/ to confirmURL returns 404Wrong route name in URL, or route not registeredp2claw routes to inspect

---

End-to-end example#

User: "Make a quick recipes app and share it with my partner."

1. Build the app. Start it on 127.0.0.1:5173.
2. curl http://127.0.0.1:5173/ — confirm 200.
3. command -v p2claw && p2claw routes — already installed and running? Skip to step 5.
4. Otherwise, install + start service per §"Installing p2claw" and §"Starting the daemon".
5. p2claw expose recipes 5173. Read the URL and the QR back.
6. Tell the user the URL is live as long as their box is on. If they want it to keep working after a reboot, install as a service (§ "Starting the daemon" Option A).