# NetBird v0.66 - Expose Local Services to the Internet from the CLI

Instantly share local services with a single command. NetBird Expose creates secure, ephemeral public URLs through the NetBird reverse proxy, with optional PIN, password, or SSO protection.

*Written by Brandon Hopkins*

Published on February 23rd, 2026

## How It Works

If you already have NetBird running, exposing a service is one command:

```shell
netbird expose 8080
```

That's it. NetBird handles the rest: provisions a TLS certificate, assigns a public domain, and routes traffic through your NetBird reverse proxy to your local port. You get output like:

```bash
Service exposed successfully!
  Name:     myapp-a1b2c3
  URL:      https://myapp-a1b2c3.proxy.example.com
  Domain:   myapp-a1b2c3.proxy.example.com
  Protocol: http
  Port:     8080

Press Ctrl+C to stop exposing.
```

The service stays alive as long as the command runs. Press `Ctrl+C` and it's gone, no orphaned configurations, no cleanup required.

## Built-In Authentication

Exposing a port to the internet doesn't mean exposing it to _everyone_. The expose command supports three authentication methods you can mix and match directly from the CLI.

### PIN Protection

Add a 6-digit PIN that visitors must enter before accessing the service:

```shell
netbird expose 8080 --with-pin 123456
```

### Password Protection

Protect with a password for slightly more flexibility:

```shell
netbird expose 8080 --with-password my-secret
```

### SSO User Group Restriction

Lock it down to specific groups from your identity provider:

```shell
netbird expose 8080 --with-user-groups engineering,devops
```

Users must authenticate through your configured IdP and belong to one of the specified groups. This is ideal for team-internal sharing where you want SSO-level assurance without setting up a permanent service.

### Combine Them

All methods can be combined. When multiple are enabled, visitors can choose which authentication method to use:

```shell
netbird expose 8080 --with-pin 123456 --with-password backup-pwd --with-user-groups admin
```

## Custom Domains and Name Prefixes

By default, exposed services get a randomly generated subdomain. For more readable URLs, you have two options.

**Name prefix** adds a human-readable prefix to the generated domain:

```shell
netbird expose 8080 --with-name-prefix staging
# Result: https://staging-a1b2c3.proxy.example.com
```

**Custom domain** uses a domain you've already configured in your account:

```shell
netbird expose 8080 --with-custom-domain app.example.com
```

Custom domains must be pre-configured and verified in your NetBird account before they can be used with the expose command. See the [Custom Domains documentation](https://docs.netbird.io/manage/reverse-proxy/custom-domains) for setup instructions.

## Ephemeral by Design

Unlike services created through the dashboard, exposed services are intentionally temporary. Here's what that means in practice:

- **Automatic cleanup**: Stop the command and the service is immediately removed. No orphaned proxy configurations.
- **Crash recovery**: If the client disconnects unexpectedly (crash, network failure, `kill -9`), the service automatically expires after 90 seconds.
- **Keep-alive**: The CLI sends a renewal signal every 30 seconds. The management server maintains a 90-second TTL that resets on each renewal.
- **Rate limited**: Each peer can run up to 10 concurrent expose sessions.

This lifecycle model means you never have to worry about forgotten services lingering in your infrastructure. Everything cleans itself up.

The above diagram is a high-level overview of how the NetBird reverse proxy functionality works. For more details, see the [Built-in Reverse Proxy with Custom Domains](/content/knowledge-hub/product-updates/reverse-proxy/index.html) product update.

## Dashboard vs. CLI: When to Use Which

The expose command doesn't replace dashboard-created services. They serve different purposes:

|                    | Dashboard Services             | CLI Expose            |
|--------------------|-------------------------------|-----------------------|
| **Lifecycle**      | Persistent                    | Ephemeral             |
| **Created via**    | Dashboard or API              | `netbird expose` command |
| **Best for**       | Production services, long-running endpoints | Demos, dev sharing, testing, webhooks |
| **Multiple targets**| Yes (path-based routing)      | Single local port     |
| **Advanced settings**| Host headers, redirect rewriting | Not available         |

Use the dashboard for anything that should be always-on. Use `netbird expose` for everything temporary.

## Enabling Peer Expose

Before peers can use the expose command, an account administrator needs to enable the feature:

1. Navigate to **Settings** > **Clients** in the NetBird dashboard
2. Scroll to the **Peer Expose** section
3. Toggle **Enable Peer Expose** on
4. Select at least one **peer group** that is allowed to expose services
5. Click **Save Changes**

Or via the API:

```bash
curl -X PUT "https://api.netbird.io/api/accounts/{account_id}" \
  -H "Authorization: Token {api_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "peer_expose_enabled": true,
      "peer_expose_groups": ["GROUP_ID"]
    }
  }'
```

Only peers belonging to the specified groups can use `netbird expose`. Peers outside the allowed groups will receive a `PermissionDenied` error.

## Getting Started

1. Update your NetBird client to v0.66 or later
2. Make sure your NetBird client is connected (`netbird up`)
3. Ask your account administrator to enable Peer Expose in **Settings** > **Clients**
4. Run `netbird expose <port>` and share the URL

For the full command reference, authentication details, session lifecycle, and troubleshooting, check out the [Expose from CLI documentation](https://docs.netbird.io/manage/reverse-proxy/expose-from-cli-docs).