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:

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:

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:

netbird expose 8080 --with-pin 123456

Password Protection

Protect with a password for slightly more flexibility:

netbird expose 8080 --with-password my-secret

SSO User Group Restriction

Lock it down to specific groups from your identity provider:

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:

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:

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:

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 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 product update.

Dashboard vs. CLI: When to Use Which

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

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:

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.