@lamalibre/portlama-agent 1.0.7 → 1.0.8

package/LICENSE.md

@@ -10,7 +10,7 @@ You may use, copy, modify, and distribute this software for any **noncommercial*
 
 ## Commercial Use
 
-Commercial use of this software requires a commercial license, available by contacting licence@codelama.com.tr.
+Commercial use of this software requires a commercial license, available by contacting license@codelama.com.tr.
 
 Commercial use includes, but is not limited to:
 

package/README.md

@@ -1,7 +1,7 @@
 # @lamalibre/portlama-agent
 
-Mac tunnel agent for Portlama — installs a Chisel tunnel client and manages it
-as a macOS launchd agent.
+Tunnel agent for Portlama — manages a Chisel tunnel client as a system service
+on macOS (launchd) and Linux (systemd).
 
 ## Installation
 
@@ -10,16 +10,17 @@ 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.
+installs a system service (launchd plist on macOS, systemd unit on Linux), 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    |
+| `update`                           | Re-fetch config from panel and restart     |
+| `uninstall`                        | Remove Chisel, service, and configuration  |
 | `status`                           | Show tunnel connection status              |
 | `logs`                             | Display recent tunnel logs                 |
 | `sites`                            | List all static sites                      |
@@ -102,11 +103,11 @@ portlama-agent deploy blog ./dist
 
 ## Requirements
 
-| Requirement | Details                         |
-| ----------- | ------------------------------- |
-| OS          | macOS                           |
-| Node.js     | >= 20.0.0                       |
-| Access      | User account (no root required) |
+| Requirement | Details                                         |
+| ----------- | ----------------------------------------------- |
+| OS          | macOS or Ubuntu Linux (24.04 LTS)               |
+| Node.js     | >= 20.0.0                                       |
+| Access      | User account on macOS; root/sudo on Linux       |
 
 ## How It Works
 
@@ -115,8 +116,8 @@ 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.
+The system service (launchd on macOS, systemd on Linux) ensures the tunnel
+reconnects automatically after reboot or network changes.
 
 ## Further Reading
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lamalibre/portlama-agent",
-  "version": "1.0.7",
-  "description": "Mac agent for Portlama — installs Chisel tunnel client and manages launchd agent",
+  "version": "1.0.8",
+  "description": "Tunnel agent for Portlama — manages Chisel tunnel client as a system service",
   "type": "module",
   "license": "SEE LICENSE IN LICENSE.md",
   "author": "Code Lama Software",
@@ -30,6 +30,9 @@
     "chisel",
     "macos",
     "launchd",
