Moln.ai Tunnels

This is a network tunnel manager tool mainly intended to be used as part of the (Moln.ai)[https://moln.ai] service and/or via terminal CLI TUI. It keeps tunnel definitions in ~/.config/moln-tunnels.json, and starts tunnel commands (based on parameterized SSH, AWS SSM etc) as detached background processes. This is convenient when working - manually or through automation scripts - with servers such as Kubernetes, databases and virtual machines when they are protected behind bastion hosts or other multi-step network hops.

Features

• Interactive TUI (npx moln-tunnels) to toggle tunnels and confirm config changes pushed from the web UI.
• Protected local API consumed by moln.ai to manage config and start/stop tunnels.
• Background tunnel processes with health checks and PID tracking.
• Built-in configurations: SSH port forward, AWS SSM port forward, AWS EC2 instance ID lookup, generic string helpers.

Security

• Moln-tunnels config should not be used to store any secrets - it is only intended to use pre-existing credentials by invoking ssh/aws/az tools
• By using a CORS allow-list, your browser will only allow the website moln.ai to contact your local moln-tunnels configuration
• You may additionally set a security passphrase used to authorize any reqeusts into your local moln-tunnels.
• The moln-tunnels endpoint allows without confirmation to: start/stop existing tunnels, read names of AWS profiles, read tunnel configs
• When you create/edit tunnels via moln.ai, your local terminal UI requires you to manually confirm the updated config

Installation

• Prereqs: Node 18+, ssh, and aws with session manager plugin.
• Via npm: npx moln-tunnels starts a TUI in your terminal.

Usage

• Default (TUI + API server): npx moln-tunnels
  • Starts the moln-tunnel tool, ready to start tunnels and their periodic health checks
  • Displays the terminal UI (TUI) (quit with q).
  • Also starts a local API on http://localhost:30720 with CORS protection, used by your browser on moln.ai to manage your tunnels
• Start a tunnel in the background: npx moln-tunnels start <name>
  • Spawns the tunnel detached; the CLI exits immediately while the tunnel keeps running.
• Stop a tunnel: npx moln-tunnels stop <name>
• List tunnels and status: npx moln-tunnels list

With the web UI (apps/moln-web)

1. Run npx moln-tunnels to bring up the terminal interface and management endpoint.
2. Open the Tunnels page in the web app; it will read/write config via http://localhost:30720.
3. When the web UI proposes a config change, approve/deny it in the terminal TUI.

Configuration

• File: ~/.config/moln-tunnels.json
• Shape:

{
  "tunnels": [
    {
      "name": "db-ssm",
      "description": "[DEV] Tunnel via bastion host to RDS", // <-- Change
      "tool": {
        "toolId": "aws-ssm",
        "type": "create-tunnel",
        "params": {
          // The AWS SSM target param can be a hardcoded EC2 id (string), 
          // or use a tool (object) to look it up such as this:
          "target": { 
            "toolId": "aws-ec2-get-id",
            "type": "provide-string",
            "params": {
              "filterName": "name-of-my-EC2-bastion-host-dev", // <-- Change
              "filterState": "running",
              "region": "eu-north-1",
              "profile": "my-aws-profile-dev" // <-- Change
            }
          },
          "localPort": 31001, // Connect to the database via your localhost:31001
          "remoteHost": "hostname-of-my-RDS-dev",
          "remotePort": 5432, // Default PostgreSQL port, on target RDS server
          "region": "eu-north-1",
          "profile": "my-aws-profile-dev" // <-- Change
        }
      },
      // The health-check also serves as a keep-alive
      "healthCheck": { "type": "tcp", "host": "localhost", "port": 31001, "interval": 5 }, 
      "dependsOn": null,
      "pid": null,
      "status": "off"
    }
  ],
  "allowGenericCommands": false
}

• tool.toolId options: ssh, aws-ssm, aws-ec2-get-id (string provider), grep, generic-command (requires allowGenericCommands: true).
• Health checks: TCP connect to host:port every interval seconds; status flips to on once healthy.
• Dependencies: set dependsOn to start another tunnel first.

License

Licensed under the PolyForm Shield License 1.0.0. This project is source-available and free to use, distribute, and modify for internal commercial purposes.

• ✅ You may use this tool internally in a commercial setting on your computers/servers/pipelines via moln.ai or CLI.
• ✅ While doing so, you may modify/extend/redistribute this work internal in order to improve your use of this tool.
• ✅ You may publicly document and/or suggest to others to use this tool - incl. providing tunnel configurations - for commercial reasons.
• ❌ You may not fork, rework, rebrand or republish this work as part of a competing product or service to moln.ai nor its owner's or partners' businesses.

For alternative Enterprise licencing, contact [email protected]