@tyevco/homelab-lxc-agent 1.0.0

package/bin/homelab-lxc-agent.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+require("../dist/index.js");

package/dist/index.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const server_1 = require("./server");
+// eslint-disable-next-line @typescript-eslint/no-var-requires
+const pkg = require("../package.json");
+const port = parseInt(process.env.HOMELAB_AGENT_PORT ?? "5002", 10);
+const hostname = process.env.HOMELAB_AGENT_HOSTNAME ?? "0.0.0.0";
+const username = process.env.HOMELAB_AGENT_USERNAME ?? "admin";
+const password = process.env.HOMELAB_AGENT_PASSWORD ?? "";
+if (!password) {
+    console.error("Error: HOMELAB_AGENT_PASSWORD is required.");
+    console.error("");
+    console.error("Set it via environment variable:");
+    console.error("  HOMELAB_AGENT_PASSWORD=secret homelab-lxc-agent");
+    console.error("");
+    console.error("Optional variables:");
+    console.error("  HOMELAB_AGENT_PORT      (default: 5002)");
+    console.error("  HOMELAB_AGENT_HOSTNAME  (default: 0.0.0.0)");
+    console.error("  HOMELAB_AGENT_USERNAME  (default: admin)");
+    process.exit(1);
+}
+const { httpServer } = (0, server_1.createAgentServer)({ username,
+    password,
+    version: pkg.version });
+httpServer.listen(port, hostname, () => {
+    console.log(`Homelab LXC Agent v${pkg.version}`);
+    console.log(`Listening on ${hostname}:${port}`);
+    console.log(`Username: ${username}`);
+    console.log("");
+    console.log("Add this agent in the Homelab UI:");
+    console.log(`  URL: http://<this-host>:${port}`);
+    console.log(`  Username: ${username}`);
+});

package/dist/lxc.js

