CLI reference

The osmRouter CLI is a single static binary configured entirely through environment variables. Only OSM_TOKEN is required.

Install

# macOS / Linux
curl -fsSL https://osmrouter.com/install.sh | sh
osmrouter version

# Windows (PowerShell)
irm https://osmrouter.com/install.ps1 | iex

The installers verify the download's SHA-256 checksum and abort on a mismatch. Set OSM_BINDIR to change the install location, or OSM_VERSION to pin a version. See Install for details.

Commands

Command	Description
`osmrouter http <port>`	Expose a local HTTP service at a public HTTPS URL.
`osmrouter tcp <port>`	Expose a raw TCP service at `tunnel.<domain>:<port>`.
`osmrouter version`	Print the installed CLI version.
`osmrouter help`	Show usage and available commands.

http

Forwards a local port to a public https:// URL. The machine dials out to the relay, so nothing needs to be open on your firewall, NAT, or CGNAT.

osmrouter http 8080
# -> https://<random-name>.osmrouter.com  ->  http://localhost:8080

TLS is terminated for you at the edge, so visitors always reach you over HTTPS. Plain HTTP/HTTPS, WebSockets, SSE, chunked/streaming responses, and long-running requests (no wall-clock timeout) all pass through transparently.

Pin a subdomain

OSM_SUBDOMAIN=my-app osmrouter http 8080
# -> https://my-app.osmrouter.com

Protect with Basic Auth

Gate an HTTP tunnel behind a username and password, enforced at the edge before any request reaches your local service:

OSM_BASIC_AUTH=alice:s3cret osmrouter http 8080

Visitors without valid credentials get a 401.

tcp

Expose a raw TCP service — a database, SSH, a game server — at a public tunnel.<domain>:<port>. The port is allocated for you:

osmrouter tcp 5432
# -> tunnel.osmrouter.com:10000  ->  localhost:5432

Connect to it like any TCP endpoint, e.g.:

psql "host=tunnel.osmrouter.com port=10000 user=postgres"

TCP tunnels count toward your plan's concurrent-tunnel limit. UDP is on the roadmap.

Environment variables

Variable	Required	Default	Description
`OSM_TOKEN`	Yes	—	Agent token used to authenticate. Create one under Tokens (`osm_xxxxx`).
`OSM_DOMAIN`	No	`osmrouter.com`	Apex domain your public URLs are served under. Set to a verified custom domain.
`OSM_SUBDOMAIN`	No	random	Pin a specific subdomain instead of a random name (http only).
`OSM_BASIC_AUTH`	No	—	Protect an HTTP tunnel with Basic Auth, as `user:pass`.
`OSM_API`	No	`https://api.<domain>`	Control-plane API, used to allocate a port for tcp tunnels.
`OSM_RELAY`	No	`tunnel.osmrouter.com:8443`	Advanced. The relay endpoint to dial. Change only when self-hosting.

OSM_DOMAIN must be a domain you've added and verified under Domains before tunnels can bind to it.

Examples

Expose a local dev server:

export OSM_TOKEN=osm_xxxxx
osmrouter http 3000

Stable URL for webhooks:

OSM_SUBDOMAIN=stripe-hooks osmrouter http 4242
# -> https://stripe-hooks.osmrouter.com

Serve a local LLM (streaming, no timeout):

OSM_SUBDOMAIN=llm osmrouter http 11434
# -> https://llm.osmrouter.com/v1/chat/completions

Use a verified custom domain:

OSM_DOMAIN=example.com OSM_SUBDOMAIN=api osmrouter http 8080
# -> https://api.example.com

Point at a self-hosted relay:

OSM_RELAY=tunnel.example.com:8443 \
OSM_DOMAIN=example.com \
osmrouter http 8080

Keep OSM_TOKEN secret. Anyone with it can open tunnels on your account. Revoke a leaked token under Tokens and create a new one.

On this page