ngrok

The ngrok agent is a lightweight command-line program that forwards traffic from endpoints on the ngrok cloud service to your upstream services.

Runs as ngrok|macOS, Linux, Windows|ngrok.com

Open form in Otty otty.toml

Sync rules

What travels, what stays, what never leaves

ngrok in your home directory Every rule on this page, by file

authtokenapi_keyagent.authtokenagent.api_key

Lifted into your secret store; the rest of the file syncs.

authtokenapi_keyagent.authtokenagent.api_key

Lifted into your secret store; the rest of the file syncs.

authtokenapi_keyagent.authtokenagent.api_key

Lifted into your secret store; the rest of the file syncs.

Only what the catalog names. A directory that syncs brings everything inside it except what is listed as excluded here.

apps/ngrok/otty.tomlThe file this page is generated from

id = "ngrok"

name = "ngrok"

homepage = "https://ngrok.com"

description = "The ngrok agent is a lightweight command-line program that forwards traffic from endpoints on the ngrok cloud service to your upstream services."

icon = "SimpleIcons:ngrok"

executables = ["ngrok"]

[dotfiles]

# https://ngrok.com/docs/agent/config/ gives the default config file as

# ~/.config/ngrok/ngrok.yml on Linux, ~/Library/Application Support/ngrok/ngrok.yml

# on macOS and %LocalAppData%\ngrok\ngrok.yml on Windows. ngrok 2 kept it in

# ~/.ngrok2/ngrok.yml on every platform (%HOMEPATH%\.ngrok2\ngrok.yml on

# Windows, which resolves to the same ~/ path). The v3 agent still reads that

# file where it exists — it warns "ngrok config file found at legacy location,

# move to XDG location" and offers `ngrok config upgrade --relocate`

# (https://ngrok.com/docs/agent/upgrade-v2-v3/) — so it is listed too; a

# consumer skips whichever is absent.

paths = [

"~/Library/Application Support/ngrok/ngrok.yml",

"~/.config/ngrok/ngrok.yml",

"%LOCALAPPDATA%/ngrok/ngrok.yml",

"~/.ngrok2/ngrok.yml",

]

exclude = []

# The file is not a whole-file secret: the endpoint and tunnel definitions,

# the region, the proxy settings and the web-UI address are the parts worth

# carrying between machines. Only the two credentials are lifted out.

secret = []

side_effect = false

# Every spelling, or the credentials are lifted out on one platform and sync

# in the clear from the others.

# Both shapes the agent has written: version 2 files put authtoken and api_key

# at the top level (https://ngrok.com/docs/agent/config/v2/), and the version 3

# format moved them under `agent`

# (https://ngrok.com/docs/agent/config/v3/: "agent:\n authtoken: ...",

# "agent:\n api_key: ..."). A rule naming only the current one would resolve

# to nothing on a file still in the old shape — and for a credential that means

# syncing it in the clear.

[[dotfiles.secret_paths]]

file = [

"~/Library/Application Support/ngrok/ngrok.yml",

"~/.config/ngrok/ngrok.yml",

"%LOCALAPPDATA%/ngrok/ngrok.yml",

"~/.ngrok2/ngrok.yml",

]

match = { key_path = ["authtoken", "api_key", "agent.authtoken", "agent.api_key"] }

[commands]

format = 1

label = "ngrok"

description = "Global options only; use the HTTP and TCP subcommands. Config-file tunnels (start) are left out."

quality = "ai-draft"

base = "fig:ngrok"

parser = { end_of_options = "--", interleave = "permute", long_equals = true, short_attached = false, short_bundles = false }

[[commands.source]]

id = "fig"

kind = "completion"

url = "https://github.com/withfig/autocomplete/blob/master/src/ngrok.ts"

license = "MIT"

[[commands.subcommand]]

path = ["http"]

label = "HTTP tunnel"

description = "Expose a local HTTP port or host."

[[commands.subcommand.source]]

id = "fig"

kind = "completion"

url = "https://github.com/withfig/autocomplete/blob/master/src/ngrok.ts"

license = "MIT"

[[commands.subcommand.field]]

id = "host"

label = "Port or host"

type = "string"

position = 0

suggestions = [{ value = "8080", label = "8080" }]

sources = ["fig"]

[[commands.subcommand.field]]

id = "hostname"

label = "Custom hostname"

type = "string"

option = ["--hostname"]

sources = ["fig"]

[[commands.subcommand.field]]

id = "subdomain"

label = "Custom subdomain"

type = "string"

option = ["--subdomain"]

sources = ["fig"]

[[commands.subcommand.field]]

id = "auth"

label = "Basic auth (user:password)"

type = "string"

option = ["--auth"]

sources = ["fig"]

[[commands.subcommand.field]]

id = "bind_tls"

label = "Listen for"

type = "enum"

option = ["--bind-tls"]

