public-ingress

You are setting up and managing a public ingress tunnel so that external services (Telegram webhooks, OAuth callbacks, etc.) can reach the local Vellum gateway. This skill uses ngrok to create a secure tunnel and persists the public URL as ingress.publicBaseUrl.

If managed platform callback routing is available, stop and do not continue with ngrok. In platform-managed deployments, Telegram/Twilio/OAuth callback routing should use the platform callback route flow instead of local public ingress.

Overview

The Vellum gateway listens locally and needs a publicly reachable URL for:

• Telegram webhook delivery
• Google/Slack OAuth redirect callbacks
• Any other inbound webhook traffic

This skill installs ngrok, configures authentication, starts a tunnel, discovers the public URL, and saves it to the assistant's ingress config.

On Windows, use the PowerShell blocks instead of the POSIX ones.

Step 0: Reject Managed Callback Environments

Check whether managed platform callback routing is available:

assistant platform status --json

If the result shows isPlatform: true and available: true, stop here. Tell the user that this assistant should use the platform callback route flow instead of ngrok, and do not install or start ngrok.

Step 1: Check Current Ingress Status

First, check whether ingress is already configured:

assistant config get ingress.publicBaseUrl
assistant config get ingress.enabled

The local gateway URL is available as the $INTERNAL_GATEWAY_BASE_URL environment variable (defaults to http://127.0.0.1:7830).

The commands return:

• ingress.publicBaseUrl - currently configured public ingress URL (if any)
• ingress.enabled - whether ingress is enabled

If publicBaseUrl is already set and the tunnel is running (check via curl -s http://127.0.0.1:4040/api/tunnels), tell the user the current status and ask if they want to reconfigure or if this is sufficient.

On Windows, check the tunnel with:

Invoke-RestMethod http://127.0.0.1:4040/api/tunnels

Step 2: Install ngrok

Check if ngrok is installed:

ngrok version

If not installed, install it:

macOS (Homebrew):

brew install ngrok/ngrok/ngrok

Windows (Microsoft Store via WinGet):

winget install ngrok -s msstore

Linux (snap):

sudo snap install ngrok

Linux (apt - alternative):

curl -sSL https://ngrok-agent.s3.amazonaws.com/ngrok.asc | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null
echo "deb https://ngrok-agent.s3.amazonaws.com buster main" | sudo tee /etc/apt/sources.list.d/ngrok.list
sudo apt update && sudo apt install ngrok

After installation, verify with ngrok version.

Step 3: Authenticate ngrok

Check if ngrok already has an auth token configured:

ngrok config check

If not authenticated:

1. Tell the user: "You need an ngrok account to create tunnels. If you don't have one, sign up at https://dashboard.ngrok.com/signup - it's free."

2. Once they have an account, run assistant credentials prompt (via the bash tool) to securely collect their auth token. Never ask the user to paste the token directly in chat.

   assistant credentials prompt --service ngrok --field authtoken \
     --label "ngrok Auth Token" \
     --description "Get your auth token from https://dashboard.ngrok.com/get-started/your-authtoken" \
     --usage-description "ngrok authentication token for creating public tunnels"

3. Once the credential is stored, reveal it and apply it to ngrok:

   ngrok config add-authtoken "$(assistant credentials reveal --service ngrok --field authtoken)"

   On Windows:

   $token = assistant credentials reveal --service ngrok --field authtoken
   ngrok config add-authtoken $token

   If no value is returned, re-run assistant credentials prompt and try again.

Verify authentication succeeded by checking ngrok config check again.

Step 4: Start the Tunnel

Before starting, check for an existing ngrok process to avoid duplicates:

curl -s http://127.0.0.1:4040/api/tunnels 2>/dev/null

On Windows:

Invoke-RestMethod http://127.0.0.1:4040/api/tunnels -ErrorAction SilentlyContinue

If a tunnel is already running, check whether it points to the correct local target. If so, skip to Step 5. If it points elsewhere, stop it first:

pkill -f ngrok || true
sleep 1

On Windows:

Get-Process ngrok -ErrorAction SilentlyContinue | Stop-Process
Start-Sleep -Seconds 1

Start ngrok in the background tunneling to the local gateway URL:

nohup ngrok http "$INTERNAL_GATEWAY_BASE_URL" --log=stdout > /tmp/ngrok.log 2>&1 &
echo $! > /tmp/ngrok.pid

On Windows:

$logPath = Join-Path $env:TEMP "ngrok.log"
$errorLogPath = Join-Path $env:TEMP "ngrok-error.log"
Start-Process ngrok -ArgumentList @("http", $env:INTERNAL_GATEWAY_BASE_URL, "--log=stdout") -RedirectStandardOutput $logPath -RedirectStandardError $errorLogPath -WindowStyle Hidden

Wait a few seconds for the tunnel to establish.

Step 4b: Verify Port Alignment

Before discovering the public URL, verify that ngrok is forwarding to the same port the gateway is actually listening on. A mismatch here causes silent failures - webhooks appear to be delivered but never reach the gateway.

Query the ngrok tunnel's target port and the gateway's configured port, then compare them:

curl -s http://127.0.0.1:4040/api/tunnels | python3 -c "
import sys, json, re

data = json.load(sys.stdin)
tunnels = data.get('tunnels', [])
if not tunnels:
    print('ERROR: no active ngrok tunnel found')
    sys.exit(1)

addr = tunnels[0].get('config', {}).get('addr', '')
match = re.search(r':(\d+)$', addr)
if not match:
    print(f'ERROR: could not extract port from ngrok tunnel addr: {addr}')
    sys.exit(1)

print(match.group(1))
"

echo "$INTERNAL_GATEWAY_BASE_URL" | grep -oE '[0-9]+$'

On Windows, resolve both ports without using the POSIX snippets:

$tunnel = (Invoke-RestMethod http://127.0.0.1:4040/api/tunnels).tunnels[0]
$tunnelPort = ([uri]$tunnel.config.addr).Port
$gatewayPort = ([uri]$env:INTERNAL_GATEWAY_BASE_URL).Port
@{ tunnelPort = $tunnelPort; gatewayPort = $gatewayPort }

Compare the two port numbers. If they differ, warn the user:

Port mismatch detected: ngrok is forwarding to port X but the gateway is listening on port Y. Webhooks will not reach the gateway. Stop ngrok (Step 4), then re-run this skill to start ngrok on the correct port.

If the ports match, proceed silently to Step 5.

Step 5: Discover the Public URL

Query the ngrok local API for the tunnel's public URL:

curl -s http://127.0.0.1:4040/api/tunnels | python3 -c "
import sys, json
data = json.load(sys.stdin)
tunnels = data.get('tunnels', [])
for t in tunnels:
    url = t.get('public_url', '')
    if url.startswith('https://'):
        print(url)
        sys.exit(0)
for t in tunnels:
    url = t.get('public_url', '')
    if url:
        print(url)
        sys.exit(0)
print('ERROR: no tunnel found')
sys.exit(1)
"

If no tunnel is found, check /tmp/ngrok.log for errors and report them to the user.

On Windows, discover the URL and inspect the logs with:

$tunnel = (Invoke-RestMethod http://127.0.0.1:4040/api/tunnels).tunnels | Where-Object { $_.public_url -like "https://*" } | Select-Object -First 1
$tunnel.public_url
Get-Content (Join-Path $env:TEMP "ngrok.log") -ErrorAction SilentlyContinue
Get-Content (Join-Path $env:TEMP "ngrok-error.log") -ErrorAction SilentlyContinue

Step 6: Persist the Ingress Setting

Save the discovered public URL and enable ingress:

assistant config set ingress.publicBaseUrl "<public-url>"
assistant config set ingress.enabled true

Verify it was saved:

assistant config get ingress.publicBaseUrl
assistant config get ingress.enabled

Step 7: Report Completion

Summarize the setup:

• Public URL: <the-url> (this is your ingress.publicBaseUrl)
• Local gateway target: $INTERNAL_GATEWAY_BASE_URL
• ngrok dashboard: http://127.0.0.1:4040

Provide useful follow-up commands:

• Check tunnel status: curl -s http://127.0.0.1:4040/api/tunnels | python3 -c "import sys,json; [print(t['public_url']) for t in json.load(sys.stdin)['tunnels']]"
• View ngrok logs: cat /tmp/ngrok.log
• Restart tunnel: pkill -f ngrok; sleep 1; nohup ngrok http "$INTERNAL_GATEWAY_BASE_URL" --log=stdout > /tmp/ngrok.log 2>&1 &
• Stop tunnel: pkill -f ngrok
• Rotate URL: Stop and restart ngrok (free tier assigns a new URL each time; update ingress.publicBaseUrl afterward)

Important: On ngrok's free tier, the public URL changes every time the tunnel restarts. After restarting, re-run this skill or manually update ingress.publicBaseUrl and any registered webhooks (e.g., Telegram).

Troubleshooting

ngrok not installed

Run the install commands in Step 2. On macOS, make sure Homebrew is installed first (brew --version).

Auth token invalid or expired

Sign in to https://dashboard.ngrok.com, copy a fresh token from the "Your Authtoken" page, and re-run Step 3.

ngrok API (port 4040) not responding

The ngrok process may not be running. On macOS or Linux, check with ps aux | grep ngrok. On Windows, use Get-Process ngrok -ErrorAction SilentlyContinue. If it is not running, start it per Step 4. If it is running but port 4040 is unresponsive, check /tmp/ngrok.log ($env:TEMP\ngrok.log on Windows) for errors.

Gateway not reachable on local target

Re-check the local gateway target with echo $INTERNAL_GATEWAY_BASE_URL. Run curl -s "$INTERNAL_GATEWAY_BASE_URL/healthz" to verify it is reachable. If the gateway is not running, start the assistant first.

On Windows, use $env:INTERNAL_GATEWAY_BASE_URL and Invoke-RestMethod "$env:INTERNAL_GATEWAY_BASE_URL/healthz".

"Too many connections" or tunnel limit errors

ngrok's free tier allows one tunnel at a time. Stop any other ngrok tunnels before starting a new one.

ngrok port doesn't match gateway port

Symptom: Webhooks return connection refused or timeouts even though both ngrok and the gateway appear to be running.

Cause: ngrok is forwarding to a different port than the gateway is listening on. This can happen if the gateway port was changed after ngrok was started, or if ngrok was started manually with a hardcoded port.

Fix: Stop ngrok (Step 4), verify the gateway URL with echo $INTERNAL_GATEWAY_BASE_URL, then re-run this skill to start ngrok on the correct port.

ngrok automatically restarts with wrong port

On macOS, if the ngrok process automatically re-spawns on the incorrect port, check for a launch agent at ~/Library/LaunchAgents/com.ngrok.tunnel.plist. If it exists, remove or update it.