server cli & tls

a reference for all `funnel-server` command-line flags and how to configure tls.

docker only

the funnel server runs exclusively as a docker container for easy deployment and management.

running the server

basic command to start the server:

docker run -d --name funnel-server [options] ghcr.io/karol-broda/funnel-server:latest

configuration

examples

basic server (no authentication):

docker run -d --name funnel-server -p 8080:8080 ghcr.io/karol-broda/funnel-server:latest

server with authentication:

docker run -d --name funnel-server \
  -p 8080:8080 \
  -v funnel-data:/var/lib/funnel \
  -e FUNNEL_REQUIRE_AUTH=true \
  ghcr.io/karol-broda/funnel-server:latest

server with custom port:

docker run -d --name funnel-server -p 9000:9000 -e FUNNEL_PORT=9000 ghcr.io/karol-broda/funnel-server:latest

authentication

token-based auth

funnel supports api key-based authentication to control who can create tunnels.

managing tokens

# with docker
docker exec funnel-server funnel-server token create --name my-laptop

# output:
# Token created for "my-laptop"
#
#   sk_7Fj2kL9xMnPqRsTuVwXyZ0AbCdEfGhIj
#
#   Save this token now - it will NOT be shown again.
#   Token is persisted to disk and survives server restarts.

important

save the token immediately - it cannot be retrieved later. only the hash is stored on the server.

docker exec funnel-server funnel-server token list

# output:
# NAME                 PREFIX       CREATED
# ----                 ------       -------
# my-laptop            sk_7Fj2kL... 2 hours ago
# ci-pipeline          sk_x8Yz9W... 5 days ago

docker exec funnel-server funnel-server token revoke --name my-laptop

# output:
# Token "my-laptop" revoked.

token storage

tokens are hashed with sha-256 before storage. the token file is saved at /var/lib/funnel/tokens.json by default.

persistence

mount a volume at /var/lib/funnel to persist tokens across container restarts.

tls configuration

automatic tls

funnel automatically provisions and renews tls certificates from let's encrypt using the dns-01 challenge.

setup steps

create dns provider config - see lego documentation

dns-providers.json

{
  "providers": [
    {
      "name": "cloudflare",
      "env": {
        "CF_API_TOKEN": "your-cloudflare-api-token"
      }
    }
  ]
}

start with tls enabled

docker run -d --name funnel-server \
  -p 8080:8080 \
  -p 8443:8443 \
  -v $(pwd)/dns-providers.json:/etc/funnel/dns-providers.json \
  -v funnel-certs:/var/lib/funnel/certs \
  -e FUNNEL_ENABLE_TLS=true \
  -e FUNNEL_LETSENCRYPT_EMAIL=your-email@example.com \
  -e FUNNEL_DNS_PROVIDERS_CONFIG=/etc/funnel/dns-providers.json \
  ghcr.io/karol-broda/funnel-server:latest

certificates are generated automatically on first request and renewed before expiration.

Last updated: December 23, 2025

by karol-broda

server cli & tls

Environment Variables

Command Line Flags

On this page