+    "linux",
+    "systemd",
+    "ubuntu",
     "agent"
   ],
   "dependencies": {

package/src/commands/deploy.js

@@ -2,7 +2,7 @@ import chalk from 'chalk';
 import { Listr } from 'listr2';
 import { readdir, stat } from 'node:fs/promises';
 import path from 'node:path';
-import { assertMacOS } from '../lib/platform.js';
+import { assertSupportedPlatform } from '../lib/platform.js';
 import { requireAgentConfig } from '../lib/config.js';
 import { fetchSites, fetchSiteFiles, deleteSiteFile, uploadSiteFiles } from '../lib/panel-api.js';
 import { formatBytes } from '../lib/format.js';
@@ -40,7 +40,7 @@ async function scanDirectory(dir, base = '') {
  * @param {string[]} args
  */
 export async function runDeploy(args) {
-  assertMacOS();
+  assertSupportedPlatform();
   const config = await requireAgentConfig();
 
   const target = args[0];

package/src/commands/logs.js

@@ -1,14 +1,14 @@
 import { existsSync } from 'node:fs';
 import { execa } from 'execa';
 import chalk from 'chalk';
-import { assertMacOS, LOG_FILE, ERROR_LOG_FILE } from '../lib/platform.js';
+import { assertSupportedPlatform, 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();
+  assertSupportedPlatform();
 
   const files = [];
   if (existsSync(LOG_FILE)) files.push(LOG_FILE);

package/src/commands/plugin.js

@@ -3,7 +3,7 @@ import { execa } from 'execa';
 import { readFile, writeFile, rename, open, mkdir, rm } from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import path from 'node:path';
-import { assertMacOS, AGENT_DIR } from '../lib/platform.js';
+import { assertSupportedPlatform, AGENT_DIR } from '../lib/platform.js';
 
 const PLUGINS_FILE = path.join(AGENT_DIR, 'plugins.json');
 
@@ -225,7 +225,7 @@ async function showStatus() {
  * Entry point for the plugin subcommand.
  */
 export async function runPlugin(args) {
-  assertMacOS();
+  assertSupportedPlatform();
 
   const subcommand = args[0];
   const target = args[1];

package/src/commands/setup.js

@@ -5,14 +5,15 @@ import { resolve } from 'node:path';
 import path from 'node:path';
 import { Listr } from 'listr2';
 import chalk from 'chalk';
-import { assertMacOS, CHISEL_BIN_DIR, LOGS_DIR, AGENT_DIR } from '../lib/platform.js';
+import { assertSupportedPlatform, isDarwin, CHISEL_BIN_DIR, LOGS_DIR, AGENT_DIR } from '../lib/platform.js';
 import { loadAgentConfig, saveAgentConfig } from '../lib/config.js';
-import { fetchHealth, fetchPlist, fetchTunnels, curlPostUnauthenticated } from '../lib/panel-api.js';
+import { fetchHealth, fetchAgentConfig, fetchTunnels, curlPostUnauthenticated } from '../lib/panel-api.js';
 import { extractPemFromP12, cleanupPemFiles } from '../lib/ws-helpers.js';
 import { installChisel } from '../lib/chisel.js';
-import { rewritePlist, writePlistFile } from '../lib/plist.js';
-import { isAgentLoaded, unloadAgent, loadAgent, getAgentPid } from '../lib/launchctl.js';
-import { generateKeypairAndCSR, importIdentityToKeychain, secureDelete } from '../lib/keychain.js';
+import { generateServiceConfig, writeServiceConfigFile } from '../lib/service-config.js';
+import { isAgentLoaded, unloadAgent, loadAgent, getAgentPid } from '../lib/service.js';
+import { generateKeypairAndCSR, secureDelete } from '../lib/keychain.js';
+import { storeEnrolledCert } from '../lib/cert-store.js';
 
 /**
  * Prompt for user input via readline.
@@ -38,6 +39,8 @@ function prompt(question, defaultValue) {
 
 /**
  * Parse --token and --panel-url flags from argv.
+ * Token can also be provided via PORTLAMA_ENROLLMENT_TOKEN env var
+ * to avoid exposure in process listings.
  * @returns {{ token?: string, panelUrl?: string }}
  */
 function parseSetupFlags() {
@@ -50,6 +53,10 @@ function parseSetupFlags() {
       flags.panelUrl = args[++i];
     }
   }
+  // Prefer env var over CLI arg to keep token out of process listings
+  if (process.env.PORTLAMA_ENROLLMENT_TOKEN) {
+    flags.token = process.env.PORTLAMA_ENROLLMENT_TOKEN;
+  }
   return flags;
 }
 
@@ -75,8 +82,8 @@ export async function runSetup() {
  * @param {{ token: string, panelUrl?: string }} flags
  */
 async function runTokenSetup(flags) {
-  // Step 1: Verify macOS
-  assertMacOS();
+  // Step 1: Verify supported platform
+  assertSupportedPlatform();
 
   // Check for existing config
   const existingConfig = await loadAgentConfig();
@@ -88,8 +95,10 @@ async function runTokenSetup(flags) {
   }
 
   console.log('');
-  console.log(chalk.bold('  Portlama Agent Setup (Hardware-Bound Certificate)'));
-  console.log(chalk.dim('  Connect this Mac to your Portlama server using a Keychain-bound certificate.'));
+  console.log(chalk.bold('  Portlama Agent Setup (Token-Based Enrollment)'));
+  console.log(chalk.dim(isDarwin()
+    ? '  Connect this Mac to your Portlama server using a Keychain-bound certificate.'
+    : '  Connect this machine to your Portlama server using a certificate.'));
   console.log('');
 
   let panelUrl = flags.panelUrl;
@@ -110,8 +119,10 @@ async function runTokenSetup(flags) {
     token: flags.token,
     agentLabel: null,
     keychainIdentity: null,
+    p12Path: null,
+    p12Password: null,
     chiselVersion: null,
-    plistXml: null,
+    serviceConfig: null,
     domain: null,
     tunnels: [],
   };
@@ -157,19 +168,25 @@ async function runTokenSetup(flags) {
         rendererOptions: { persistentOutput: true },
       },
       {
-        title: 'Importing certificate into Keychain',
+        title: isDarwin() ? 'Importing certificate into Keychain' : 'Storing certificate',
         task: async (_ctx, task) => {
           // The server overrides the CSR subject with the correct CN=agent:<label>
           // during signing, so the CSR placeholder subject doesn't matter.
-          const { identity } = await importIdentityToKeychain(
+          const result = await storeEnrolledCert(
             ctx._keyData.keyPath,
             ctx._certPem,
             ctx._caCertPem,
             ctx.agentLabel,
             console,
           );
-          ctx.keychainIdentity = identity;
-          task.output = `Identity "${identity}" imported (non-extractable)`;
+          if (result.identity) {
+            ctx.keychainIdentity = result.identity;
+            task.output = `Identity "${result.identity}" imported (non-extractable)`;
+          } else {
+            ctx.p12Path = result.p12Path;
+            ctx.p12Password = result.p12Password;
+            task.output = `Certificate stored at ${result.p12Path}`;
+          }
         },
         rendererOptions: { persistentOutput: true },
       },
@@ -183,12 +200,10 @@ async function runTokenSetup(flags) {
       {
         title: 'Verifying panel connectivity',
         task: async (_ctx, task) => {
-          const config = {
-            panelUrl: ctx.panelUrl,
-            authMethod: 'keychain',
-            keychainIdentity: ctx.keychainIdentity,
-          };
-          const health = await fetchHealth(config);
+          const authConfig = ctx.keychainIdentity
+            ? { panelUrl: ctx.panelUrl, authMethod: 'keychain', keychainIdentity: ctx.keychainIdentity }
+            : { panelUrl: ctx.panelUrl, authMethod: 'p12', p12Path: ctx.p12Path, p12Password: ctx.p12Password };
+          const health = await fetchHealth(authConfig);
           task.output = `Panel is reachable (status: ${health.status || 'ok'})`;
         },
         rendererOptions: { persistentOutput: true },
@@ -209,30 +224,24 @@ async function runTokenSetup(flags) {
       {
         title: 'Fetching tunnel configuration',
         task: async (_ctx, task) => {
-          const config = {
-            panelUrl: ctx.panelUrl,
-            authMethod: 'keychain',
-            keychainIdentity: ctx.keychainIdentity,
-          };
-          const data = await fetchPlist(config);
-          ctx.plistXml = data.plist;
+          const authConfig = ctx.keychainIdentity
+            ? { panelUrl: ctx.panelUrl, authMethod: 'keychain', keychainIdentity: ctx.keychainIdentity }
+            : { panelUrl: ctx.panelUrl, authMethod: 'p12', p12Path: ctx.p12Path, p12Password: ctx.p12Password };
 
-          const tunnelData = await fetchTunnels(config);
+          const agentConfig = await fetchAgentConfig(authConfig);
+          ctx.domain = agentConfig.domain;
+          ctx.serviceConfig = generateServiceConfig(agentConfig.chiselArgs);
+
+          const tunnelData = await fetchTunnels(authConfig);
           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',
+        title: 'Writing service config',
         task: async () => {
-          await writePlistFile(ctx.plistXml);
+          await writeServiceConfigFile(ctx.serviceConfig);
         },
       },
       {
@@ -247,13 +256,16 @@ async function runTokenSetup(flags) {
       },
       {
         title: 'Loading agent',
+        skip: () => ctx.tunnels.length === 0 && 'No tunnels configured — run portlama-agent update after creating tunnels',
         task: async () => {
           await loadAgent();
         },
       },
       {
         title: 'Verifying agent is running',
+        skip: () => ctx.tunnels.length === 0 && 'No tunnels configured',
         task: async (_ctx, task) => {
+          // Give the service manager a moment to start the process
           await new Promise((r) => setTimeout(r, 2000));
           const pid = await getAgentPid();
           if (pid) {
@@ -272,18 +284,24 @@ async function runTokenSetup(flags) {
       {
         title: 'Saving configuration',
         task: async () => {
-          const domainMatch = ctx.plistXml.match(/wss:\/\/tunnel\.([^:]+):/);
-          ctx.domain = domainMatch ? domainMatch[1] : null;
-
-          await saveAgentConfig({
+          const configData = {
             panelUrl: ctx.panelUrl,
-            authMethod: 'keychain',
-            keychainIdentity: ctx.keychainIdentity,
             agentLabel: ctx.agentLabel,
             domain: ctx.domain,
             chiselVersion: ctx.chiselVersion,
             setupAt: new Date().toISOString(),
-          });
+          };
+
+          if (ctx.keychainIdentity) {
+            configData.authMethod = 'keychain';
+            configData.keychainIdentity = ctx.keychainIdentity;
+          } else {
+            configData.authMethod = 'p12';
+            configData.p12Path = ctx.p12Path;
+            configData.p12Password = ctx.p12Password;
+          }
+
+          await saveAgentConfig(configData);
         },
       },
     ],
@@ -298,7 +316,7 @@ async function runTokenSetup(flags) {
     await tasks.run();
   } catch (err) {
     // Securely delete the temporary private key if it was generated but not
-    // yet imported into Keychain (importIdentityToKeychain handles its own cleanup).
+    // yet consumed by storeEnrolledCert (which handles its own cleanup).
     if (ctx._keyData?.keyPath) {
       await secureDelete(ctx._keyData.keyPath).catch(() => {});
     }
@@ -313,8 +331,8 @@ async function runTokenSetup(flags) {
  * Traditional P12-based setup flow.
  */
 async function runP12Setup() {
-  // Step 1: Verify macOS
-  assertMacOS();
+  // Step 1: Verify supported platform
+  assertSupportedPlatform();
 
   // Check for existing config
   const existingConfig = await loadAgentConfig();
@@ -328,7 +346,9 @@ async function runP12Setup() {
   // 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(chalk.dim(isDarwin()
+    ? '  Connect this Mac to your Portlama server.'
+    : '  Connect this machine 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'));
@@ -363,7 +383,7 @@ async function runP12Setup() {
     p12Path,
     p12Password,
     chiselVersion: null,
-    plistXml: null,
+    serviceConfig: null,
     domain: null,
     tunnels: [],
   };
@@ -415,8 +435,9 @@ async function runP12Setup() {
       {
         title: 'Fetching tunnel configuration',
         task: async (_ctx, task) => {
-          const data = await fetchPlist(ctx.panelUrl, ctx.p12Path, ctx.p12Password);
-          ctx.plistXml = data.plist;
+          const agentConfig = await fetchAgentConfig(ctx.panelUrl, ctx.p12Path, ctx.p12Password);
+          ctx.domain = agentConfig.domain;
+          ctx.serviceConfig = generateServiceConfig(agentConfig.chiselArgs);
 
           // Also fetch tunnel list for the summary
           const tunnelData = await fetchTunnels(ctx.panelUrl, ctx.p12Path, ctx.p12Password);
@@ -426,15 +447,9 @@ async function runP12Setup() {
         rendererOptions: { persistentOutput: true },
       },
       {
-        title: 'Rewriting plist paths',
-        task: async () => {
-          ctx.plistXml = rewritePlist(ctx.plistXml);
-        },
-      },
-      {
-        title: 'Writing plist file',
+        title: 'Writing service config',
         task: async () => {
-          await writePlistFile(ctx.plistXml);
+          await writeServiceConfigFile(ctx.serviceConfig);
         },
       },
       {
@@ -449,14 +464,16 @@ async function runP12Setup() {
       },
       {
         title: 'Loading agent',
+        skip: () => ctx.tunnels.length === 0 && 'No tunnels configured — run portlama-agent update after creating tunnels',
         task: async () => {
           await loadAgent();
         },
       },
       {
         title: 'Verifying agent is running',
+        skip: () => ctx.tunnels.length === 0 && 'No tunnels configured',
         task: async (_ctx, task) => {
-          // Give launchd a moment to start the process
+          // Give the service manager a moment to start the process
           await new Promise((r) => setTimeout(r, 2000));
           const pid = await getAgentPid();
           if (pid) {
@@ -475,10 +492,6 @@ async function runP12Setup() {
       {
         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,
             authMethod: 'p12',

package/src/commands/sites.js

@@ -1,6 +1,6 @@
 import { createInterface } from 'node:readline';
 import chalk from 'chalk';
-import { assertMacOS } from '../lib/platform.js';
+import { assertSupportedPlatform } from '../lib/platform.js';
 import { requireAgentConfig } from '../lib/config.js';
 import { fetchSites, createSite, deleteSite } from '../lib/panel-api.js';
 import { formatBytes } from '../lib/format.js';
@@ -57,7 +57,7 @@ function parseFlags(args) {
  * @param {string[]} args
  */
 export async function runSites(args) {
-  assertMacOS();
+  assertSupportedPlatform();
   const config = await requireAgentConfig();
   const sub = args[0];
 

package/src/commands/status.js

@@ -1,7 +1,7 @@
 import chalk from 'chalk';
-import { assertMacOS, CHISEL_BIN_PATH, PLIST_PATH, LOG_FILE, AGENT_DIR } from '../lib/platform.js';
+import { assertSupportedPlatform, CHISEL_BIN_PATH, SERVICE_CONFIG_PATH, LOG_FILE, AGENT_DIR } from '../lib/platform.js';
 import { loadAgentConfig } from '../lib/config.js';
-import { isAgentLoaded, getAgentPid } from '../lib/launchctl.js';
+import { isAgentLoaded, getAgentPid } from '../lib/service.js';
 import { getInstalledVersion } from '../lib/chisel.js';
 import { fetchTunnels } from '../lib/panel-api.js';
 import { existsSync } from 'node:fs';
@@ -10,7 +10,7 @@ import { existsSync } from 'node:fs';
  * Print formatted status information about the agent.
  */
 export async function runStatus() {
-  assertMacOS();
+  assertSupportedPlatform();
 
   const b = chalk.bold;
   const c = chalk.cyan;
@@ -52,7 +52,7 @@ export async function runStatus() {
   );
 
   // Files
-  console.log(`  ${b('Plist:')}     ${existsSync(PLIST_PATH) ? g('present') : y('missing')}`);
+  console.log(`  ${b('Service:')}   ${existsSync(SERVICE_CONFIG_PATH) ? g('present') : y('missing')}`);
   console.log(`  ${b('Config:')}    ${existsSync(AGENT_DIR) ? g('present') : y('missing')}`);
   console.log(`  ${b('Logs:')}      ${d(LOG_FILE)}`);
 

package/src/commands/uninstall.js

@@ -2,14 +2,14 @@ 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';
+import { assertSupportedPlatform, AGENT_DIR, SERVICE_CONFIG_PATH, isLinux } from '../lib/platform.js';
+import { isAgentLoaded, unloadAgent } from '../lib/service.js';
 
 /**
- * Unload the agent, remove the plist, chisel binary, and config.
+ * Unload the agent, remove the service config, chisel binary, and config.
  */
 export async function runUninstall() {
-  assertMacOS();
+  assertSupportedPlatform();
 
   const tasks = new Listr(
     [
@@ -24,10 +24,14 @@ export async function runUninstall() {
         },
       },
       {
-        title: 'Removing plist file',
-        skip: () => !existsSync(PLIST_PATH) && 'Plist not found',
+        title: 'Removing service config',
+        skip: () => !existsSync(SERVICE_CONFIG_PATH) && 'Service config not found',
         task: async () => {
-          await rm(PLIST_PATH);
+          await rm(SERVICE_CONFIG_PATH);
+          if (isLinux()) {
+            const { execa } = await import('execa');
+            await execa('systemctl', ['daemon-reload']);
+          }
         },
       },
       {

package/src/commands/update.js

@@ -1,22 +1,22 @@
 import { Listr } from 'listr2';
 import chalk from 'chalk';
-import { assertMacOS } from '../lib/platform.js';
+import { assertSupportedPlatform } 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';
+import { fetchAgentConfig, fetchTunnels } from '../lib/panel-api.js';
+import { generateServiceConfig, writeServiceConfigFile } from '../lib/service-config.js';
+import { isAgentLoaded, unloadAgent, loadAgent, getAgentPid } from '../lib/service.js';
 
 /**
- * Re-fetch the plist from the panel and restart the agent.
+ * Re-fetch tunnel config from the panel and restart the agent.
  * Used after adding/removing tunnels on the panel.
  */
 export async function runUpdate() {
-  assertMacOS();
+  assertSupportedPlatform();
 
   const config = await requireAgentConfig();
 
   const ctx = {
-    plistXml: null,
+    serviceConfig: null,
     tunnels: [],
   };
 
@@ -25,8 +25,8 @@ export async function runUpdate() {
       {
         title: 'Fetching updated tunnel configuration',
         task: async (_ctx, task) => {
-          const data = await fetchPlist(config);
-          ctx.plistXml = data.plist;
+          const agentConfig = await fetchAgentConfig(config);
+          ctx.serviceConfig = generateServiceConfig(agentConfig.chiselArgs);
 
           const tunnelData = await fetchTunnels(config);
           ctx.tunnels = tunnelData.tunnels || [];
@@ -35,15 +35,9 @@ export async function runUpdate() {
         rendererOptions: { persistentOutput: true },
       },
       {
-        title: 'Rewriting plist paths',
+        title: 'Writing service config',
         task: async () => {
-          ctx.plistXml = rewritePlist(ctx.plistXml);
-        },
-      },
-      {
-        title: 'Writing plist file',
-        task: async () => {
-          await writePlistFile(ctx.plistXml);
+          await writeServiceConfigFile(ctx.serviceConfig);
         },
       },
       {

package/src/index.js

@@ -9,7 +9,7 @@ function printHelp() {
   const d = chalk.dim;
 
   console.log(`
-${b('portlama-agent')} — Mac tunnel agent for Portlama
+${b('portlama-agent')} — tunnel agent for Portlama (macOS & Linux)
 
 ${b('USAGE')}
 
@@ -18,7 +18,7 @@ ${b('USAGE')}
 ${b('COMMANDS')}
 
   ${c('setup')}           Interactive setup: install Chisel, fetch tunnel config, start agent
-  ${c('update')}          Re-fetch plist from panel after tunnel changes
+  ${c('update')}          Re-fetch config 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)
@@ -28,9 +28,12 @@ ${b('COMMANDS')}
 
 ${b('EXAMPLES')}
 
-  ${d('# First-time setup')}
+  ${d('# First-time setup (interactive)')}
   ${c('npx @lamalibre/portlama-agent setup')}
 
+  ${d('# Token-based setup (non-interactive)')}
+  ${c('PORTLAMA_ENROLLMENT_TOKEN=<token> portlama-agent setup --panel-url https://1.2.3.4:9292')}
+
   ${d('# After adding a tunnel on the panel')}
   ${c('portlama-agent update')}
 
@@ -52,9 +55,9 @@ ${b('EXAMPLES')}
 
 ${b('PREREQUISITES')}
 
-  ${d('•')} macOS (arm64 or x64)
-  ${d('•')} Agent certificate (.p12) generated from your Portlama panel
-    (Panel → Certificates → Agent Certificates → Generate)
+  ${d('•')} macOS (arm64 or x64) or Ubuntu Linux (arm64 or x64)
+  ${d('•')} Agent certificate (.p12) or enrollment token from your Portlama panel
+    (Panel → Certificates → Agent Certificates → Generate / Enroll)
   ${d('•')} Panel URL (e.g. https://1.2.3.4:9292)
 `);
   process.exit(0);

package/src/lib/cert-store.js

@@ -0,0 +1,142 @@
+/**
+ * Portable certificate storage for token-based enrollment.
+ *
+ * Dispatches to macOS Keychain or Linux P12 file storage based on process.platform.
+ */
+
+import crypto from 'node:crypto';
+import { writeFile, access, constants } from 'node:fs/promises';
+import path from 'node:path';
+import { execa } from 'execa';
+import { isDarwin, AGENT_DIR } from './platform.js';
+import { secureDelete } from './keychain.js';
+
+const LINUX_P12_PATH = path.join(AGENT_DIR, 'client.p12');
+
+/**
+ * Store an enrolled certificate using the platform-appropriate mechanism.
+ *
+ * - macOS: imports identity into Keychain (non-extractable)
+ * - Linux: creates a P12 file at ~/.portlama/client.p12 with mode 0600
+ *
+ * @param {string} keyPath - Path to the temporary private key PEM
+ * @param {string} certPem - PEM-encoded signed certificate
+ * @param {string} caCertPem - PEM-encoded CA certificate
+ * @param {string} label - Agent label
+ * @param {import('pino').Logger | Console} logger
+ * @returns {Promise<{ identity?: string, p12Path?: string, p12Password?: string }>}
+ */
+export async function storeEnrolledCert(keyPath, certPem, caCertPem, label, logger) {
+  if (isDarwin()) {
+    const { importIdentityToKeychain } = await import('./keychain.js');
+    const { identity } = await importIdentityToKeychain(keyPath, certPem, caCertPem, label, logger);
+    return { identity };
+  }
+  return storeP12Linux(keyPath, certPem, caCertPem, label, logger);
+}
+
+/**
+ * Check if an enrolled certificate exists.
+ * @param {string} label - Agent label
+ * @returns {Promise<boolean>}
+ */
+export async function enrolledCertExists(label) {
+  if (isDarwin()) {
+    const { keychainIdentityExists } = await import('./keychain.js');
+    return keychainIdentityExists(label);
+  }
+  return linuxP12Exists();
+}
+
+/**
+ * Remove an enrolled certificate.
+ * @param {string} label - Agent label
+ */
+export async function removeEnrolledCert(label) {
+  if (isDarwin()) {
+    const { removeKeychainIdentity } = await import('./keychain.js');
+    return removeKeychainIdentity(label);
+  }
+  return removeLinuxP12();
+}
+
+// ---------------------------------------------------------------------------
+// Linux — P12 file storage
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a P12 from key + cert + CA and store at ~/.portlama/client.p12.
+ *
+ * Uses the same `-keypbe PBE-SHA1-3DES` parameters as keychain.js for
+ * maximum curl compatibility.
+ */
+async function storeP12Linux(keyPath, certPem, caCertPem, label, logger) {
+  const suffix = crypto.randomBytes(8).toString('hex');
+  const certPath = path.join(AGENT_DIR, `.tmp-cert-${suffix}.pem`);
+  const caPath = path.join(AGENT_DIR, `.tmp-ca-${suffix}.pem`);
+  const p12Password = crypto.randomBytes(16).toString('hex');
+
+  try {
+    // Write cert and CA to temp files
+    await writeFile(certPath, certPem, { mode: 0o600 });
+    await writeFile(caPath, caCertPem, { mode: 0o600 });
+
+    logger.info?.({ label }, 'Creating P12 certificate bundle') ??
+      logger.log?.(`Creating P12 certificate bundle: ${label}`);
+
+    await execa('openssl', [
+      'pkcs12',
+      '-export',
+      '-keypbe',
+      'PBE-SHA1-3DES',
+      '-certpbe',
+      'PBE-SHA1-3DES',
+      '-macalg',
+      'sha1',
+      '-out',
+      LINUX_P12_PATH,
+      '-inkey',
+      keyPath,
+      '-in',
+      certPath,
+      '-certfile',
+      caPath,
+      '-name',
+      `Portlama Agent (${label})`,
+      '-passout',
+      'env:PORTLAMA_TMP_P12_PASS',
+    ], {
+      env: { ...process.env, PORTLAMA_TMP_P12_PASS: p12Password },
+    });
+
+    // Set restrictive permissions on the P12
+    await execa('chmod', ['600', LINUX_P12_PATH]);
+
+    logger.info?.({ label, path: LINUX_P12_PATH }, 'P12 stored') ??
+      logger.log?.(`P12 stored at ${LINUX_P12_PATH}`);
+
+    return { p12Path: LINUX_P12_PATH, p12Password };
+  } finally {
+    // Securely delete temp files — the key is consumed here
+    await secureDelete(keyPath);
+    await secureDelete(certPath);
+    await secureDelete(caPath);
+  }
+}
+
+async function linuxP12Exists() {
+  try {
+    await access(LINUX_P12_PATH, constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function removeLinuxP12() {
+  try {
+    await secureDelete(LINUX_P12_PATH);
+  } catch {
+    // May not exist — this is fine
+  }
+}

package/src/lib/panel-api.js

@@ -216,22 +216,26 @@ export async function fetchHealth(panelUrlOrConfig, p12Path, p12Password) {
 }
 
 /**
- * Fetch the plist XML and metadata from the panel.
+ * Fetch the platform-agnostic agent config from the panel.
+ * Returns chiselArgs, domain, and tunnel metadata for any platform.
+ *
  * @param {string|object} panelUrlOrConfig
  * @param {string} [p12Path]
  * @param {string} [p12Password]
- * @returns {Promise<{ plist: string, instructions: object }>}
+ * @returns {Promise<{ domain: string, chiselServerUrl: string, chiselArgs: string[], tunnels: Array<{ port: number, subdomain: string }> }>}
  */
-export async function fetchPlist(panelUrlOrConfig, p12Path, p12Password) {
+export async function fetchAgentConfig(panelUrlOrConfig, p12Path, p12Password) {
   const panelUrl = resolvePanelUrl(panelUrlOrConfig);
-  const url = `${panelUrl}/api/tunnels/mac-plist?format=json`;
+  const url = `${panelUrl}/api/tunnels/agent-config`;
   try {
     const { stdout } = typeof panelUrlOrConfig === 'object'
       ? await curlAuthenticated(panelUrlOrConfig, [url])
       : await curlWithConfig(p12Path, p12Password, [url]);
     return JSON.parse(stdout);
   } catch (err) {
-    throw new Error(`Failed to fetch plist from panel. ` + `Details: ${err.stderr || err.message}`);
+    throw new Error(
+      `Failed to fetch agent config from panel. ` + `Details: ${err.stderr || err.message}`,
+    );
   }
 }
 

package/src/lib/platform.js

@@ -13,27 +13,54 @@ export const PLIST_PATH = path.join(HOME, 'Library', 'LaunchAgents', `${PLIST_LA
 export const LOG_FILE = path.join(LOGS_DIR, 'chisel.log');
 export const ERROR_LOG_FILE = path.join(LOGS_DIR, 'chisel.error.log');
 
+/** systemd unit file path on Linux */
+export const SYSTEMD_UNIT_PATH = '/etc/systemd/system/portlama-chisel.service';
+
+/**
+ * Platform-appropriate service config path.
+ * - macOS: ~/Library/LaunchAgents/com.portlama.chisel.plist
+ * - Linux: /etc/systemd/system/portlama-chisel.service
+ */
+export const SERVICE_CONFIG_PATH = process.platform === 'darwin' ? PLIST_PATH : SYSTEMD_UNIT_PATH;
+
+/**
+ * @returns {boolean} true if running on macOS
+ */
+export function isDarwin() {
+  return process.platform === 'darwin';
+}
+
+/**
+ * @returns {boolean} true if running on Linux
+ */
+export function isLinux() {
+  return process.platform === 'linux';
+}
+
 /**
- * Assert we are running on macOS. Throws if not.
+ * Assert we are running on a supported platform (macOS or Linux).
+ * Throws if not.
  */
-export function assertMacOS() {
-  if (process.platform !== 'darwin') {
+export function assertSupportedPlatform() {
+  if (process.platform !== 'darwin' && process.platform !== 'linux') {
     throw new Error(
-      'portlama-agent is designed for macOS only. ' + `Detected platform: ${process.platform}`,
+      'portlama-agent supports macOS and Linux only. ' +
+        `Detected platform: ${process.platform}`,
     );
   }
 }
 
 /**
  * Detect architecture and return the Chisel release suffix.
- * @returns {'darwin_arm64' | 'darwin_amd64'}
+ * @returns {'darwin_arm64' | 'darwin_amd64' | 'linux_arm64' | 'linux_amd64'}
  */
 export function detectArch() {
+  const platform = process.platform === 'darwin' ? 'darwin' : 'linux';
   switch (process.arch) {
     case 'arm64':
-      return 'darwin_arm64';
+      return `${platform}_arm64`;
     case 'x64':
-      return 'darwin_amd64';
+      return `${platform}_amd64`;
     default:
       throw new Error(`Unsupported architecture: ${process.arch}. Expected arm64 or x64.`);
   }

package/src/lib/service-config.js

@@ -0,0 +1,189 @@
+/**
+ * Unified service config generation.
+ *
+ * Dispatches to plist (macOS) or systemd unit (Linux) based on process.platform.
+ */
+
+import { writeFile, rename, mkdir } from 'node:fs/promises';
+import path from 'node:path';
+import { execa } from 'execa';
+import {
+  isDarwin,
+  CHISEL_BIN_PATH,
+  LOG_FILE,
+  ERROR_LOG_FILE,
+  PLIST_PATH,
+  SYSTEMD_UNIT_PATH,
+  LOGS_DIR,
+} from './platform.js';
+
+/**
+ * Validate chiselArgs against expected patterns to prevent injection.
+ * Chisel args must be: ['client', '--tls-skip-verify', 'https://tunnel.DOMAIN:443', 'R:...', ...]
+ * @param {string[]} chiselArgs
+ */
+function validateChiselArgs(chiselArgs) {
+  if (!Array.isArray(chiselArgs) || chiselArgs.length < 3) {
+    throw new Error('Invalid chiselArgs: expected at least 3 elements');
+  }
+  if (chiselArgs[0] !== 'client') {
+    throw new Error('Invalid chiselArgs: first element must be "client"');
+  }
+
+  for (const arg of chiselArgs) {
+    if (typeof arg !== 'string') {
+      throw new Error('Invalid chiselArgs: all elements must be strings');
+    }
+    // Reject newlines, null bytes, and other control characters
+    if (/[\n\r\0]/.test(arg)) {
+      throw new Error('Invalid chiselArgs: element contains newline or null byte');
+    }
+  }
+
+  // Validate the --tls-skip-verify flag at index 1 (only allowed flag)
+  if (chiselArgs[1] !== '--tls-skip-verify') {
+    throw new Error(`Invalid chiselArgs: expected --tls-skip-verify at index 1, got: ${chiselArgs[1]}`);
+  }
+
+  // Validate URL argument (3rd element)
+  if (!/^https:\/\/[a-z0-9._-]+:\d+$/.test(chiselArgs[2])) {
+    throw new Error(`Invalid chiselArgs: unexpected server URL format: ${chiselArgs[2]}`);
+  }
+
+  // Validate remaining args are R:127.0.0.1:port:127.0.0.1:port tunnel mappings.
+  // Only 127.0.0.1 is accepted to prevent binding to all interfaces or pivoting
+  // to internal network addresses via a compromised panel response.
+  for (let i = 3; i < chiselArgs.length; i++) {
+    const arg = chiselArgs[i];
+    if (/^R:127\.0\.0\.1:\d+:127\.0\.0\.1:\d+$/.test(arg)) continue;
+    throw new Error(`Invalid chiselArgs: unexpected argument at index ${i}: ${arg}`);
+  }
+}
+
+/**
+ * Generate service config text from chiselArgs.
+ * @param {string[]} chiselArgs - Chisel client argument array (e.g. ['client', '--tls-skip-verify', ...])
+ * @returns {string} Config file content (plist XML on macOS, systemd unit on Linux)
+ */
+export function generateServiceConfig(chiselArgs) {
+  validateChiselArgs(chiselArgs);
+  if (isDarwin()) {
+    return generatePlistConfig(chiselArgs);
+  }
+  return generateSystemdUnit(chiselArgs);
+}
+
+/**
+ * Write the service config file to the platform-appropriate location.
+ * @param {string} content - Config file content
+ */
+export async function writeServiceConfigFile(content) {
+  if (isDarwin()) {
+    return writePlistConfigFile(content);
+  }
+  return writeSystemdUnitFile(content);
+}
+
+// ---------------------------------------------------------------------------
+// macOS — plist
+// ---------------------------------------------------------------------------
+
+function generatePlistConfig(chiselArgs) {
+  const xmlEsc = (str) =>
+    String(str)
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;')
+      .replace(/'/g, '&apos;');
+
+  // First arg is the binary path, rest are arguments
+  const programArgs = [
+    `        <string>${xmlEsc(CHISEL_BIN_PATH)}</string>`,
+    ...chiselArgs.map((arg) => `        <string>${xmlEsc(arg)}</string>`),
+  ];
+
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>Label</key>
+    <string>com.portlama.chisel</string>
+
+    <key>ProgramArguments</key>
+    <array>
+${programArgs.join('\n')}
+    </array>
+
+    <key>KeepAlive</key>
+    <true/>
+
+    <key>RunAtLoad</key>
+    <true/>
+
+    <key>StandardOutPath</key>
+    <string>${xmlEsc(LOG_FILE)}</string>
+
+    <key>StandardErrorPath</key>
+    <string>${xmlEsc(ERROR_LOG_FILE)}</string>
+
+    <key>EnvironmentVariables</key>
+    <dict>
+        <key>PATH</key>
+        <string>/usr/local/bin:/usr/bin:/bin</string>
+    </dict>
+</dict>
+</plist>
+`;
+}
+
+async function writePlistConfigFile(content) {
+  const dir = path.dirname(PLIST_PATH);
+  await mkdir(dir, { recursive: true });
+  const tmp = PLIST_PATH + '.tmp';
+  await writeFile(tmp, content, 'utf8');
+  await rename(tmp, PLIST_PATH);
+}
+
+// ---------------------------------------------------------------------------
+// Linux — systemd
+// ---------------------------------------------------------------------------
+
+function generateSystemdUnit(chiselArgs) {
+  // Build ExecStart with proper systemd quoting (double-quote each argument)
+  const systemdQuote = (s) => `"${s.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+  const execStart = [CHISEL_BIN_PATH, ...chiselArgs].map(systemdQuote).join(' ');
+
+  return `[Unit]
+Description=Portlama Chisel Tunnel Client
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+ExecStart=${execStart}
+Restart=always
+RestartSec=5
+StandardOutput=append:${LOG_FILE}
+StandardError=append:${ERROR_LOG_FILE}
+Environment=PATH=/usr/local/bin:/usr/bin:/bin
+NoNewPrivileges=true
+ProtectSystem=strict
+ReadWritePaths=${LOGS_DIR}
+
+[Install]
+WantedBy=multi-user.target
+`;
+}
+
+async function writeSystemdUnitFile(content) {
+  // Ensure logs directory exists
+  await mkdir(LOGS_DIR, { recursive: true });
+
+  const tmp = SYSTEMD_UNIT_PATH + '.tmp';
+  await writeFile(tmp, content, { encoding: 'utf8', mode: 0o644 });
+  await rename(tmp, SYSTEMD_UNIT_PATH);
+
+  // Reload systemd so it picks up the new/changed unit file
+  await execa('systemctl', ['daemon-reload']);
+}

package/src/lib/service.js

@@ -0,0 +1,102 @@
+/**
+ * Unified service management interface.
+ *
+ * Dispatches to launchctl (macOS) or systemctl (Linux) based on process.platform.
+ */
+
+import { execa } from 'execa';
+import { isDarwin } from './platform.js';
+
+// Lazy imports for macOS-specific modules to avoid loading them on Linux
+
+/**
+ * Check if the agent service is currently loaded/active.
+ * @returns {Promise<boolean>}
+ */
+export async function isAgentLoaded() {
+  if (isDarwin()) {
+    const { isAgentLoaded: macIsLoaded } = await import('./launchctl.js');
+    return macIsLoaded();
+  }
+  return systemctlIsActive();
+}
+
+/**
+ * Get the PID of the running agent, or null if not running.
+ * @returns {Promise<number | null>}
+ */
+export async function getAgentPid() {
+  if (isDarwin()) {
+    const { getAgentPid: macGetPid } = await import('./launchctl.js');
+    return macGetPid();
+  }
+  return systemctlGetPid();
+}
+
+/**
+ * Load/start the agent service.
+ */
+export async function loadAgent() {
+  if (isDarwin()) {
+    const { loadAgent: macLoad } = await import('./launchctl.js');
+    return macLoad();
+  }
+  return systemctlStart();
+}
+
+/**
+ * Unload/stop the agent service. Silent if not loaded.
+ */
+export async function unloadAgent() {
+  if (isDarwin()) {
+    const { unloadAgent: macUnload } = await import('./launchctl.js');
+    return macUnload();
+  }
+  return systemctlStop();
+}
+
+// ---------------------------------------------------------------------------
+// Linux / systemd helpers
+// ---------------------------------------------------------------------------
+
+async function systemctlIsActive() {
+  try {
+    await execa('systemctl', ['is-active', '--quiet', 'portlama-chisel']);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function systemctlGetPid() {
+  try {
+    const { stdout } = await execa('systemctl', [
+      'show',
+      '-p',
+      'MainPID',
+      '--value',
+      'portlama-chisel',
+    ]);
+    const pid = parseInt(stdout.trim(), 10);
+    return Number.isNaN(pid) || pid <= 0 ? null : pid;
+  } catch {
+    return null;
+  }
+}
+
+async function systemctlStart() {
+  try {
+    await execa('systemctl', ['daemon-reload']);
+    await execa('systemctl', ['enable', '--now', 'portlama-chisel']);
+  } catch (err) {
+    throw new Error(`Failed to start agent: ${err.stderr || err.message}`);
+  }
+}
+
+async function systemctlStop() {
+  try {
+    await execa('systemctl', ['disable', '--now', 'portlama-chisel']);
+  } catch {
+    // Agent may not be active — this is fine
+  }
+}

package/src/lib/plist.js

@@ -1,34 +0,0 @@
-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);
-}