@@ -0,0 +1,288 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.joinExecTerminal = exports.getDistributions = exports.createContainer = exports.saveConfig = exports.deleteContainer = exports.unfreezeContainer = exports.freezeContainer = exports.restartContainer = exports.stopContainer = exports.startContainer = exports.getContainer = exports.getContainerList = exports.STACK_TYPE_LXC = exports.FROZEN = exports.EXITED = exports.RUNNING = exports.UNKNOWN = void 0;
+const promisify_child_process_1 = require("promisify-child-process");
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const terminal_1 = require("./terminal");
+const LXC_PATH = "/var/lib/lxc";
+exports.UNKNOWN = 0;
+exports.RUNNING = 3;
+exports.EXITED = 4;
+exports.FROZEN = 5;
+exports.STACK_TYPE_LXC = "lxc";
+function getLxcTerminalName(endpoint, name) {
+    return `lxc-${endpoint}-${name}`;
+}
+function getLxcExecTerminalName(endpoint, name, index) {
+    return `lxc-exec-${endpoint}-${name}-${index}`;
+}
+function statusConvert(state) {
+    switch (state.toUpperCase().trim()) {
+        case "RUNNING": return exports.RUNNING;
+        case "STOPPED": return exports.EXITED;
+        case "FROZEN": return exports.FROZEN;
+        default: return exports.UNKNOWN;
+    }
+}
+function parseLxcLsOutput(stdout) {
+    const lines = stdout.trim().split("\n");
+    if (lines.length < 2) {
+        return [];
+    }
+    const headerLine = lines[0];
+    const headers = [];
+    const positions = [];
+    const headerMatch = headerLine.match(/\S+/g);
+    if (!headerMatch) {
+        return [];
+    }
+    for (const header of headerMatch) {
+        const searchFrom = positions.length > 0
+            ? positions[positions.length - 1] + headers[headers.length - 1].length
+            : 0;
+        const idx = headerLine.indexOf(header, searchFrom);
+        headers.push(header.toLowerCase());
+        positions.push(idx);
+    }
+    const results = [];
+    for (let i = 1; i < lines.length; i++) {
+        const line = lines[i];
+        if (!line.trim() || line.startsWith("-")) {
+            continue;
+        }
+        const row = {};
+        for (let j = 0; j < headers.length; j++) {
+            const start = positions[j];
+            const end = j + 1 < positions.length ? positions[j + 1] : line.length;
+            row[headers[j]] = line.substring(start, end).trim();
+        }
+        results.push(row);
+    }
+    return results;
+}
+function readConfig(name) {
+    try {
+        return fs.readFileSync(path.join(LXC_PATH, name, "config"), "utf-8");
+    }
+    catch {
+        return "";
+    }
+}
+async function getContainerList(endpoint) {
+    const result = {};
+    try {
+        const res = await (0, promisify_child_process_1.spawn)("lxc-ls", ["-f", "-F", "name,state"], { encoding: "utf-8" });
+        if (!res.stdout) {
+            return result;
+        }
+        const rows = parseLxcLsOutput(res.stdout.toString());
+        for (const row of rows) {
+            const name = row["name"];
+            if (!name) {
+                continue;
+            }
+            result[name] = {
+                name,
+                status: statusConvert(row["state"] || ""),
+                type: exports.STACK_TYPE_LXC,
+                tags: [],
+                endpoint,
+                isManagedByHomelab: true,
+            };
+        }
+    }
+    catch (e) {
+        console.error("[lxc] Failed to get container list:", e instanceof Error ? e.message : e);
+    }
+    return result;
+}
+exports.getContainerList = getContainerList;
+async function getContainer(name, endpoint) {
+    if (!/^[a-z0-9_.-]+$/.test(name)) {
+        throw new Error("Invalid LXC container name");
+    }
+    const res = await (0, promisify_child_process_1.spawn)("lxc-info", ["-n", name], { encoding: "utf-8" });
+    if (!res.stdout) {
+        throw new Error("LXC container not found");
+    }
+    const output = res.stdout.toString();
+    let status = exports.UNKNOWN;
+    let ip = "";
+    let pid = 0;
+    let memory = "";
+    const stateMatch = output.match(/^State:\s+(.+)$/m);
+    if (stateMatch) {
+        status = statusConvert(stateMatch[1]);
+    }
+    const ipMatch = output.match(/^IP:\s+(.+)$/m);
+    if (ipMatch) {
+        ip = ipMatch[1].trim();
+    }
+    const pidMatch = output.match(/^PID:\s+(.+)$/m);
+    if (pidMatch) {
+        pid = parseInt(pidMatch[1].trim(), 10) || 0;
+    }
+    const memMatch = output.match(/^Memory use:\s+(.+)$/m);
+    if (memMatch) {
+        memory = memMatch[1].trim();
+    }
+    return {
+        name,
+        status,
+        type: exports.STACK_TYPE_LXC,
+        tags: [],
+        endpoint,
+        ip,
+        autostart: false,
+        pid,
+        memory,
+        config: readConfig(name),
+        isManagedByHomelab: true,
+    };
+}
+exports.getContainer = getContainer;
+async function startContainer(socket, endpoint, name) {
+    const code = await terminal_1.AgentTerminal.exec(socket, getLxcTerminalName(endpoint, name), "lxc-start", ["-n", name], LXC_PATH);
+    if (code !== 0) {
+        throw new Error("Failed to start LXC container");
+    }
+}
+exports.startContainer = startContainer;
+async function stopContainer(socket, endpoint, name) {
+    const code = await terminal_1.AgentTerminal.exec(socket, getLxcTerminalName(endpoint, name), "lxc-stop", ["-n", name], LXC_PATH);
+    if (code !== 0) {
+        throw new Error("Failed to stop LXC container");
+    }
+}
+exports.stopContainer = stopContainer;
+async function restartContainer(socket, endpoint, name) {
+    const termName = getLxcTerminalName(endpoint, name);
+    const stopCode = await terminal_1.AgentTerminal.exec(socket, termName, "lxc-stop", ["-n", name], LXC_PATH);
+    if (stopCode !== 0) {
+        throw new Error("Failed to stop LXC container for restart");
+    }
+    const startCode = await terminal_1.AgentTerminal.exec(socket, termName, "lxc-start", ["-n", name], LXC_PATH);
+    if (startCode !== 0) {
+        throw new Error("Failed to start LXC container for restart");
+    }
+}
+exports.restartContainer = restartContainer;
+async function freezeContainer(socket, endpoint, name) {
+    const code = await terminal_1.AgentTerminal.exec(socket, getLxcTerminalName(endpoint, name), "lxc-freeze", ["-n", name], LXC_PATH);
+    if (code !== 0) {
+        throw new Error("Failed to freeze LXC container");
+    }
+}
+exports.freezeContainer = freezeContainer;
+async function unfreezeContainer(socket, endpoint, name) {
+    const code = await terminal_1.AgentTerminal.exec(socket, getLxcTerminalName(endpoint, name), "lxc-unfreeze", ["-n", name], LXC_PATH);
+    if (code !== 0) {
+        throw new Error("Failed to unfreeze LXC container");
+    }
+}
+exports.unfreezeContainer = unfreezeContainer;
+async function deleteContainer(socket, endpoint, name, status) {
+    const termName = getLxcTerminalName(endpoint, name);
+    if (status === exports.RUNNING || status === exports.FROZEN) {
+        await terminal_1.AgentTerminal.exec(socket, termName, "lxc-stop", ["-n", name], LXC_PATH);
+    }
+    const code = await terminal_1.AgentTerminal.exec(socket, termName, "lxc-destroy", ["-n", name], LXC_PATH);
+    if (code !== 0) {
+        throw new Error("Failed to destroy LXC container");
+    }
+}
+exports.deleteContainer = deleteContainer;
+async function saveConfig(name, config) {
+    const containerPath = path.join(LXC_PATH, name);
+    if (!fs.existsSync(containerPath)) {
+        throw new Error("LXC container not found");
+    }
+    await fs.promises.writeFile(path.join(containerPath, "config"), config);
+}
+exports.saveConfig = saveConfig;
+async function createContainer(socket, endpoint, name, dist, release, arch) {
+    if (!/^[a-z0-9_.-]+$/.test(name)) {
+        throw new Error("Invalid container name");
+    }
+    if (!/^[a-zA-Z0-9_.-]+$/.test(dist)) {
+        throw new Error("Invalid distribution name");
+    }
+    if (!/^[a-zA-Z0-9_.-]+$/.test(release)) {
+        throw new Error("Invalid release name");
+    }
+    if (!/^[a-zA-Z0-9_]+$/.test(arch)) {
+        throw new Error("Invalid architecture");
+    }
+    const code = await terminal_1.AgentTerminal.exec(socket, getLxcTerminalName(endpoint, name), "lxc-create", ["-n", name, "-t", "download", "--", "--dist", dist, "--release", release, "--arch", arch], LXC_PATH);
+    if (code !== 0) {
+        throw new Error("Failed to create LXC container");
+    }
+}
+exports.createContainer = createContainer;
+async function getDistributions() {
+    const distributions = [];
+    try {
+        const res = await (0, promisify_child_process_1.spawn)("lxc-create", ["-t", "download", "--", "--list"], {
+            encoding: "utf-8",
+            timeout: 30000,
+        });
+        if (!res.stdout) {
+            return distributions;
+        }
+        const lines = res.stdout.toString().trim().split("\n");
+        for (const line of lines) {
+            const parts = line.trim().split(/\s+/);
+            if (parts.length >= 3 && parts[0] !== "DIST" && !line.startsWith("-")) {
+                distributions.push({
+                    dist: parts[0],
+                    release: parts[1],
+                    arch: parts[2],
+                    variant: parts[3] || "default",
+                });
+            }
+        }
+    }
+    catch (e) {
+        console.error("[lxc] Failed to get distributions:", e instanceof Error ? e.message : e);
+    }
+    return distributions;
+}
+exports.getDistributions = getDistributions;
+function joinExecTerminal(socket, endpoint, name, shell) {
+    const terminalName = getLxcExecTerminalName(endpoint, name, 0);
+    let terminal = terminal_1.AgentTerminal.getTerminal(terminalName);
+    if (!terminal) {
+        terminal = new terminal_1.AgentTerminal(socket, terminalName, "lxc-attach", ["-n", name, "--", shell], LXC_PATH);
+        terminal.rows = terminal_1.TERMINAL_ROWS;
+    }
+    else {
+        // Update socket reference so output goes to the current connection
+        terminal.socket = socket;
+    }
+    terminal.start();
+}
+exports.joinExecTerminal = joinExecTerminal;

