Menu
Set up and manage ngrok-based public ingress for local assistants; do not use this in managed mode when platform callback routing is available
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Read, search, send, and manage messages across Gmail, Outlook, Telegram, and other platforms
An on-demand personal daily briefing — weather, headlines, the shape of your day, and one thing worth your attention — in a sharp executive-assistant voice. The general-purpose morning brief; richer work or admin digests compose it as their general layer.
One-time migration of an existing memory-v2 concept corpus into the memory-v3 section-grain "wiki" — topical articles with a stand-alone lead and queryable sections — with loss-proof staging, assistant-reviewed authoring, and a retrieval-eval gate before cutover.
Delegate a big or high-stakes job to a fleet of parallel subagents, orchestrated deterministically; runs unattended and reports back
Manage contacts, communication channels, access control, and invite links
Build and edit small, personal visual tools and artifacts — dashboards, trackers, calculators, data visualizations, charts, simple landing pages, and slide decks the user wants for THEMSELVES. This is the right skill whenever the user asks to "visualize this," "make a chart," or "build an artifact" for their own use, or to edit an app they already built here. Do NOT reach for a ui_show dynamic_page to fake an artifact — build a real persistent app here. NOT for complex, multi-user, or shippable products — those go to a real project folder with a coding agent (see Scope below).
| name | public-ingress |
| description | Set up and manage ngrok-based public ingress for local assistants; do not use this in managed mode when platform callback routing is available |
| compatibility | Designed for Vellum personal assistants |
| metadata | {"emoji":"🌍","vellum":{"category":"system","display-name":"Public Ingress","activation-hints":["Local assistant needs a public webhook or OAuth callback URL","ngrok tunnel setup for a non-managed assistant"],"avoid-when":["Running in a platform-managed assistant with platform callback routing available"]}} |
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.
The Vellum gateway listens locally and needs a publicly reachable URL for:
This skill installs ngrok, configures authentication, starts a tunnel, discovers the public URL, and saves it to the assistant's ingress config.
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.
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 enabledIf 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.
Check if ngrok is installed:
ngrok version
If not installed, install it:
macOS (Homebrew):
brew install ngrok/ngrok/ngrok
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.
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)"
If no value is returned, re-run assistant credentials prompt and try again.
Verify authentication succeeded by checking ngrok config check again.
Before starting, check for an existing ngrok process to avoid duplicates:
curl -s http://127.0.0.1:4040/api/tunnels 2>/dev/null
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
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
Wait a few seconds for the tunnel to establish:
sleep 3
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]+$'
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 (
pkill -f ngrok), then re-run this skill to start ngrok on the correct port.
If the ports match, proceed silently to Step 5.
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.
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
Summarize the setup:
<the-url> (this is your ingress.publicBaseUrl)$INTERNAL_GATEWAY_BASE_URLProvide useful follow-up commands:
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']]"cat /tmp/ngrok.logpkill -f ngrok; sleep 1; nohup ngrok http "$INTERNAL_GATEWAY_BASE_URL" --log=stdout > /tmp/ngrok.log 2>&1 &pkill -f ngrokingress.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).
Run the install commands in Step 2. On macOS, make sure Homebrew is installed first (brew --version).
Sign in to https://dashboard.ngrok.com, copy a fresh token from the "Your Authtoken" page, and re-run Step 3.
The ngrok process may not be running. Check with ps aux | grep ngrok. If not running, start it per Step 4. If running but 4040 is unresponsive, check /tmp/ngrok.log for errors.
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.
ngrok's free tier allows one tunnel at a time. Stop any other ngrok tunnels before starting a new one.
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 (pkill -f ngrok), verify the gateway URL with echo $INTERNAL_GATEWAY_BASE_URL, then re-run this skill to start ngrok on the correct port.
If after killing the ngrok process, it automatically re-spawns and is still attached to the incorrect port, check to see if there is a launch agent process configured to auto-restart it. This might exist at ~/Library/LaunchAgents/com.ngrok.tunnel.plist. If so, it needs to be either removed or updated.