Configuration

If you're just sharing one thing on your computer, the CLI is all you need — a single command does it. This page is for when one command isn't enough: a web app and a database, a homelab with half a dozen services, a fleet of devices that should all come up together. Write them down in a YAML file once, then bring everything up with one command.

Quick start

Create a file called localport.yaml:

version: 1
spec:
  token: YOUR_TOKEN
  endpoints:
    - name: web
      url: localhost:3000

Run it:

localport --config localport.yaml

Localport connects your local service and gives you a public URL. Add more endpoints to tunnel multiple services at once.

File structure

Every configuration file starts with version: 1 and contains either a single spec or multiple specs.

Single spec

Use spec when all your endpoints share the same tunnel token:

version: 1
spec:
  token: ${env.LOCALPORT_TOKEN}
  region: eu
  endpoints:
    - name: api
      proto: http
      url: localhost:8080
    - name: database
      proto: tcp
      url: localhost:5432

Multiple specs

Use specs when you need different tokens or regions:

version: 1
specs:
  - token: ${env.EU_TOKEN}
    region: eu
    endpoints:
      - name: eu-api
        proto: http
        url: localhost:8080
  - token: ${env.US_TOKEN}
    region: us
    endpoints:
      - name: us-worker
        proto: tcp
        url: localhost:9090

You must use exactly one of spec or specs — not both.

Field reference

Spec fields

Field	Required	Default	Description
token	Yes	—	Tunnel authentication token from the dashboard
region	No	default endpoint	Edge region: eu, us, or ap. Omit to use Localport's default endpoint.
endpoints	No	—	One or more endpoint definitions (see below)

Endpoint fields

Field	Required	Default	Description
name	Yes	—	Display label for this endpoint
url	Yes	—	Local service address (host:port)
proto	No	http	Protocol: http, tcp, or tls

Using environment variables

Use ${env.VARIABLE_NAME} anywhere in your configuration to reference environment variables. This keeps tokens and secrets out of your config files.

version: 1
spec:
  token: ${env.LOCALPORT_TOKEN}
  endpoints:
    - name: web
      url: localhost:3000

export LOCALPORT_TOKEN=tok_abc123
localport --config localport.yaml

All referenced variables must be set and non-empty when Localport starts. If any variable is missing, Localport shows an error telling you which ones are unresolved.

Examples

Web application

The simplest configuration — one HTTP tunnel to a local dev server:

version: 1
spec:
  token: ${env.LOCALPORT_TOKEN}
  endpoints:
    - name: web
      url: localhost:3000

Full-stack application

Tunnel both your API and database from a single config:

version: 1
spec:
  token: ${env.LOCALPORT_TOKEN}
  region: eu
  endpoints:
    - name: api
      proto: http
      url: localhost:8080
    - name: postgres
      proto: tcp
      url: localhost:5432

Microservices across regions

Route services to the regions closest to their users with separate tokens:

version: 1
specs:
  - token: ${env.EU_TOKEN}
    region: eu
    endpoints:
      - name: auth-service
        proto: http
        url: localhost:4000
      - name: payment-service
        proto: http
        url: localhost:4001
  - token: ${env.US_TOKEN}
    region: us
    endpoints:
      - name: analytics
        proto: http
        url: localhost:5000
      - name: redis
        proto: tcp
        url: localhost:6379

Game server

Expose a Minecraft or Valheim server over TCP:

version: 1
spec:
  token: ${env.LOCALPORT_TOKEN}
  region: us
  endpoints:
    - name: minecraft
      proto: tcp
      url: localhost:25565

IoT device fleet

Tunnel multiple services from an edge device or Raspberry Pi:

version: 1
spec:
  token: ${env.IOT_TOKEN}
  region: ap
  endpoints:
    - name: sensor-hub
      proto: http
      url: localhost:8088
    - name: mqtt-bridge
      proto: tcp
      url: localhost:1883

Tips

• Version control your config — Commit localport.yaml to your repository. Use ${env.VAR} for tokens so secrets never enter source control.
• One file, many tunnels — A single config file manages all your endpoints. No need for multiple processes or terminal windows.
• Team sharing — Share a config template with your team. Each member sets their own token via environment variables.
• Pair with .env files — Use tools like direnv or dotenv to load environment variables automatically when you enter a project directory.
• Protocol defaults — You can omit proto for HTTP endpoints since http is the default. Only specify it for tcp or tls.

Next steps

• CLI — Every flag in one place, with examples for web apps, game servers, databases, and homelab services
• HTTP Tunnels — How HTTP tunneling works
• Mesh Tunnels — Connect multiple devices to one tunnel