package/dist/server.js

@@ -0,0 +1,270 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAgentServer = void 0;
+const http_1 = require("http");
+const socket_io_1 = require("socket.io");
+const lxc = __importStar(require("./lxc"));
+const terminal_1 = require("./terminal");
+function createAgentServer(config) {
+    const httpServer = (0, http_1.createServer)();
+    const io = new socket_io_1.Server(httpServer);
+    io.on("connection", (socket) => {
+        // The main server sends its own endpoint string in the header so we can
+        // echo it back in push events (lxcContainerList, terminalWrite, etc.)
+        const endpoint = socket.handshake.headers["endpoint"] || "";
+        let loggedIn = false;
+        console.log(`[agent] Main server connected (endpoint: ${endpoint || "<none>"})`);
+        // Announce ourselves — main server checks version >= 1.4.0
+        socket.emit("info", {
+            version: config.version,
+            lxcAvailable: true,
+        });
+        socket.on("disconnect", () => {
+            console.log("[agent] Main server disconnected");
+            // Leave interactive terminals open (lxc-attach) across reconnects;
+            // only clean up non-interactive progress terminals which are already
+            // gone by the time the process exits.
+        });
+        socket.on("login", (data, callback) => {
+            const cb = typeof callback === "function" ? callback : null;
+            if (typeof data !== "object" || data === null) {
+                cb?.({ ok: false,
+                    msg: "Invalid login data" });
+                return;
+            }
+            const { username, password } = data;
+            if (username === config.username && password === config.password) {
+                loggedIn = true;
+                console.log(`[agent] Authenticated as ${username}`);
+                cb?.({ ok: true });
+            }
+            else {
+                console.warn(`[agent] Login failed for ${username}`);
+                cb?.({ ok: false,
+                    msg: "Invalid credentials" });
+            }
+        });
+        // The main server proxies browser requests as:
+        //   socket.emit("agent", targetEndpoint, eventName, ...args)
+        socket.on("agent", async (targetEndpoint, eventName, ...args) => {
+            if (!loggedIn) {
+                return;
+            }
+            if (typeof targetEndpoint !== "string" || typeof eventName !== "string") {
+                return;
+            }
+            // Only handle events addressed to this endpoint (or broadcast)
+            if (targetEndpoint !== endpoint && targetEndpoint !== "") {
+                return;
+            }
+            await dispatch(socket, endpoint, eventName, args);
+        });
+    });
+    return { io,
+        httpServer };
+}
+exports.createAgentServer = createAgentServer;
+async function dispatch(socket, endpoint, eventName, args) {
+    // Pop ack callback if the last argument is a function
+    const callback = typeof args[args.length - 1] === "function"
+        ? args.pop()
+        : null;
+    const ok = (msg, extra) => callback?.({ ok: true,
+        ...(msg ? { msg,
+            msgi18n: true } : {}),
+        ...extra });
+    const fail = (e) => callback?.({ ok: false,
+        msg: e instanceof Error ? e.message : String(e) });
+    const pushList = async () => {
+        const list = await lxc.getContainerList(endpoint);
+        socket.emit("agent", "lxcContainerList", { ok: true,
+            lxcContainerList: list,
+            endpoint });
+    };
+    try {
+        switch (eventName) {
+            case "requestLxcContainerList": {
+                await pushList();
+                ok("Updated");
+                break;
+            }
+            case "getLxcContainer": {
+                const [name] = args;
+                if (typeof name !== "string") {
+                    throw new Error("Name must be a string");
+                }
+                const container = await lxc.getContainer(name, endpoint);
+                callback?.({ ok: true,
+                    container });
+                break;
+            }
+            case "startLxcContainer": {
+                const [name] = args;
+                if (typeof name !== "string") {
+                    throw new Error("Name must be a string");
+                }
+                await lxc.startContainer(socket, endpoint, name);
+                ok("Started");
+                await pushList();
+                break;
+            }
+            case "stopLxcContainer": {
+                const [name] = args;
+                if (typeof name !== "string") {
+                    throw new Error("Name must be a string");
+                }
+                await lxc.stopContainer(socket, endpoint, name);
+                ok("Stopped");
+                await pushList();
+                break;
+            }
+            case "restartLxcContainer": {
+                const [name] = args;
+                if (typeof name !== "string") {
+                    throw new Error("Name must be a string");
+                }
+                await lxc.restartContainer(socket, endpoint, name);
+                ok("Restarted");
+                await pushList();
+                break;
+            }
+            case "freezeLxcContainer": {
+                const [name] = args;
+                if (typeof name !== "string") {
+                    throw new Error("Name must be a string");
+                }
+                await lxc.freezeContainer(socket, endpoint, name);
+                ok("Frozen");
+                await pushList();
+                break;
+            }
+            case "unfreezeLxcContainer": {
+                const [name] = args;
+                if (typeof name !== "string") {
+                    throw new Error("Name must be a string");
+                }
+                await lxc.unfreezeContainer(socket, endpoint, name);
+                ok("Unfrozen");
+                await pushList();
+                break;
+            }
+            case "deleteLxcContainer": {
+                const [name] = args;
+                if (typeof name !== "string") {
+                    throw new Error("Name must be a string");
+                }
+                const container = await lxc.getContainer(name, endpoint);
+                await lxc.deleteContainer(socket, endpoint, name, container.status);
+                await pushList();
+                ok("Destroyed");
+                break;
+            }
+            case "saveLxcConfig": {
+                const [name, configContent] = args;
+                if (typeof name !== "string") {
+                    throw new Error("Name must be a string");
+                }
+                if (typeof configContent !== "string") {
+                    throw new Error("Config must be a string");
+                }
+                await lxc.saveConfig(name, configContent);
+                ok("Saved");
+                break;
+            }
+            case "createLxcContainer": {
+                const [name, dist, release, arch] = args;
+                await lxc.createContainer(socket, endpoint, name, dist, release, arch);
+                await pushList();
+                ok("Created");
+                break;
+            }
+            case "getLxcDistributions": {
+                const distributions = await lxc.getDistributions();
+                callback?.({ ok: true,
+                    distributions });
+                break;
+            }
+            case "lxcExecTerminal": {
+                const [name, shell] = args;
+                if (typeof name !== "string") {
+                    throw new Error("Name must be a string");
+                }
+                if (typeof shell !== "string") {
+                    throw new Error("Shell must be a string");
+                }
+                lxc.joinExecTerminal(socket, endpoint, name, shell);
+                ok();
+                break;
+            }
+            case "terminalInput": {
+                const [terminalName, cmd] = args;
+                if (typeof terminalName !== "string") {
+                    throw new Error("Terminal name must be a string");
+                }
+                if (typeof cmd !== "string") {
+                    throw new Error("Command must be a string");
+                }
+                const terminal = terminal_1.AgentTerminal.getTerminal(terminalName);
+                if (!terminal) {
+                    throw new Error("Terminal not found");
+                }
+                terminal.write(cmd);
+                break;
+            }
+            case "terminalJoin": {
+                const [terminalName] = args;
+                if (typeof terminalName !== "string") {
+                    throw new Error("Terminal name must be a string");
+                }
+                const buffer = terminal_1.AgentTerminal.getTerminal(terminalName)?.getBuffer() ?? "";
+                callback?.({ ok: true,
+                    buffer });
+                break;
+            }
+            case "terminalResize": {
+                const [terminalName, rows, cols] = args;
+                if (typeof terminalName !== "string") {
+                    break;
+                }
+                const terminal = terminal_1.AgentTerminal.getTerminal(terminalName);
+                if (terminal) {
+                    if (typeof rows === "number") {
+                        terminal.rows = rows;
+                    }
+                    if (typeof cols === "number") {
+                        terminal.cols = cols;
+                    }
+                }
+                break;
+            }
+            default:
+                console.warn(`[agent] Unknown event: ${eventName}`);
+        }
+    }
+    catch (e) {
+        fail(e);
+    }
+}

