> Complete YAML configuration reference for Localport. Multi-tunnel setups, environment variable expansion, regions, and validation rules.

# Configuration

If you're just sharing one thing on your computer, the [CLI](/docs/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`:

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

Run it:

```bash
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:

```yaml
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:

```yaml
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](https://dashboard.localport.io) |
| `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.

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

```bash
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:

```yaml
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:

```yaml
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:

```yaml
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:

```yaml
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:

```yaml
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](/docs/cli) — Every flag in one place, with examples for web apps, game servers, databases, and homelab services
- [HTTP Tunnels](/docs/http-tunnels) — How HTTP tunneling works
- [Mesh Tunnels](/docs/mesh-tunnels) — Connect multiple devices to one tunnel