wolfpack-bridge
Advanced tools
...:.
:=+=:
. .-*####+-
.- :++**####*=.
- :+***#####*=:.
: .+**######*+==++++++=:..
.. .=*#######*++++====+=--=-.
.:.- -+**######**+*#*+=-:-===:
-. .. -++++***#**++*#*--:---===:
-.:--==+=--=*++*+**********+==------++-
.:----=++*++##########******+=====--=+#=-.
.::-----=+*#%%%%%%#***###*+===--==+*=++=:.
...::::-=+*#%%############*+-----===+****+=:.
:--=-====+******++****##***-.::--++*######**
.++-+++++***********#*+*#***=.:---=+**=--=+==
-**++*++****+***##*++*****++=. ----=+=. ..:-
.+##***+*+*****##*#=-=**=-=-::. -**-::-==+++++
:*%%*+=+=+****##**++****+**+-.. -*=- .::::-=
.-#%#*+*+**#***+++**+****+*++=--+=::-:..:...-+
=###***=*+++++-=*=+++++-====-=:-=--:=---==---
.:-+***+=*+++**+++===*++++=--:= ::=::-=----++
.+****+++++*##+***++=+*-.:--:..-===---=-:-++
.-+###**+++*#****+=---:--==.--=:==-==:::-=++
:####*****+++======:.. :...:::---:.=------
.=###***+++*++++--:.:::. :-=::.:..-:---:
:+**++++++*++*+=-:: .. ...... .. .:..::
Mobile & desktop command center for AI coding agents. Control agent sessions (Claude, Codex, Gemini, or any custom command) across multiple machines from your phone or browser. Sessions live in a dedicated Rust PTY broker daemon, so they survive wolfpack server restarts and redeploys. Secured by Tailscale — zero-config encrypted access, no ports to open.
Install on your phone's home screen for a native app experience — scan the QR code after setup and tap "Add to Home Screen".
┌─────────────┐ ┌───────────┐ ┌──────────────────────────────────────────┐
│ Phone / │ │ Tailscale │ │ Your Machine │
│ Browser │◄──►│ (HTTPS) │◄──►│ │
│ (PWA) │ │ mesh VPN │ │ ┌──────────┐ unix ┌──────────────┐ │
└─────────────┘ └───────────┘ │ │ wolfpack │ socket │ wolfpack- │ │
│ │ server │◄───────►│ broker │ │
│ │ (Bun) │ │ (Rust, PTY) │ │
│ │ HTTP/WS │ │ owns agents │ │
│ └──────────┘ └──────────────┘ │
└──────────────────────────────────────────┘
Components:
/api/* and the /ws/pty binary stream. Pure broker client — owns no PTYs.wolfpack-broker, a Rust daemon. Owns every PTY, keeps per-session output rings, and survives wolfpack server restarts. One Unix-domain socket per host ($XDG_RUNTIME_DIR/wolfpack-broker.sock, fallback ~/.wolfpack/broker.sock). Wire format documented in docs/broker-protocol.md.bunx wolfpack-bridge
Or with npx:
npx wolfpack-bridge
Or via shell script (no Node/Bun required):
curl -fsSL https://raw.githubusercontent.com/almogdepaz/wolfpack/main/install.sh | bash
This will download the pre-built binary for your platform, run the setup wizard, and optionally install as a login service.
Supported platforms: macOS (Apple Silicon, Intel), Linux (x64, arm64). Each platform package ships both wolfpack (the Bun binary) and wolfpack-broker (the Rust daemon).
No other runtime dependencies. The broker is bundled.
The wolfpack-broker daemon owns every PTY and runs independently of the wolfpack server. If the server crashes, gets redeployed, or restarts (e.g. launchctl kickstart), agent sessions keep running. When the server comes back up, it reconnects to the existing broker over the Unix socket and re-attaches to live sessions automatically.
The broker is started by wolfpack service install (alongside the server) and is checked by wolfpack doctor.
wolfpack # Start the server (runs setup on first launch)
wolfpack setup # Re-run the setup wizard
wolfpack ls # List active broker sessions
wolfpack kill <session> # Kill a session by name
wolfpack doctor # Diagnose broker socket, binaries, JWT, Tailscale
wolfpack migrate-plan FILE # Convert old-format plan headers to ## N. Title
wolfpack service install # Auto-start on login (launchd / systemd) — installs broker too
wolfpack service stop # Stop the background service
wolfpack service start # Start the background service
wolfpack service status # Check if running
wolfpack service uninstall # Remove the launch agent
wolfpack uninstall --yes # Remove everything (service, config, ~/.wolfpack, global command)
On first run, wolfpack walks you through:
~/Dev)18790)+ on any sidebar card to add it to the grid, × to remove. Focused cell highlighted./ws/pty connection. Per-instance isolation lets each grid cell run its own emulator.Cmd/Ctrl + ArrowUp/Down — cycle between sessionsCmd/Ctrl + ArrowLeft/Right — navigate grid cellsCmd/Ctrl + T — new session (project picker)Cmd/Ctrl + K — clear focused terminalgit shortcut, and copy/keyboard buttons.All settings (font size, haptics, enter-sends, snapshot TTL, etc.) persist in localStorage across sessions.
wolfpack setup — it auto-detects your Tailscale hostname and runs tailscale serve to expose the port over HTTPSTailscale's encrypted mesh network handles auth and routing — no ports to open, no DNS to configure.
Always use the Tailscale hostname (e.g. https://mybox.tail1234.ts.net) — not raw IPs. The QR code from setup already points to the correct URL. Raw IP access (LAN or Tailscale 100.x.x.x) bypasses Tailscale's DNS-based routing and may not be protected by CORS.
JWT authentication adds a second layer of protection. Without it, anyone who can reach the server port has full access to your sessions. To enable:
Generate a secret (minimum 32 characters):
openssl rand -base64 48
Set the environment variable before starting wolfpack:
export WOLFPACK_JWT_SECRET="your-secret-here"
For service installs, add it to your shell profile or the service environment.
Optional configuration:
WOLFPACK_JWT_AUDIENCE — expected aud claimWOLFPACK_JWT_ISSUER — expected iss claimWOLFPACK_JWT_CLOCK_TOLERANCE_SEC — clock skew tolerance (default: 30s)Tokens use HS256 (HMAC-SHA256). The server validates but does not issue tokens — generate them with any JWT library using the same secret.
Without WOLFPACK_JWT_SECRET set, authentication is disabled. This is fine for localhost-only usage but strongly recommended when the server is reachable over a network.
Autonomous task runner. Write a markdown plan file, pick an agent, set iterations, and let it rip. Ralph reads the plan, extracts the first incomplete task, hands it to the agent, marks it done, and moves on — implementing, testing, and committing along the way. See full documentation.
Stored in ~/.wolfpack/config.json (mode 0600):
{
"devDir": "/Users/you/Dev",
"port": 18790,
"tailscaleHostname": "your-machine.tailnet-name.ts.net"
}
Agent list and per-server settings stored in ~/.wolfpack/bridge-settings.json.
The broker socket lives at $XDG_RUNTIME_DIR/wolfpack-broker.sock (or ~/.wolfpack/broker.sock) and is owned by the user (filesystem permissions are the auth boundary).
Requires Bun (v1.2+) and a Rust toolchain (for building the broker).
git clone https://github.com/almogdepaz/wolfpack.git
cd wolfpack
bun install
bun run scripts/gen-assets.ts # generate embedded assets (required once)
cargo build --release --manifest-path broker/Cargo.toml # build the broker
bun run src/cli/index.ts # start the server locally
For an end-to-end local install (build + service install + restart), use scripts/deploy-local.sh.
bun test # all bun tests
bun test tests/unit/ # unit tests only
bun test tests/unit/plan-parsing.test.ts # single file
bunx playwright test # e2e (uses test-server harness)
Test layout:
tests/unit/ — pure-logic tests (plan parsing, ralph log parsing, escaping, validation, grid logic, broker codec, etc.)tests/integration/ — API routes, broker backend, ralph loop endpoints, WS dispatchtests/snapshot/ — launchd plist and systemd unit generationtests/e2e/ — Playwright end-to-end (test:e2e / test:e2e:headed scripts)The Rust broker has its own tests under broker/tests/ (cargo test from broker/).
Frontend files live in public/. The server doesn't serve from disk — everything is embedded:
public/ (HTML, TS, CSS, manifest, etc.)bun run scripts/gen-assets.ts — bundles public/app.ts and ghostty-web, then embeds every file from public/ into src/public-assets.ts (binary→base64, text→string)src/public-assets.ts manually — it's auto-generatedbun run scripts/build.ts # assets + broker + 4 platform binaries + npm pkg dirs in dist/
Compiles wolfpack for: linux-x64, linux-arm64, darwin-x64, darwin-arm64. The script also stages wolfpack-broker per platform — in CI it expects pre-built broker binaries under dist/broker/<target>/; locally it falls back to a host-arch-only cargo build --release.
mainbun test)MIT
FAQs
Mobile/browser command center for AI coding agents on your own machines
The npm package wolfpack-bridge receives a total of 76 weekly downloads. As such, wolfpack-bridge popularity was classified as not popular.
We found that wolfpack-bridge demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PolinRider expands across npm, Packagist, Go modules, and Chrome extensions, using hidden loaders to target developer environments.
Security News
Open source attacks are accelerating as AI coding agents pull in dependencies faster, with less human review.
Research
/Security News
Malicious Chrome and Firefox extensions posed as free VPNs while stealing clipboard data through later extension updates.