package/dist/terminal.js

@@ -0,0 +1,144 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentTerminal = exports.PROGRESS_TERMINAL_ROWS = exports.TERMINAL_ROWS = exports.TERMINAL_COLS = void 0;
+const pty = __importStar(require("@homebridge/node-pty-prebuilt-multiarch"));
+exports.TERMINAL_COLS = 105;
+exports.TERMINAL_ROWS = 10;
+exports.PROGRESS_TERMINAL_ROWS = 8;
+const BUFFER_SIZE = 100;
+class AgentTerminal {
+    name;
+    file;
+    args;
+    cwd;
+    static terminalMap = new Map();
+    _ptyProcess;
+    buffer = [];
+    _rows = exports.TERMINAL_ROWS;
+    _cols = exports.TERMINAL_COLS;
+    exitCallback;
+    /** Exposed so joinExecTerminal can update the socket on reconnect */
+    socket;
+    constructor(socket, name, file, args, cwd) {
+        this.name = name;
+        this.file = file;
+        this.args = args;
+        this.cwd = cwd;
+        this.socket = socket;
+        AgentTerminal.terminalMap.set(name, this);
+    }
+    get rows() {
+        return this._rows;
+    }
+    set rows(v) {
+        this._rows = v;
+        try {
+            this._ptyProcess?.resize(this._cols, v);
+        }
+        catch { /* ignore */ }
+    }
+    get cols() {
+        return this._cols;
+    }
+    set cols(v) {
+        this._cols = v;
+        try {
+            this._ptyProcess?.resize(v, this._rows);
+        }
+        catch { /* ignore */ }
+    }
+    start() {
+        if (this._ptyProcess) {
+            return;
+        }
+        try {
+            this._ptyProcess = pty.spawn(this.file, this.args, {
+                name: this.name,
+                cwd: this.cwd,
+                cols: this._cols,
+                rows: this._rows,
+            });
+            this._ptyProcess.onData((data) => {
+                if (this.buffer.length >= BUFFER_SIZE) {
+                    this.buffer.shift();
+                }
+                this.buffer.push(data);
+                this.socket.emit("agent", "terminalWrite", this.name, data);
+            });
+            this._ptyProcess.onExit(({ exitCode }) => {
+                this.socket.emit("agent", "terminalExit", this.name, exitCode);
+                AgentTerminal.terminalMap.delete(this.name);
+                this.exitCallback?.(exitCode);
+            });
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : String(error);
+            const exitCode = Number(msg.split(" ").pop()) || 1;
+            this.socket.emit("agent", "terminalExit", this.name, exitCode);
+            AgentTerminal.terminalMap.delete(this.name);
+            this.exitCallback?.(exitCode);
+        }
+    }
+    write(input) {
+        this._ptyProcess?.write(input);
+    }
+    close() {
+        this._ptyProcess?.write("\x03");
+    }
+    getBuffer() {
+        return this.buffer.join("");
+    }
+    onExit(cb) {
+        this.exitCallback = cb;
+    }
+    static getTerminal(name) {
+        return AgentTerminal.terminalMap.get(name);
+    }
+    /**
+     * Spawn a non-interactive terminal for a command, resolve with its exit code.
+     * Output is streamed back to the main server via `socket`.
+     */
+    static exec(socket, terminalName, file, args, cwd) {
+        return new Promise((resolve, reject) => {
+            if (AgentTerminal.terminalMap.has(terminalName)) {
+                reject(new Error("Another operation is already running, please try again later."));
+                return;
+            }
+            const terminal = new AgentTerminal(socket, terminalName, file, args, cwd);
+            terminal.rows = exports.PROGRESS_TERMINAL_ROWS;
+            terminal.onExit(resolve);
+            terminal.start();
+        });
+    }
+    /** Remove all terminals — called on socket disconnect to free PTYs */
+    static closeAll() {
+        for (const terminal of AgentTerminal.terminalMap.values()) {
+            terminal.close();
+        }
+        AgentTerminal.terminalMap.clear();
+    }
+}
+exports.AgentTerminal = AgentTerminal;

package/package.json

@@ -0,0 +1,31 @@
+{
+    "name": "@tyevco/homelab-lxc-agent",
+    "version": "1.0.0",
+    "description": "Lightweight LXC agent for Homelab",
+    "bin": {
+        "homelab-lxc-agent": "bin/homelab-lxc-agent.js"
+    },
+    "scripts": {
+        "build": "tsc",
+        "prepare": "tsc",
+        "start": "node dist/index.js",
+        "dev": "ts-node src/index.ts"
+    },
+    "files": [
+        "dist/",
+        "bin/"
+    ],
+    "dependencies": {
+        "@homebridge/node-pty-prebuilt-multiarch": "0.11.14",
+        "promisify-child-process": "^4.1.2",
+        "socket.io": "~4.8.1"
+    },
+    "devDependencies": {
+        "@types/node": "^20.0.0",
+        "ts-node": "^10.9.1",
+        "typescript": "~5.2.2"
+    },
+    "engines": {
+        "node": ">=18"
+    }
+}