pairpod 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 solidquant
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,131 @@
+# pairpod
+
+Run terminals and Claude Code sessions from your phone, through a Telegram bot.
+
+Point pairpod at a backend (a Docker container, an SSH host, or the machine the bot runs on) and it gives you a real terminal inside a Telegram mini app. Start a plain shell or a Claude Code session, attach from anywhere, scroll, copy, pinch to zoom. It's xterm over a WebSocket, so it behaves the way you'd expect.
+
+## Concepts
+
+A **pod** is a backend. A **session** is a terminal running on it.
+
+Pods come in three kinds:
+
+| | |
+|---|---|
+| 🐳 Docker | a throwaway, isolated container on the bot host |
+| 🔌 SSH | a remote machine reached over SSH |
+| 💻 Host | a shell on the bot machine itself |
+
+Sessions come in three modes:
+
+| | |
+|---|---|
+| terminal | a plain shell |
+| regular | `claude` — you answer the permission prompts |
+| skip-perms | `claude --dangerously-skip-permissions` |
+
+Docker and SSH pods run all three modes; Host pods are terminal-only. You can name pods and sessions, which keeps a list of `pod-7` / `claude-3` readable once you have a few.
+
+## Quick start
+
+You'll need Node 22, pnpm, and [cloudflared](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/) (`brew install cloudflared`). Docker is optional; only Docker pods touch it.
+
+```bash
+nvm use
+pnpm install
+pnpm onboard     # asks for a bot token, allowed users, and a port
+pnpm start       # opens the tunnel and starts the bot together
+```
+
+`onboard` points you at [@BotFather](https://t.me/BotFather) to create a bot, then writes everything to `~/.pairpod/.env` and generates a vault key for you. `start` brings up a cloudflared tunnel, points the bot at its URL, and runs both. One command, and Ctrl-C stops everything.
+
+Then message your bot `/pods`, create one, and tap ▶ to open a terminal.
+
+## Where state lives
+
+Everything host-specific sits under `~/.pairpod/` (set `PAIRPOD_HOME` to move it):
+
+```
+~/.pairpod/
+  .env                config
+  pairpod.db          pods and sessions
+  vault/              encrypted SSH credentials
+  workspaces/         Docker pod working dirs
+  notify-chats.json   who gets permission pings
+```
+
+Nothing gets written into the repo.
+
+## Layout
+
+```
+packages/
+  bot/    the Fastify server, grammy bot, and the mini app
+  cli/    the `pairpod` command
+docker/   the image Docker pods run
+```
+
+It's a pnpm workspace. `packages/bot` is the whole app: the server, the bot, the pod/session store, the Docker/SSH/PTY backends, and the vault. `packages/cli` is the small `pairpod` command that onboards and launches it.
+
+## Commands
+
+In Telegram:
+
+- `/pods` — your pods; create, rename, delete, open sessions
+- `/sessions` — every session with an open button
+- `/ssh` — add, test, edit, or remove SSH hosts
+- `/whoami` — your id and username, for locking down the allowlist
+
+On the command line (`pairpod <cmd>` once installed, or `pnpm <cmd>` in the repo):
+
+- `onboard` — write `~/.pairpod/.env`
+- `start` — tunnel plus bot
+- `start --no-tunnel` — bot only, using a `MINIAPP_URL` you set yourself
+- `dev` — hot-reload the bot, no tunnel (for development)
+- `build` — compile both packages to `dist/`
+
+## SSH hosts
+
+Add one from `/ssh` → Add SSH endpoint, or while creating a pod. The form opens in the mini app, so the secret travels over HTTPS rather than through a chat message. Three ways to authenticate:
+
+| Method | What's stored | Use it when |
+|---|---|---|
+| ssh-agent | nothing | the key's already loaded in your agent on the bot host; best for passphrase-protected keys |
+| key file | just the path | the key file lives on the bot host and never leaves it |
+| paste key | the key, encrypted | there's no file on the host; needs the vault |
+
+Anything you paste (a key, a passphrase) is encrypted with AES-256-GCM. The master key comes from `PAIRPOD_VAULT_KEY` and only lives in memory, never on disk beside the ciphertext and never in the database. `onboard` generates it.
+
+Running Claude on an SSH host needs `claude` installed and logged in over there (open a terminal session and run it once), plus a reachable `MINIAPP_URL`/`PAIRPOD_PUBLIC_URL` so permission prompts can notify you. The first connection to a host pins its key fingerprint and verifies it every time after.
+
+## Worth knowing
+
+A cloudflared quick tunnel terminates TLS at Cloudflare's edge, so a pasted key or passphrase is briefly in the clear there. If that bothers you, use ssh-agent (nothing leaves the host) or a fixed named tunnel.
+
+Docker pods are isolated. SSH pods are a separate machine. A Host pod, though, is an un-sandboxed shell on the bot machine (vault key in memory included), so only enable it somewhere you're comfortable handing out that access. Either way the bot only answers people on your allowlist, and the mini app checks Telegram's signed `initData` on every connection.
+
+## Config keys
+
+Most people never touch these directly; `onboard` writes the ones that matter. Full list in `.env.example`.
+
+| Key | What it does |
+|---|---|
+| `TELEGRAM_BOT_TOKEN` | the bot token |
+| `TELEGRAM_ALLOWED_USERNAMES` / `..._USER_IDS` | who's allowed in (empty means anyone) |
+| `PORT` | server port (default 40002) |
+| `MINIAPP_URL` | public origin for the mini app; `start` fills this from the tunnel |
+| `PAIRPOD_PUBLIC_URL` | where SSH Claude sessions send notifications; defaults to `MINIAPP_URL` |
+| `PAIRPOD_VAULT_KEY` | vault master key |
+| `PAIRPOD_HOME` | where state lives (default `~/.pairpod`) |
+
+## Troubleshooting
+
+- `ERR_DLOPEN_FAILED` or a `NODE_MODULE_VERSION` mismatch means you're not on Node 22. Run `nvm use`.
+- `posix_spawnp failed` on a Host session is node-pty's helper losing its execute bit. `pnpm install` re-fixes it (a postinstall handles it).
+- If the mini app looks stale after an update, Telegram has cached it. Fully close and reopen the web app.
+- `could not run cloudflared`: install it, or run `pairpod start --no-tunnel` with your own URL.
+- Old "Open" buttons that 404: Telegram bakes the URL into a message when it's sent, so after a new tunnel URL just re-run `/pods` to get fresh buttons.
+
+## License
+
+MIT

package/dist/env.js

@@ -0,0 +1,37 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+export const PAIRPOD_HOME = process.env.PAIRPOD_HOME
+    ? path.resolve(process.env.PAIRPOD_HOME)
+    : path.join(os.homedir(), ".pairpod");
+export const ENV_PATH = path.join(PAIRPOD_HOME, ".env");
+export function readEnv() {
+    const out = {};
+    let text = "";
+    try {
+        text = fs.readFileSync(ENV_PATH, "utf8");
+    }
+    catch {
+        return out;
+    }
+    for (const line of text.split("\n")) {
+        const t = line.trim();
+        if (!t || t.startsWith("#"))
+            continue;
+        const eq = t.indexOf("=");
+        if (eq === -1)
+            continue;
+        out[t.slice(0, eq).trim()] = t.slice(eq + 1).trim();
+    }
+    return out;
+}
+// Write the given keys, preserving any other existing ones. Empty values are dropped.
+export function writeEnv(vars) {
+    fs.mkdirSync(PAIRPOD_HOME, { recursive: true });
+    const merged = { ...readEnv(), ...vars };
+    const body = Object.entries(merged)
+        .filter(([, v]) => v !== undefined && v !== "")
+        .map(([k, v]) => `${k}=${v}`)
+        .join("\n");
+    fs.writeFileSync(ENV_PATH, body + "\n", { mode: 0o600 });
+}

package/dist/index.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+import { onboard } from "./onboard.js";
+import { start } from "./start.js";
+const HELP = `pairpod — run terminals & Claude sessions from Telegram
+
+Usage:
+  pairpod onboard              Configure the bot (token, allowlist, port, vault key)
+  pairpod start                Start the tunnel + bot (one command)
+  pairpod start --no-tunnel    Start the bot only (use the existing MINIAPP_URL)
+
+Config lives in ~/.pairpod/ (override with PAIRPOD_HOME).`;
+async function main() {
+    const [cmd, ...rest] = process.argv.slice(2);
+    switch (cmd) {
+        case "onboard":
+            await onboard();
+            break;
+        case "start":
+            await start(!rest.includes("--no-tunnel"));
+            break;
+        case undefined:
+        case "help":
+        case "--help":
+        case "-h":
+            console.log(HELP);
+            break;
+        default:
+            console.error(`Unknown command: ${cmd}\n\n${HELP}`);
+            process.exit(1);
+    }
+}
+main();

package/dist/onboard.js

@@ -0,0 +1,45 @@
+import crypto from "node:crypto";
+import * as p from "@clack/prompts";
+import { readEnv, writeEnv, ENV_PATH } from "./env.js";
+function cancelled(v) {
+    if (p.isCancel(v)) {
+        p.cancel("Onboarding aborted.");
+        process.exit(0);
+    }
+}
+export async function onboard() {
+    p.intro("pairpod onboard");
+    const existing = readEnv();
+    p.note("1. Open @BotFather in Telegram (https://t.me/BotFather)\n2. Send /newbot and follow the prompts\n3. Copy the token it gives you", "Create a Telegram bot");
+    const token = await p.password({
+        message: "Telegram bot token",
+        validate: (v) => (v && v.includes(":") ? undefined : "Looks off — should look like 123456:AA..."),
+    });
+    cancelled(token);
+    const usernames = await p.text({
+        message: "Allowed Telegram @usernames (comma-separated; blank = anyone)",
+        placeholder: "alice,bob",
+        initialValue: existing.TELEGRAM_ALLOWED_USERNAMES ?? "",
+        defaultValue: "",
+    });
+    cancelled(usernames);
+    const port = await p.text({
+        message: "Port for the bot/mini-app server",
+        initialValue: existing.PORT ?? "40002",
+        validate: (v) => (/^\d+$/.test(v) ? undefined : "Must be a number"),
+    });
+    cancelled(port);
+    const hadKey = Boolean(existing.PAIRPOD_VAULT_KEY);
+    const vaultKey = existing.PAIRPOD_VAULT_KEY || crypto.randomBytes(32).toString("base64");
+    const s = p.spinner();
+    s.start("Writing config");
+    writeEnv({
+        TELEGRAM_BOT_TOKEN: token,
+        TELEGRAM_ALLOWED_USERNAMES: usernames.trim(),
+        PORT: port,
+        PAIRPOD_VAULT_KEY: vaultKey,
+    });
+    s.stop(`Wrote ${ENV_PATH}`);
+    p.note(`${hadKey ? "Kept existing" : "Generated a new"} vault key (AES-256-GCM, stored in your .env).`, "Credential vault");
+    p.outro("Done. Start it with:  pairpod start");
+}

package/dist/start.js

@@ -0,0 +1,95 @@
+import { spawn } from "node:child_process";
+import { createRequire } from "node:module";
+import fs from "node:fs";
+import path from "node:path";
+import { readEnv } from "./env.js";
+const require = createRequire(import.meta.url);
+function resolveBotEntry() {
+    const botDir = path.dirname(require.resolve("pairpod-bot/package.json"));
+    const distMain = path.join(botDir, "dist", "main.js");
+    if (fs.existsSync(distMain))
+        return { cmd: process.execPath, args: [distMain] };
+    return { cmd: "npx", args: ["tsx", path.join(botDir, "src", "main.ts")] };
+}
+function startTunnel(port) {
+    return new Promise((resolve, reject) => {
+        const cf = spawn("cloudflared", ["tunnel", "--url", `http://localhost:${port}`], {
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let done = false;
+        const scan = (buf) => {
+            const m = String(buf).match(/https:\/\/[a-zA-Z0-9.-]+\.trycloudflare\.com/);
+            if (m && !done) {
+                done = true;
+                resolve({ url: m[0], child: cf });
+            }
+        };
+        cf.stdout?.on("data", scan);
+        cf.stderr?.on("data", scan);
+        cf.on("error", (e) => {
+            if (!done) {
+                done = true;
+                reject(new Error(`could not run cloudflared (${e.message}). Install it: brew install cloudflared`));
+            }
+        });
+        cf.on("exit", (code) => {
+            if (!done) {
+                done = true;
+                reject(new Error(`cloudflared exited (code ${code}) before producing a URL`));
+            }
+        });
+        setTimeout(() => {
+            if (!done) {
+                done = true;
+                reject(new Error("timed out waiting for the tunnel URL"));
+            }
+        }, 30000);
+    });
+}
+export async function start(useTunnel) {
+    const env = { ...process.env, ...readEnv() };
+    if (!env.TELEGRAM_BOT_TOKEN) {
+        console.error("Not configured yet. Run:  pairpod onboard");
+        process.exit(1);
+    }
+    const port = env.PORT || "40002";
+    const children = [];
+    let shuttingDown = false;
+    const shutdown = () => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        for (const c of children) {
+            try {
+                c.kill();
+            }
+            catch { }
+        }
+        process.exit(0);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+    if (useTunnel) {
+        process.stdout.write("Starting tunnel… ");
+        try {
+            const { url, child } = await startTunnel(port);
+            children.push(child);
+            env.MINIAPP_URL = url;
+            console.log(url);
+        }
+        catch (e) {
+            console.log("failed");
+            console.error(`  ${e.message}`);
+            console.error("  Continuing without a tunnel — mini-app buttons will be disabled.");
+        }
+    }
+    const entry = resolveBotEntry();
+    const bot = spawn(entry.cmd, entry.args, { env, stdio: "inherit" });
+    children.push(bot);
+    bot.on("exit", (code) => {
+        if (!shuttingDown) {
+            console.error(`bot exited (code ${code ?? "?"})`);
+            shutdown();
+        }
+    });
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "pairpod",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "MIT",
+  "description": "Run terminals and Claude Code sessions from your phone via a Telegram bot, on Docker, SSH, or host backends.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/solidquant/pairpod.git",
+    "directory": "packages/cli"
+  },
+  "keywords": [
+    "telegram-bot",
+    "claude-code",
+    "claude",
+    "terminal",
+    "web-terminal",
+    "ssh",
+    "docker",
+    "tmux",
+    "pty",
+    "mobile",
+    "self-hosted",
+    "cli"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "pairpod": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@clack/prompts": "^0.7.0",
+    "pairpod-bot": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0"
+  },
+  "scripts": {}
+}