devleash

Leash your AI coding agent from your phone. Review git changes and commit/push, run & preview dev servers, browse files, and chat with Claude Code — all running on your Mac, reachable from anywhere through a self-hosted relay.

Mental model: phone → relay (a tiny VPS) → agent on your Mac → git / files / processes / Claude. Your Mac never opens an inbound port; the agent dials out.

Quick start

On the machine you want to control (Mac/Linux; Windows works for most features):

npx devleash

It prints http://localhost:4555/setup — open it and you get a friendly page to:

1. Pick the folders to expose (browse + tick; everything else stays private).
2. Choose a relay — the default, or your own.
3. Optionally turn on end-to-end encryption.
4. Pair: scan the QR with the app.

That's it. (No global install needed; npx always runs the latest. State is saved in ~/.pocket-git/.)

What you need on the machine

The agent shells out to real tools — the in-app Diagnostics screen checks these and gives copy-paste fixes:

| Tool | Powers | Required? | |---|---|---| | Node + git | the agent, and review/commit/push | yes | | Claude Code (claude, logged in) | the chat | for chat | | tmux | the live terminal | optional | | cloudflared | remote dev-server preview tunnels | optional |

What you can do from the phone

• Review & ship — staged/unstaged diffs, stage/unstage/stage-all, commit (with an AI-suggested message), fetch/pull/push, commit history + per-commit diff.
• Chat with Claude Code — send a prompt to the agent; watch streaming text + tool calls. Per-action Allow/Deny approval, or flip to Auto mode. Sessions persist and auto-resume.
• Run & preview — start detected dev servers, tail logs, and open a live preview tunnel (cloudflared) from anywhere.
• Live terminal — a tmux-mirrored, real Claude Code TUI you can drive (Enter/Esc/⌃C/↑↓/Tab).
• Files — browse and read any file under your exposed folders.
• Activity — a log of what happened, with push notifications ("Claude finished — review") when you're away.

The three pieces

server.js     the AGENT — runs on your machine. Serves the UI + /setup, dials out to a relay.
relay.js      the RELAY — a tiny token-keyed broker you host once. Pipes phone↔agent. Stores no code.
public/       the SPA   — the phone UI (also runs as a web app served by the relay).

A Capacitor wrapper for the native iOS/Android app lives in app/; relay deploy (Docker + Caddy) in deploy/.

Hosting the relay

Use the default relay, or run your own for full isolation:

cd deploy
echo "DOMAIN=relay.yourdomain.com" > .env    # A-record it at the VPS, DNS-only
docker compose up -d --build                 # Caddy auto-issues TLS, proxies wss + https

Then run the agent against it (or just pick it in /setup):

RELAY_WS=wss://relay.yourdomain.com/ws npx devleash

Security

• The token is the gate — whoever holds the pairing token can drive the agent. It's stored in ~/.pocket-git/relay.json (git-ignored); rotate by deleting that file.
• End-to-end encryption (opt-in): with E2E on, the relay only ever forwards ciphertext — it can't read your diffs, files, or chat, even if compromised. The key rides in the pairing QR's #fragment and is never sent to the relay.
• The relay's push registry stores only sha256(token), never the raw token.
• Run the relay over wss:// (TLS).

Full trust model, self-host, E2E activation, and an AnyDesk comparison: see SECURITY.md. Push-notification (APNs) setup: see PUSH-SETUP.md.

Config (env overrides the /setup config; both override defaults)

| Var | Default | Meaning | |---|---|---| | ROOTS | $HOME or /setup choice | browsable roots (colon-separated); the picker is jailed to these | | RELAY_WS | from /setup | wss://host/ws to enable relay mode | | RELAY_PUBLIC | derived from RELAY_WS | the https://host the phone opens (for the QR) | | PG_E2E | 0 | 1 enables end-to-end encryption (re-pair after enabling) | | PG_DATA_DIR | ~/.pocket-git | where token/config/attachments are stored | | PORT | 4555 agent / 4566 relay | listen port | | PIN | — | require this code on direct (LAN) HTTP access | | ANTHROPIC_API_KEY / ANTHROPIC_MODEL | — / haiku | AI commit-message suggestions |

Roadmap

Native App Store / Play wrapper · a clickable desktop (tray) app that bundles the agent · P2P-direct relay fallback · per-device approve/revoke · preview tunnels routed through the relay.