vellum-ai 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:
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."
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"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 $tokenIf no value is returned, re-run
assistant credentials promptand 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 youringress.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.publicBaseUrlafterward)
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.