choices = [{ value = "true", label = "true" }, { value = "false", label = "false" }, { value = "both", label = "both" }]

sources = ["fig"]

[[commands.subcommand.field]]

id = "host_header"

label = "Host header"

type = "string"

option = ["--host-header"]

suggestions = [{ value = "rewrite", label = "rewrite" }]

sources = ["fig"]

[[commands.subcommand.field]]

id = "config"

label = "Config file"

type = "path"

option = ["--config"]

path = { kind = "file", role = "input" }

sources = ["fig"]

[[commands.subcommand.field]]

id = "region"

label = "Region"

type = "enum"

option = ["--region"]

choices = [{ value = "us", label = "us" }, { value = "eu", label = "eu" }, { value = "au", label = "au" }, { value = "ap", label = "ap" }, { value = "sa", label = "sa" }, { value = "jp", label = "jp" }, { value = "in", label = "in" }]

sources = ["fig"]

[[commands.subcommand.field]]

id = "log_level"

label = "Log level"

type = "enum"

option = ["--log-level"]

choices = [{ value = "crit", label = "crit" }, { value = "warn", label = "warn" }, { value = "error", label = "error" }, { value = "info", label = "info" }, { value = "debug", label = "debug" }]

sources = ["fig"]

[[commands.subcommand.field]]

id = "log_format"

label = "Log format"

type = "enum"

option = ["--log-format"]

choices = [{ value = "term", label = "term" }, { value = "logfmt", label = "logfmt" }, { value = "json", label = "json" }]

sources = ["fig"]

[[commands.subcommand.field]]

id = "log"

label = "Log destination"

type = "string"

option = ["--log"]

suggestions = [{ value = "stdout", label = "stdout" }, { value = "stderr", label = "stderr" }, { value = "false", label = "false" }]

sources = ["fig"]

[[commands.subcommand.task]]

id = "http"

label = "Expose port"

fields = ["host", "region"]

required = ["host"]

[[commands.subcommand.task]]

id = "http-domain"

label = "Custom subdomain"

fields = ["host", "subdomain", "region"]

required = ["host", "subdomain"]

[[commands.subcommand.group]]

id = "basic"

label = "Basic"

fields = ["host", "hostname", "subdomain", "region"]

[[commands.subcommand.group]]

id = "advanced"

label = "Advanced"

fields = ["auth", "bind_tls", "host_header", "config", "log_level", "log_format", "log"]

[[commands.subcommand]]

path = ["tcp"]

label = "TCP tunnel"

description = "Expose a local TCP port."

[[commands.subcommand.source]]

id = "fig"

kind = "completion"

url = "https://github.com/withfig/autocomplete/blob/master/src/ngrok.ts"

license = "MIT"

[[commands.subcommand.field]]

id = "port"

label = "Port"

type = "string"

position = 0

suggestions = [{ value = "22", label = "22" }]

sources = ["fig"]

[[commands.subcommand.field]]

id = "remote_addr"

label = "Reserved remote address"

type = "string"

option = ["--remote-addr"]

sources = ["fig"]

[[commands.subcommand.field]]

id = "config"

label = "Config file"

type = "path"

option = ["--config"]

path = { kind = "file", role = "input" }

sources = ["fig"]

[[commands.subcommand.field]]

id = "region"

label = "Region"

type = "enum"

option = ["--region"]

sources = ["fig"]

[[commands.subcommand.field]]

id = "log_level"

label = "Log level"

type = "enum"

option = ["--log-level"]

choices = [{ value = "crit", label = "crit" }, { value = "warn", label = "warn" }, { value = "error", label = "error" }, { value = "info", label = "info" }, { value = "debug", label = "debug" }]

sources = ["fig"]

[[commands.subcommand.field]]

id = "log_format"

label = "Log format"

type = "enum"

option = ["--log-format"]

choices = [{ value = "term", label = "term" }, { value = "logfmt", label = "logfmt" }, { value = "json", label = "json" }]

sources = ["fig"]

[[commands.subcommand.field]]

id = "log"

label = "Log destination"

type = "string"

option = ["--log"]

suggestions = [{ value = "stdout", label = "stdout" }, { value = "stderr", label = "stderr" }, { value = "false", label = "false" }]

sources = ["fig"]

[[commands.subcommand.task]]

id = "tcp"

label = "Expose port"

fields = ["port", "region"]

required = ["port"]

[[commands.subcommand.group]]

id = "basic"

label = "Basic"

fields = ["port", "remote_addr", "region"]

[[commands.subcommand.group]]

id = "advanced"

label = "Advanced"

fields = ["config", "log_level", "log_format", "log"]

Use it with your dotfile manager

Same data, in the shape your tool already reads

Opens Otty and adds this tool to what it syncs

Opens otty://sync/add/ngrok. Otty ships with this catalog, so the link only has to name the tool — nothing is downloaded.

Every one of these is generated from the same rules as this page.