wolfpack-tailnet-control

name	wolfpack-tailnet-control
description	Use when an agent needs to find, inspect, or take control of Wolfpack terminal sessions on machines reachable through the same Tailscale tailnet.
metadata	{"author":"almogdepaz"}

Wolfpack Tailnet Session Control

Use this when you need to look up or control Wolfpack sessions on this machine or another machine in the same tailnet.

Trust and safety

• Treat every Wolfpack session as a live user terminal. Read before writing.
• Prefer the Wolfpack web UI for interactive control. Only use the low-level WebSocket protocol when automation is explicitly needed.
• Do not kill, take over, or send input to a session unless the user asked for that exact action.
• Tailscale is the primary network boundary. If the server has JWT auth enabled, include Authorization: Bearer <token> on HTTP requests. For browser-style WebSocket clients that cannot set headers, append ?token=<jwt> alongside session.

Find Wolfpack hosts

Local config usually tells you the current host and port:

jq -r '.tailscaleHostname // empty, .port // 18790' ~/.wolfpack/config.json

Discover other Wolfpack servers from any running Wolfpack host:

BASE="https://$(jq -r '.tailscaleHostname' ~/.wolfpack/config.json)"
curl -fsS "$BASE/api/discover" | jq .

Each peer has a url like https://machine.tailnet.ts.net. Use that URL as BASE for the commands below.

List and inspect sessions

List sessions:

curl -fsS "$BASE/api/sessions" | jq .

Read the terminal pane for one session:

SESSION="my-session"
curl -fsS "$BASE/api/poll?session=$(python3 -c 'import urllib.parse,sys; print(urllib.parse.quote(sys.argv[1]))' "$SESSION")" | jq -r .pane

Fetch plain text for copy/debugging:

curl -fsS "$BASE/api/copy-text?session=$(python3 -c 'import urllib.parse,sys; print(urllib.parse.quote(sys.argv[1]))' "$SESSION")"

Check a session repo's git status:

curl -fsS "$BASE/api/git-status?session=$(python3 -c 'import urllib.parse,sys; print(urllib.parse.quote(sys.argv[1]))' "$SESSION")" | jq -r .status

Create or kill sessions

Create a session in an existing project under the host's configured devDir:

curl -fsS "$BASE/api/create" \
  -H 'Content-Type: application/json' \
  -d '{"project":"repo-name","cmd":"claude","sessionName":"repo-name-claude"}' | jq .

Kill only when explicitly requested:

curl -fsS "$BASE/api/kill" \
  -H 'Content-Type: application/json' \
  -d "$(jq -nc --arg session "$SESSION" '{session:$session}')" | jq .

Interactive control

Recommended path: open the Wolfpack UI at $BASE, choose the machine/session, then use the terminal. If another viewer owns the PTY, Wolfpack shows a take-control flow; confirm only if the user asked you to take over.

Low-level protocol for automation:

1. Connect to wss://host/ws/pty?session=<name>; if JWT auth is enabled and you cannot set headers, use wss://host/ws/pty?session=<name>&token=<jwt>.
2. Send JSON attach first: {"type":"attach","cols":120,"rows":40,"prefillMode":"full"}.
3. If the server replies viewer_conflict, do not take over unless requested. To take over, either send {"type":"take_control"} after attach, or reconnect and include "takeControl":true in the attach message.
4. Terminal output arrives as binary frames. Terminal input must be sent as binary UTF-8 bytes.
5. Resize with {"type":"resize","cols":120,"rows":40}.

Minimal Bun example:

const base = process.env.BASE!; // e.g. https://machine.tailnet.ts.net
const session = process.env.SESSION!;
const wsUrl = base.replace(/^http/, "ws") + "/ws/pty?session=" + encodeURIComponent(session);
const ws = new WebSocket(wsUrl);

ws.binaryType = "arraybuffer";
ws.addEventListener("open", () => {
  ws.send(JSON.stringify({ type: "attach", cols: 120, rows: 40, prefillMode: "full" }));
});
ws.addEventListener("message", (event) => {
  if (typeof event.data === "string") console.error("control", event.data);
  else process.stdout.write(Buffer.from(event.data));
});

// after attach, send one command and enter:
setTimeout( ws.(.(, )), );

Notify the user

A session can send a Wolfpack push notification through the local host:

curl -fsS http://localhost:18790/api/notify \
  -H 'Content-Type: application/json' \
  -d '{"message":"agent needs input"}'

---

Source: almogdepaz/wolfpack — distributed by TomeVault.