@lamalibre/portlama-agent 1.0.0

package/LICENSE.md

@@ -0,0 +1,100 @@
+# License
+
+Copyright (c) 2026 Code Lama Software
+
+## Noncommercial Use
+
+This software is licensed under the [Polyform Noncommercial License 1.0.0](https://polyformproject.org/licenses/noncommercial/1.0.0/).
+
+You may use, copy, modify, and distribute this software for any **noncommercial** purpose. This includes personal projects, academic research, education, and evaluation.
+
+## Commercial Use
+
+Commercial use of this software requires a commercial license, available by contacting licence@codelama.com.tr.
+
+Commercial use includes, but is not limited to:
+- Using Portlama in a business to serve data to clients or partners
+- Deploying Portlama as part of a revenue-generating service or product
+- Using Portlama internally at a for-profit organization
+
+Sponsorship tiers and terms are listed on our GitHub Sponsors page. Once you become an active sponsor at a qualifying tier, you are granted a commercial use license for the duration of your sponsorship.
+
+## Questions
+
+If you are unsure whether your use qualifies as noncommercial, please open a [GitHub Discussion](https://github.com/lamalibre/portlama/discussions) or contact us directly.
+
+---
+
+## Polyform Noncommercial License 1.0.0
+
+<https://polyformproject.org/licenses/noncommercial/1.0.0/>
+
+### Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+### Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose. However, you may only distribute the software according to [Distribution License](#distribution-license) and make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license).
+
+### Distribution License
+
+The licensor grants you an additional copyright license to distribute copies of the software. Your license to distribute covers distributing the software with changes and new works permitted by [Changes and New Works License](#changes-and-new-works-license).
+
+### Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms or the URL for them above, as well as copies of any plain-text lines beginning with `Required Notice:` that the licensor provided with the software. For example:
+
+> Required Notice: Copyright (c) 2026 Code Lama Software (https://github.com/lamalibre/portlama)
+
+### Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+### Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+### Noncommercial Purposes
+
+Any noncommercial purpose is a permitted purpose.
+
+### Personal Uses
+
+Personal use for research, experiment, and testing for the benefit of public knowledge, personal study, private entertainment, hobby projects, amateur pursuits, or religious observance, without any anticipated commercial application, is use for a permitted purpose.
+
+### Noncommercial Organizations
+
+Use by any charitable organization, educational institution, public research organization, public safety or health organization, environmental protection organization, or government institution is use for a permitted purpose regardless of the source of funding or obligations resulting from the funding.
+
+### Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+### No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else. These terms do not imply any other licenses.
+
+### Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+### Violations
+
+The first time you are notified in writing that you have violated any of these terms, or any agreement made under them, you have 32 calendar days to come into compliance. If you come into compliance within that time, your licenses under these terms will not be permanently revoked.
+
+### No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+### Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization. **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise. Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

package/README.md

@@ -0,0 +1,51 @@
+# @lamalibre/portlama-agent
+
+Mac tunnel agent for Portlama — installs a Chisel tunnel client and manages it
+as a macOS launchd agent.
+
+## Installation
+
+```bash
+npx @lamalibre/portlama-agent setup
+```
+
+The setup command downloads the Chisel binary, configures the tunnel connection,
+installs a launchd plist, and starts the agent. The panel provides the
+connection details and an agent-scoped mTLS certificate.
+
+## Commands
+
+| Command     | Description                              |
+| ----------- | ---------------------------------------- |
+| `setup`     | Install Chisel and configure the tunnel  |
+| `update`    | Update Chisel binary to latest version   |
+| `uninstall` | Remove Chisel, plist, and configuration  |
+| `status`    | Show tunnel connection status            |
+| `logs`      | Display recent tunnel logs               |
+
+## Requirements
+
+| Requirement | Details         |
+| ----------- | --------------- |
+| OS          | macOS           |
+| Node.js     | >= 20.0.0       |
+| Access      | User account (no root required) |
+
+## How It Works
+
+The agent registers with the Portlama panel using an agent-scoped mTLS
+certificate (not the admin certificate). It connects to the server's Chisel
+endpoint over WebSocket-over-HTTPS and exposes local ports as configured
+in the panel's tunnel settings.
+
+The launchd plist ensures the tunnel reconnects automatically after reboot
+or network changes.
+
+## Further Reading
+
+See the main repository for architecture, tunnel configuration, and the full
+development plan: <https://github.com/lamalibre/portlama>
+
+## License
+
+[Polyform Noncommercial 1.0.0](./LICENSE.md) — see [LICENSE.md](./LICENSE.md) for details.

package/bin/portlama-agent.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+
+import { main } from '../src/index.js';
+
+try {
+  await main();
+} catch (error) {
+  console.error('\n');
+  console.error('  Portlama Agent failed.');
+  console.error(`  Error: ${error.message}`);
+  console.error('\n');
+  process.exit(1);
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@lamalibre/portlama-agent",
+  "version": "1.0.0",
+  "description": "Mac agent for Portlama — installs Chisel tunnel client and manages launchd agent",
+  "type": "module",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "author": "Code Lama Software",
+  "bin": {
+    "portlama-agent": "bin/portlama-agent.js"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "scripts": {
+    "lint": "eslint ."
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lamalibre/portlama.git",
+    "directory": "packages/portlama-agent"
+  },
+  "homepage": "https://github.com/lamalibre/portlama#readme",
+  "bugs": {
+    "url": "https://github.com/lamalibre/portlama/issues"
+  },
+  "keywords": [
+    "portlama",
+    "tunnel",
+    "chisel",
+    "macos",
+    "launchd",
+    "agent"
+  ],
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "execa": "^9.0.0",
+    "listr2": "^8.0.0"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}

package/src/commands/logs.js

@@ -0,0 +1,33 @@
+import { existsSync } from 'node:fs';
+import { execa } from 'execa';
+import chalk from 'chalk';
+import { assertMacOS, LOG_FILE, ERROR_LOG_FILE } from '../lib/platform.js';
+
+/**
+ * Stream chisel logs to the terminal.
+ * Tails both stdout and stderr log files.
+ */
+export async function runLogs() {
+  assertMacOS();
+
+  const files = [];
+  if (existsSync(LOG_FILE)) files.push(LOG_FILE);
+  if (existsSync(ERROR_LOG_FILE)) files.push(ERROR_LOG_FILE);
+
+  if (files.length === 0) {
+    console.log('');
+    console.log(chalk.yellow('  No log files found.'));
+    console.log(chalk.dim(`  Expected: ${LOG_FILE}`));
+    console.log(chalk.dim(`  Expected: ${ERROR_LOG_FILE}`));
+    console.log(chalk.dim('  Has the agent been started? Run "portlama-agent setup" first.'));
+    console.log('');
+    process.exit(1);
+  }
+
+  console.log(chalk.dim(`  Streaming logs from: ${files.join(', ')}`));
+  console.log(chalk.dim('  Press Ctrl+C to stop.'));
+  console.log('');
+
+  // tail -f streams indefinitely — use stdio: 'inherit' to forward to terminal
+  await execa('tail', ['-f', ...files], { stdio: 'inherit' });
+}

package/src/commands/setup.js

@@ -0,0 +1,260 @@
+import { createInterface } from 'node:readline';
+import { existsSync } from 'node:fs';
+import { mkdir } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { Listr } from 'listr2';
+import chalk from 'chalk';
+import { assertMacOS, CHISEL_BIN_DIR, LOGS_DIR } from '../lib/platform.js';
+import { loadAgentConfig, saveAgentConfig } from '../lib/config.js';
+import { fetchHealth, fetchPlist, fetchTunnels } from '../lib/panel-api.js';
+import { installChisel } from '../lib/chisel.js';
+import { rewritePlist, writePlistFile } from '../lib/plist.js';
+import { isAgentLoaded, unloadAgent, loadAgent, getAgentPid } from '../lib/launchctl.js';
+
+/**
+ * Prompt for user input via readline.
+ * @param {string} question
+ * @param {string} [defaultValue]
+ * @returns {Promise<string>}
+ */
+function prompt(question, defaultValue) {
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  const suffix = defaultValue ? ` ${chalk.dim(`[${defaultValue}]`)}` : '';
+
+  return new Promise((resolvePromise) => {
+    rl.question(`  ${question}${suffix}: `, (answer) => {
+      rl.close();
+      resolvePromise(answer.trim() || defaultValue || '');
+    });
+  });
+}
+
+/**
+ * Run the interactive setup flow.
+ */
+export async function runSetup() {
+  // Step 1: Verify macOS
+  assertMacOS();
+
+  // Check for existing config
+  const existingConfig = await loadAgentConfig();
+  if (existingConfig) {
+    console.log('');
+    console.log(chalk.yellow('  An existing agent configuration was found.'));
+    console.log(chalk.yellow('  Running setup again will overwrite it.'));
+    console.log('');
+  }
+
+  // Step 2: Prompt credentials
+  console.log('');
+  console.log(chalk.bold('  Portlama Agent Setup'));
+  console.log(chalk.dim('  Connect this Mac to your Portlama server.'));
+  console.log('');
+  console.log(chalk.dim('  The admin must generate an agent certificate from the panel first:'));
+  console.log(chalk.dim('    Panel → Certificates → Agent Certificates → Generate'));
+  console.log('');
+
+  const panelUrl = await prompt(
+    'Panel URL (e.g. https://1.2.3.4:9292)',
+    existingConfig?.panelUrl,
+  );
+  if (!panelUrl) {
+    throw new Error('Panel URL is required.');
+  }
+
+  // Normalize URL: strip trailing slash
+  const normalizedUrl = panelUrl.replace(/\/+$/, '');
+
+  const defaultP12 = existingConfig?.p12Path || './agent.p12';
+  const p12Input = await prompt('Path to agent certificate (.p12)', defaultP12);
+  const p12Path = resolve(p12Input);
+
+  if (!existsSync(p12Path)) {
+    throw new Error(`client.p12 not found at: ${p12Path}`);
+  }
+
+  const p12Password = await prompt('P12 password');
+  if (!p12Password) {
+    throw new Error('P12 password is required.');
+  }
+
+  console.log('');
+
+  // Context shared across tasks
+  const ctx = {
+    panelUrl: normalizedUrl,
+    p12Path,
+    p12Password,
+    chiselVersion: null,
+    plistXml: null,
+    domain: null,
+    tunnels: [],
+  };
+
+  const tasks = new Listr(
+    [
+      {
+        title: 'Verifying panel connectivity',
+        task: async (_ctx, task) => {
+          const health = await fetchHealth(ctx.panelUrl, ctx.p12Path, ctx.p12Password);
+          task.output = `Panel is reachable (status: ${health.status || 'ok'})`;
+        },
+        rendererOptions: { persistentOutput: true },
+      },
+      {
+        title: 'Creating directories',
+        task: async () => {
+          await mkdir(CHISEL_BIN_DIR, { recursive: true });
+          await mkdir(LOGS_DIR, { recursive: true });
+        },
+      },
+      {
+        title: 'Installing Chisel',
+        task: async (_ctx, task) => {
+          const result = await installChisel();
+          ctx.chiselVersion = result.version;
+          if (result.skipped) {
+            task.output = `Already installed (${result.version})`;
+          } else {
+            task.output = `Installed ${result.version}`;
+          }
+        },
+        rendererOptions: { persistentOutput: true },
+      },
+      {
+        title: 'Fetching tunnel configuration',
+        task: async (_ctx, task) => {
+          const data = await fetchPlist(ctx.panelUrl, ctx.p12Path, ctx.p12Password);
+          ctx.plistXml = data.plist;
+
+          // Also fetch tunnel list for the summary
+          const tunnelData = await fetchTunnels(ctx.panelUrl, ctx.p12Path, ctx.p12Password);
+          ctx.tunnels = tunnelData.tunnels || [];
+          task.output = `${ctx.tunnels.length} tunnel(s) configured`;
+        },
+        rendererOptions: { persistentOutput: true },
+      },
+      {
+        title: 'Rewriting plist paths',
+        task: async () => {
+          ctx.plistXml = rewritePlist(ctx.plistXml);
+        },
+      },
+      {
+        title: 'Writing plist file',
+        task: async () => {
+          await writePlistFile(ctx.plistXml);
+        },
+      },
+      {
+        title: 'Unloading previous agent',
+        skip: async () => {
+          const loaded = await isAgentLoaded();
+          return !loaded && 'No previous agent loaded';
+        },
+        task: async () => {
+          await unloadAgent();
+        },
+      },
+      {
+        title: 'Loading agent',
+        task: async () => {
+          await loadAgent();
+        },
+      },
+      {
+        title: 'Verifying agent is running',
+        task: async (_ctx, task) => {
+          // Give launchd a moment to start the process
+          await new Promise((r) => setTimeout(r, 2000));
+          const pid = await getAgentPid();
+          if (pid) {
+            task.output = `Agent running (PID ${pid})`;
+          } else {
+            const loaded = await isAgentLoaded();
+            if (loaded) {
+              task.output = 'Agent loaded (process starting...)';
+            } else {
+              throw new Error(
+                'Agent failed to load. Check logs with: portlama-agent logs',
+              );
+            }
+          }
+        },
+        rendererOptions: { persistentOutput: true },
+      },
+      {
+        title: 'Saving configuration',
+        task: async () => {
+          // Extract domain from the plist (look for wss://tunnel.<domain>)
+          const domainMatch = ctx.plistXml.match(/wss:\/\/tunnel\.([^:]+):/);
+          ctx.domain = domainMatch ? domainMatch[1] : null;
+
+          await saveAgentConfig({
+            panelUrl: ctx.panelUrl,
+            p12Path: ctx.p12Path,
+            p12Password: ctx.p12Password,
+            domain: ctx.domain,
+            chiselVersion: ctx.chiselVersion,
+            setupAt: new Date().toISOString(),
+          });
+        },
+      },
+    ],
+    {
+      renderer: 'default',
+      rendererOptions: { collapseSubtasks: false },
+      exitOnError: true,
+    },
+  );
+
+  await tasks.run();
+
+  // Print summary
+  printSetupSummary(ctx);
+}
+
+/**
+ * Print a formatted summary after successful setup.
+ * @param {object} ctx
+ */
+function printSetupSummary(ctx) {
+  const b = chalk.bold;
+  const c = chalk.cyan;
+  const d = chalk.dim;
+  const g = chalk.green;
+
+  console.log('');
+  console.log(c('  ╔══════════════════════════════════════════════════════════╗'));
+  console.log(c('  ║') + `  ${g.bold('Portlama Agent installed successfully!')}` + ' '.repeat(17) + c('║'));
+  console.log(c('  ╠══════════════════════════════════════════════════════════╣'));
+
+  if (ctx.domain) {
+    console.log(c('  ║') + `  ${b('Domain:')}  ${c(ctx.domain)}` + ' '.repeat(Math.max(0, 46 - ctx.domain.length)) + c('║'));
+  }
+
+  console.log(c('  ║') + `  ${b('Chisel:')}  ${ctx.chiselVersion}` + ' '.repeat(Math.max(0, 46 - (ctx.chiselVersion || '').length)) + c('║'));
+  console.log(c('  ║') + `  ${b('Tunnels:')} ${ctx.tunnels.length} configured` + ' '.repeat(33) + c('║'));
+  console.log(c('  ║') + ' '.repeat(58) + c('║'));
+
+  if (ctx.tunnels.length > 0) {
+    for (const t of ctx.tunnels) {
+      const line = `${t.subdomain} → localhost:${t.port}`;
+      console.log(c('  ║') + `    ${d('•')} ${line}` + ' '.repeat(Math.max(0, 54 - line.length)) + c('║'));
+    }
+    console.log(c('  ║') + ' '.repeat(58) + c('║'));
+  }
+
+  console.log(c('  ║') + `  ${b('Commands:')}` + ' '.repeat(47) + c('║'));
+  console.log(c('  ║') + `    ${d('portlama-agent status')}    ${d('— check agent health')}` + ' '.repeat(11) + c('║'));
+  console.log(c('  ║') + `    ${d('portlama-agent logs')}      ${d('— stream chisel logs')}` + ' '.repeat(11) + c('║'));
+  console.log(c('  ║') + `    ${d('portlama-agent update')}    ${d('— refresh tunnel config')}` + ' '.repeat(8) + c('║'));
+  console.log(c('  ║') + `    ${d('portlama-agent uninstall')} ${d('— remove everything')}` + ' '.repeat(12) + c('║'));
+  console.log(c('  ║') + ' '.repeat(58) + c('║'));
+  console.log(c('  ╚══════════════════════════════════════════════════════════╝'));
+  console.log('');
+}

package/src/commands/status.js

@@ -0,0 +1,83 @@
+import chalk from 'chalk';
+import { assertMacOS, CHISEL_BIN_PATH, PLIST_PATH, LOG_FILE, AGENT_DIR } from '../lib/platform.js';
+import { loadAgentConfig } from '../lib/config.js';
+import { isAgentLoaded, getAgentPid } from '../lib/launchctl.js';
+import { getInstalledVersion } from '../lib/chisel.js';
+import { fetchTunnels } from '../lib/panel-api.js';
+import { existsSync } from 'node:fs';
+
+/**
+ * Print formatted status information about the agent.
+ */
+export async function runStatus() {
+  assertMacOS();
+
+  const b = chalk.bold;
+  const c = chalk.cyan;
+  const g = chalk.green;
+  const r = chalk.red;
+  const d = chalk.dim;
+  const y = chalk.yellow;
+
+  console.log('');
+  console.log(b('  Portlama Agent Status'));
+  console.log(d('  ─'.repeat(28)));
+
+  // Config
+  const config = await loadAgentConfig();
+  if (!config) {
+    console.log(`  ${r('Not configured.')} Run ${c('portlama-agent setup')} first.`);
+    console.log('');
+    return;
+  }
+
+  // Agent status
+  const loaded = await isAgentLoaded();
+  const pid = await getAgentPid();
+
+  console.log(`  ${b('Agent:')}     ${loaded ? g('loaded') : r('not loaded')}${pid ? ` (PID ${pid})` : ''}`);
+  console.log(`  ${b('Panel:')}     ${c(config.panelUrl)}`);
+
+  if (config.domain) {
+    console.log(`  ${b('Domain:')}    ${c(config.domain)}`);
+  }
+
+  // Chisel
+  const chiselVersion = await getInstalledVersion();
+  const chiselInstalled = existsSync(CHISEL_BIN_PATH);
+  console.log(`  ${b('Chisel:')}    ${chiselInstalled ? g(chiselVersion || 'installed') : r('not installed')}`);
+
+  // Files
+  console.log(`  ${b('Plist:')}     ${existsSync(PLIST_PATH) ? g('present') : y('missing')}`);
+  console.log(`  ${b('Config:')}    ${existsSync(AGENT_DIR) ? g('present') : y('missing')}`);
+  console.log(`  ${b('Logs:')}      ${d(LOG_FILE)}`);
+
+  if (config.setupAt) {
+    console.log(`  ${b('Setup at:')}  ${d(config.setupAt)}`);
+  }
+  if (config.updatedAt) {
+    console.log(`  ${b('Updated:')}   ${d(config.updatedAt)}`);
+  }
+
+  // Try to fetch tunnels from panel
+  console.log('');
+  console.log(b('  Tunnels'));
+  console.log(d('  ─'.repeat(28)));
+
+  try {
+    const data = await fetchTunnels(config.panelUrl, config.p12Path, config.p12Password);
+    const tunnels = data.tunnels || [];
+
+    if (tunnels.length === 0) {
+      console.log(`  ${d('No tunnels configured.')}`);
+    } else {
+      for (const t of tunnels) {
+        console.log(`  ${c('•')} ${b(t.subdomain)}.${config.domain || '?'} → localhost:${t.port}${t.description ? d(` (${t.description})`) : ''}`);
+      }
+    }
+  } catch {
+    console.log(`  ${y('Could not reach panel to fetch tunnel list.')}`);
+  }
+
+  console.log('');
+}

package/src/commands/uninstall.js

@@ -0,0 +1,54 @@
+import { rm } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { Listr } from 'listr2';
+import chalk from 'chalk';
+import { assertMacOS, AGENT_DIR, PLIST_PATH } from '../lib/platform.js';
+import { isAgentLoaded, unloadAgent } from '../lib/launchctl.js';
+
+/**
+ * Unload the agent, remove the plist, chisel binary, and config.
+ */
+export async function runUninstall() {
+  assertMacOS();
+
+  const tasks = new Listr(
+    [
+      {
+        title: 'Unloading agent',
+        skip: async () => {
+          const loaded = await isAgentLoaded();
+          return !loaded && 'Agent not loaded';
+        },
+        task: async () => {
+          await unloadAgent();
+        },
+      },
+      {
+        title: 'Removing plist file',
+        skip: () => !existsSync(PLIST_PATH) && 'Plist not found',
+        task: async () => {
+          await rm(PLIST_PATH);
+        },
+      },
+      {
+        title: 'Removing ~/.portlama directory',
+        skip: () => !existsSync(AGENT_DIR) && 'Directory not found',
+        task: async () => {
+          await rm(AGENT_DIR, { recursive: true });
+        },
+      },
+    ],
+    {
+      renderer: 'default',
+      rendererOptions: { collapseSubtasks: false },
+      exitOnError: true,
+    },
+  );
+
+  await tasks.run();
+
+  console.log('');
+  console.log(chalk.green('  Portlama Agent uninstalled successfully.'));
+  console.log(chalk.dim('  All agent files have been removed.'));
+  console.log('');
+}

package/src/commands/update.js

@@ -0,0 +1,110 @@
+import { Listr } from 'listr2';
+import chalk from 'chalk';
+import { assertMacOS } from '../lib/platform.js';
+import { requireAgentConfig, saveAgentConfig } from '../lib/config.js';
+import { fetchPlist, fetchTunnels } from '../lib/panel-api.js';
+import { rewritePlist, writePlistFile } from '../lib/plist.js';
+import { isAgentLoaded, unloadAgent, loadAgent, getAgentPid } from '../lib/launchctl.js';
+
+/**
+ * Re-fetch the plist from the panel and restart the agent.
+ * Used after adding/removing tunnels on the panel.
+ */
+export async function runUpdate() {
+  assertMacOS();
+
+  const config = await requireAgentConfig();
+
+  const ctx = {
+    plistXml: null,
+    tunnels: [],
+  };
+
+  const tasks = new Listr(
+    [
+      {
+        title: 'Fetching updated tunnel configuration',
+        task: async (_ctx, task) => {
+          const data = await fetchPlist(config.panelUrl, config.p12Path, config.p12Password);
+          ctx.plistXml = data.plist;
+
+          const tunnelData = await fetchTunnels(config.panelUrl, config.p12Path, config.p12Password);
+          ctx.tunnels = tunnelData.tunnels || [];
+          task.output = `${ctx.tunnels.length} tunnel(s) configured`;
+        },
+        rendererOptions: { persistentOutput: true },
+      },
+      {
+        title: 'Rewriting plist paths',
+        task: async () => {
+          ctx.plistXml = rewritePlist(ctx.plistXml);
+        },
+      },
+      {
+        title: 'Writing plist file',
+        task: async () => {
+          await writePlistFile(ctx.plistXml);
+        },
+      },
+      {
+        title: 'Unloading agent',
+        skip: async () => {
+          const loaded = await isAgentLoaded();
+          return !loaded && 'Agent not currently loaded';
+        },
+        task: async () => {
+          await unloadAgent();
+        },
+      },
+      {
+        title: 'Loading agent',
+        task: async () => {
+          await loadAgent();
+        },
+      },
+      {
+        title: 'Verifying agent is running',
+        task: async (_ctx, task) => {
+          await new Promise((r) => setTimeout(r, 2000));
+          const pid = await getAgentPid();
+          if (pid) {
+            task.output = `Agent running (PID ${pid})`;
+          } else {
+            const loaded = await isAgentLoaded();
+            if (loaded) {
+              task.output = 'Agent loaded (process starting...)';
+            } else {
+              throw new Error(
+                'Agent failed to load. Check logs with: portlama-agent logs',
+              );
+            }
+          }
+        },
+        rendererOptions: { persistentOutput: true },
+      },
+      {
+        title: 'Saving configuration',
+        task: async () => {
+          await saveAgentConfig({
+            ...config,
+            updatedAt: new Date().toISOString(),
+          });
+        },
+      },
+    ],
+    {
+      renderer: 'default',
+      rendererOptions: { collapseSubtasks: false },
+      exitOnError: true,
+    },
+  );
+
+  await tasks.run();
+
+  console.log('');
+  console.log(chalk.green('  Agent updated successfully.'));
+  if (ctx.tunnels.length > 0) {
+    console.log(chalk.dim(`  ${ctx.tunnels.length} tunnel(s) active.`));
+  }
+  console.log('');
+}

package/src/index.js

@@ -0,0 +1,89 @@
+import chalk from 'chalk';
+
+/**
+ * Print help message and exit.
+ */
+function printHelp() {
+  const b = chalk.bold;
+  const c = chalk.cyan;
+  const d = chalk.dim;
+
+  console.log(`
+${b('portlama-agent')} — Mac tunnel agent for Portlama
+
+${b('USAGE')}
+
+  ${c('portlama-agent')} ${d('<command>')}
+
+${b('COMMANDS')}
+
+  ${c('setup')}       Interactive setup: install Chisel, fetch tunnel config, start agent
+  ${c('update')}      Re-fetch plist from panel after tunnel changes
+  ${c('uninstall')}   Stop agent and remove all files
+  ${c('status')}      Show agent health, tunnel list, connection status
+  ${c('logs')}        Stream Chisel log output (tail -f)
+
+${b('EXAMPLES')}
+
+  ${d('# First-time setup')}
+  ${c('npx @lamalibre/portlama-agent setup')}
+
+  ${d('# After adding a tunnel on the panel')}
+  ${c('portlama-agent update')}
+
+  ${d('# Check if the agent is running')}
+  ${c('portlama-agent status')}
+
+${b('PREREQUISITES')}
+
+  ${d('•')} macOS (arm64 or x64)
+  ${d('•')} Agent certificate (.p12) generated from your Portlama panel
+    (Panel → Certificates → Agent Certificates → Generate)
+  ${d('•')} Panel URL (e.g. https://1.2.3.4:9292)
+`);
+  process.exit(0);
+}
+
+/**
+ * Parse command from argv and dispatch to the appropriate module.
+ */
+export async function main() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+
+  if (!command || command === '--help' || command === '-h') {
+    printHelp();
+  }
+
+  switch (command) {
+    case 'setup': {
+      const { runSetup } = await import('./commands/setup.js');
+      await runSetup();
+      break;
+    }
+    case 'update': {
+      const { runUpdate } = await import('./commands/update.js');
+      await runUpdate();
+      break;
+    }
+    case 'uninstall': {
+      const { runUninstall } = await import('./commands/uninstall.js');
+      await runUninstall();
+      break;
+    }
+    case 'status': {
+      const { runStatus } = await import('./commands/status.js');
+      await runStatus();
+      break;
+    }
+    case 'logs': {
+      const { runLogs } = await import('./commands/logs.js');
+      await runLogs();
+      break;
+    }
+    default:
+      console.error(`\n  Unknown command: ${chalk.red(command)}`);
+      console.error(`  Run ${chalk.cyan('portlama-agent --help')} for usage.\n`);
+      process.exit(1);
+  }
+}

package/src/lib/chisel.js

@@ -0,0 +1,112 @@
+import { execa } from 'execa';
+import { access, constants, mkdir } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { CHISEL_BIN_PATH, CHISEL_BIN_DIR } from './platform.js';
+import { detectArch } from './platform.js';
+
+const GITHUB_API = 'https://api.github.com/repos/jpillora/chisel/releases/latest';
+
+/**
+ * Check if a file exists at the given path.
+ */
+async function fileExists(filePath) {
+  try {
+    await access(filePath, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get the currently installed Chisel version, or null if not installed.
+ */
+export async function getInstalledVersion() {
+  try {
+    const { stdout } = await execa(CHISEL_BIN_PATH, ['--version']);
+    return stdout.trim();
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Download and install the Chisel binary from GitHub releases.
+ * Installs to ~/.portlama/bin/chisel — no sudo needed.
+ * @returns {Promise<{ skipped?: boolean, installed?: boolean, version: string }>}
+ */
+export async function installChisel() {
+  const exists = await fileExists(CHISEL_BIN_PATH);
+  if (exists) {
+    const version = await getInstalledVersion();
+    if (version) {
+      return { skipped: true, version };
+    }
+  }
+
+  // Fetch latest release info
+  let releaseInfo;
+  try {
+    const { stdout } = await execa('curl', [
+      '-s', '-L',
+      '-H', 'Accept: application/vnd.github+json',
+      GITHUB_API,
+    ]);
+    releaseInfo = JSON.parse(stdout);
+  } catch (err) {
+    throw new Error(
+      `Failed to fetch Chisel release info from GitHub: ${err.message}. Check internet connectivity.`,
+    );
+  }
+
+  if (releaseInfo.message && releaseInfo.message.includes('rate limit')) {
+    throw new Error(
+      'GitHub API rate limit exceeded. Please try again later or set a GITHUB_TOKEN environment variable.',
+    );
+  }
+
+  // Find the correct asset for this platform
+  const archSuffix = detectArch();
+  const asset = releaseInfo.assets?.find(
+    (a) => a.name.includes(archSuffix) && a.name.endsWith('.gz'),
+  );
+
+  if (!asset) {
+    throw new Error(
+      `Could not find ${archSuffix} asset in the latest Chisel release. Available assets: ` +
+        (releaseInfo.assets?.map((a) => a.name).join(', ') || 'none'),
+    );
+  }
+
+  const downloadUrl = asset.browser_download_url;
+  const tmpGz = path.join(tmpdir(), `chisel-${crypto.randomBytes(4).toString('hex')}.gz`);
+  const tmpBin = tmpGz.replace('.gz', '');
+
+  try {
+    await execa('curl', ['-L', '-o', tmpGz, downloadUrl]);
+  } catch (err) {
+    throw new Error(
+      `Failed to download Chisel from ${downloadUrl}: ${err.stderr || err.message}`,
+    );
+  }
+
+  try {
+    await mkdir(CHISEL_BIN_DIR, { recursive: true });
+    await execa('gunzip', ['-f', tmpGz]);
+    await execa('mv', [tmpBin, CHISEL_BIN_PATH]);
+    await execa('chmod', ['+x', CHISEL_BIN_PATH]);
+  } catch (err) {
+    throw new Error(`Failed to install Chisel binary: ${err.stderr || err.message}`);
+  } finally {
+    await execa('rm', ['-f', tmpGz, tmpBin]).catch(() => {});
+  }
+
+  const version = await getInstalledVersion();
+  if (!version) {
+    throw new Error('Chisel was installed but version check failed. The binary may be corrupted.');
+  }
+
+  return { installed: true, version };
+}

package/src/lib/config.js

@@ -0,0 +1,42 @@
+import { readFile, writeFile, rename, mkdir } from 'node:fs/promises';
+import { CONFIG_PATH, AGENT_DIR } from './platform.js';
+
+/**
+ * Load the agent config from ~/.portlama/agent.json.
+ * Returns null if the file does not exist.
+ * @returns {Promise<object | null>}
+ */
+export async function loadAgentConfig() {
+  try {
+    const raw = await readFile(CONFIG_PATH, 'utf8');
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Save the agent config atomically (write tmp → rename).
+ * @param {object} config
+ */
+export async function saveAgentConfig(config) {
+  await mkdir(AGENT_DIR, { recursive: true });
+  const tmp = CONFIG_PATH + '.tmp';
+  await writeFile(tmp, JSON.stringify(config, null, 2) + '\n', { encoding: 'utf8', mode: 0o600 });
+  await rename(tmp, CONFIG_PATH);
+}
+
+/**
+ * Load agent config or throw if it doesn't exist.
+ * Used by commands that require prior setup.
+ * @returns {Promise<object>}
+ */
+export async function requireAgentConfig() {
+  const config = await loadAgentConfig();
+  if (!config) {
+    throw new Error(
+      'No agent configuration found. Run "portlama-agent setup" first.',
+    );
+  }
+  return config;
+}

package/src/lib/launchctl.js

@@ -0,0 +1,57 @@
+import { execa } from 'execa';
+import { PLIST_PATH, PLIST_LABEL } from './platform.js';
+
+/**
+ * Check if the launchd agent is currently loaded.
+ * @returns {Promise<boolean>}
+ */
+export async function isAgentLoaded() {
+  try {
+    const { stdout } = await execa('launchctl', ['list']);
+    return stdout.includes(PLIST_LABEL);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get the PID of the running agent, or null if not running.
+ * @returns {Promise<number | null>}
+ */
+export async function getAgentPid() {
+  try {
+    const { stdout } = await execa('launchctl', ['list']);
+    for (const line of stdout.split('\n')) {
+      if (line.includes(PLIST_LABEL)) {
+        const pid = line.split('\t')[0];
+        const parsed = parseInt(pid, 10);
+        return Number.isNaN(parsed) || parsed <= 0 ? null : parsed;
+      }
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Load the launchd agent.
+ */
+export async function loadAgent() {
+  try {
+    await execa('launchctl', ['load', PLIST_PATH]);
+  } catch (err) {
+    throw new Error(`Failed to load agent: ${err.stderr || err.message}`);
+  }
+}
+
+/**
+ * Unload the launchd agent. Silent if not loaded.
+ */
+export async function unloadAgent() {
+  try {
+    await execa('launchctl', ['unload', PLIST_PATH]);
+  } catch {
+    // Agent may not be loaded — this is fine
+  }
+}

package/src/lib/panel-api.js

@@ -0,0 +1,88 @@
+import { execa } from 'execa';
+
+/**
+ * Build the common curl args for mTLS authentication.
+ * @param {string} p12Path - Path to client.p12
+ * @param {string} p12Password - P12 password
+ * @returns {string[]}
+ */
+function certArgs(p12Path, p12Password) {
+  return [
+    '--cert-type', 'P12',
+    '--cert', `${p12Path}:${p12Password}`,
+    '-k', // accept self-signed server cert
+    '-s', // silent
+    '-f', // fail on HTTP errors
+    '--max-time', '30',
+  ];
+}
+
+/**
+ * Check panel connectivity by hitting /api/health.
+ * @param {string} panelUrl - e.g. "https://1.2.3.4:9292"
+ * @param {string} p12Path
+ * @param {string} p12Password
+ * @returns {Promise<object>}
+ */
+export async function fetchHealth(panelUrl, p12Path, p12Password) {
+  const url = `${panelUrl}/api/health`;
+  try {
+    const { stdout } = await execa('curl', [
+      ...certArgs(p12Path, p12Password),
+      url,
+    ]);
+    return JSON.parse(stdout);
+  } catch (err) {
+    throw new Error(
+      `Cannot reach panel at ${url}. ` +
+        `Check the URL and that your client.p12 is valid. ` +
+        `Details: ${err.stderr || err.message}`,
+    );
+  }
+}
+
+/**
+ * Fetch the plist XML and metadata from the panel.
+ * @param {string} panelUrl
+ * @param {string} p12Path
+ * @param {string} p12Password
+ * @returns {Promise<{ plist: string, instructions: object }>}
+ */
+export async function fetchPlist(panelUrl, p12Path, p12Password) {
+  const url = `${panelUrl}/api/tunnels/mac-plist?format=json`;
+  try {
+    const { stdout } = await execa('curl', [
+      ...certArgs(p12Path, p12Password),
+      url,
+    ]);
+    return JSON.parse(stdout);
+  } catch (err) {
+    throw new Error(
+      `Failed to fetch plist from panel. ` +
+        `Details: ${err.stderr || err.message}`,
+    );
+  }
+}
+
+/**
+ * Fetch the tunnel list from the panel.
+ * @param {string} panelUrl
+ * @param {string} p12Path
+ * @param {string} p12Password
+ * @returns {Promise<{ tunnels: Array<{ id: string, subdomain: string, port: number }> }>}
+ */
+export async function fetchTunnels(panelUrl, p12Path, p12Password) {
+  const url = `${panelUrl}/api/tunnels`;
+  try {
+    const { stdout } = await execa('curl', [
+      ...certArgs(p12Path, p12Password),
+      url,
+    ]);
+    return JSON.parse(stdout);
+  } catch (err) {
+    throw new Error(
+      `Failed to fetch tunnels from panel. ` +
+        `Details: ${err.stderr || err.message}`,
+    );
+  }
+}

package/src/lib/platform.js

@@ -0,0 +1,41 @@
+import { homedir } from 'node:os';
+import path from 'node:path';
+
+const HOME = homedir();
+
+export const AGENT_DIR = path.join(HOME, '.portlama');
+export const CHISEL_BIN_DIR = path.join(AGENT_DIR, 'bin');
+export const CHISEL_BIN_PATH = path.join(CHISEL_BIN_DIR, 'chisel');
+export const LOGS_DIR = path.join(AGENT_DIR, 'logs');
+export const CONFIG_PATH = path.join(AGENT_DIR, 'agent.json');
+export const PLIST_LABEL = 'com.portlama.chisel';
+export const PLIST_PATH = path.join(HOME, 'Library', 'LaunchAgents', `${PLIST_LABEL}.plist`);
+export const LOG_FILE = path.join(LOGS_DIR, 'chisel.log');
+export const ERROR_LOG_FILE = path.join(LOGS_DIR, 'chisel.error.log');
+
+/**
+ * Assert we are running on macOS. Throws if not.
+ */
+export function assertMacOS() {
+  if (process.platform !== 'darwin') {
+    throw new Error(
+      'portlama-agent is designed for macOS only. ' +
+        `Detected platform: ${process.platform}`,
+    );
+  }
+}
+
+/**
+ * Detect architecture and return the Chisel release suffix.
+ * @returns {'darwin_arm64' | 'darwin_amd64'}
+ */
+export function detectArch() {
+  switch (process.arch) {
+    case 'arm64':
+      return 'darwin_arm64';
+    case 'x64':
+      return 'darwin_amd64';
+    default:
+      throw new Error(`Unsupported architecture: ${process.arch}. Expected arm64 or x64.`);
+  }
+}

package/src/lib/plist.js

@@ -0,0 +1,43 @@
+import { writeFile, rename, mkdir } from 'node:fs/promises';
+import path from 'node:path';
+import { CHISEL_BIN_PATH, LOG_FILE, ERROR_LOG_FILE, PLIST_PATH } from './platform.js';
+
+/**
+ * Rewrite server-generated plist XML to use user-scoped paths.
+ *
+ * Replaces:
+ *   /usr/local/bin/chisel → ~/.portlama/bin/chisel
+ *   /usr/local/var/log/chisel.log → ~/.portlama/logs/chisel.log
+ *   /usr/local/var/log/chisel.error.log → ~/.portlama/logs/chisel.error.log
+ *
+ * @param {string} xml - Original plist XML from the panel
+ * @returns {string} Rewritten plist XML
+ */
+export function rewritePlist(xml) {
+  let result = xml;
+  result = result.replace(
+    /\/usr\/local\/bin\/chisel/g,
+    CHISEL_BIN_PATH,
+  );
+  result = result.replace(
+    /\/usr\/local\/var\/log\/chisel\.log/g,
+    LOG_FILE,
+  );
+  result = result.replace(
+    /\/usr\/local\/var\/log\/chisel\.error\.log/g,
+    ERROR_LOG_FILE,
+  );
+  return result;
+}
+
+/**
+ * Write the plist file to ~/Library/LaunchAgents/ atomically.
+ * @param {string} xml - Plist XML content (already rewritten)
+ */
+export async function writePlistFile(xml) {
+  const dir = path.dirname(PLIST_PATH);
+  await mkdir(dir, { recursive: true });
+  const tmp = PLIST_PATH + '.tmp';
+  await writeFile(tmp, xml, 'utf8');
+  await rename(tmp, PLIST_PATH);
+}