Configuration reference
YAML fields, target formats, HTTP routing, path rewrites and shared secret rules.
Configuration example
Save as tubu.yml. Set TUBU_TOKEN to your API key and replace the domains and targets with your own values.
version: 1
tunnels:
- type: http
domain: my-app.tubu.dev
target: 3000
routes:
- path: /api
target: "https://api.internal:8443"
rewrites:
- ["^/api(/|$)", "/"]
- type: tcp
domain: my-ssh.tubu.dev
target: "tcp://192.168.1.20:22"npx tubu-cli --config tubu.ymlOnly one YAML 1.2 document is accepted. Unknown fields, duplicate keys, aliases, tags and merge keys are rejected. Configuration changes require a publisher restart. There is no environment variable substitution inside YAML strings.
Root fields
| Field | Type | Default | Rules |
|---|---|---|---|
version | Integer | 1 | Only 1 is supported. |
authtoken | String | Unset | Optional 16 lowercase letters or digits. Overrides TUBU_TOKEN; --authtoken has priority. |
secret | String or null | Unset | Optional shared secret inherited by HTTP tunnels. Nonempty when a string. |
secret_hash | String or null | Unset | Optional SHA-256 digest. Cannot be supplied together with secret. |
tunnels | Array | Required | 1 through 20 entries, with unique domains. Account limits can be lower. |
Use TUBU_TOKEN to keep the API key outside the YAML file. Neither that variable nor authtoken provides visitor authentication.
Tunnel fields
| Field | Type | Default | Rules |
|---|---|---|---|
type | http or tcp | Required | http also supports an HTTPS target. |
domain | String | Required | Exact third or fourth level tubu.dev hostname; normalized to lowercase. |
target | Integer or URL string | Required | Integer port 1 through 65535, or a matching target origin. |
secret | String or null | Inherited for HTTP | HTTP only. Overrides the root secret; null disables inherited protection. |
secret_hash | String or null | Inherited for HTTP | HTTP only. Overrides the root digest; null disables inherited protection. |
routes | Array | Empty | HTTP only. Unique route path values. |
rewrites | Array of string pairs | Empty | HTTP only. Applied to requests using the tunnel fallback target. |
Domains and targets
Domains must end in .tubu.dev with one or two preceding labels. Each label contains letters, digits or hyphens, starts and ends with a letter or digit, and has at most 63 characters. The total maximum is 253 characters. api.tubu.dev is reserved. Wildcards, external domains, ports and paths are not accepted.
Fourth level names require an existing reservation. See Reserve a domain.
| Tunnel | Example | Meaning |
|---|---|---|
| HTTP with port | target: 3000 | http://127.0.0.1:3000 |
| HTTP with URL | target: "http://192.168.1.20:8080" | HTTP origin reachable from the publisher. |
| HTTP with HTTPS URL | target: "https://api.internal" | HTTPS origin with certificate verification. |
| TCP with port | target: 22 | tcp://127.0.0.1:22 |
| TCP with URL | target: "tcp://db.internal:5432" | TCP origin with an explicit port. |
Use a YAML number for a port, not a quoted numeric string. URL strings cannot contain credentials, query parameters, fragments or a path other than an optional /. HTTP targets use http:// or https://; TCP targets use tcp://.
HTTP routes
| Field | Type | Default | Rules |
|---|---|---|---|
path | String | Required | Unique prefix beginning with /. Cannot be / alone, end in /, or contain // at the start, wildcards, query or fragment delimiters, spaces or control characters. |
target | Integer or URL string | Required | HTTP or HTTPS target, using the same rules as an HTTP tunnel target. |
rewrites | Array of string pairs | Empty | Only these rules run for requests matched to this route. |
A route matches its exact pathname or a prefix followed by /. /api matches /api and /api/users, not /apiculture. The longest matching prefix wins. The tunnel target handles unmatched paths.
Matching uses the original pathname before rewriting. The query string does not affect selection. Route targets do not inherit tunnel rewrite rules. There is no per route secret field.
Path rewrites
Each rule is a pair of strings: [pattern, replacement]. Patterns use a restricted regular expression syntax without slash delimiters or flags.
rewrites:
- ["^/api(/|$)", "/"]
- ["^/v1/([a-z]+)$", "/v2/$1"]Rules run once in array order. Each rule replaces its first match. Capture substitutions $1 through $9 and a literal dollar sign written as $$ are supported. Literal characters, anchors, character classes, alternation, capture groups, and supported single character quantifiers are available.
Quantifiers apply to literal characters and character classes, not to a dot or a group. Use a character class such as [^/]+ to match a path segment.
Special groups, quantifiers on groups, counted or lazy quantifiers, regex backreferences, shorthand escapes such as \d, flags and slash delimited patterns are rejected. An empty result becomes /. A result containing ? or #, control characters, or a leading // is rejected. The original query string is preserved.
See Rewrite request paths for a complete prefix removal example.
HTTP secrets
Set secret to a nonempty string or secret_hash to a 64 character hexadecimal SHA-256 digest. Hexadecimal letters are normalized to lowercase. Do not supply both fields at the same level, including null values.
For example, generate a digest without adding a newline to the original secret:
printf '%s' 'REPLACE_WITH_A_RANDOM_SECRET' | openssl dgst -sha256Copy only the 64 hexadecimal characters into secret_hash. Callers send the original secret, not the digest, in exactly one X-Tubu-Auth header.
HTTP tunnels inherit the root secret unless they supply their own secret or secret_hash. A local null disables inherited protection. TCP tunnels ignore root HTTP protection and reject any local secret, secret_hash, routes or rewrites field, even null or empty values.
A missing, incorrect or duplicate header returns 401 before a local channel opens. Protection applies to normal HTTP requests and WebSocket upgrades. X-Tubu-Auth is removed before forwarding; application Authorization remains available.
Validation errors
Errors identify the file and the invalid field or tunnel index when available. Common causes are unknown fields, quoted port numbers, duplicate domains, duplicate route paths, mismatched target schemes and unsupported rewrite syntax.
The CLI validates the complete YAML document before applying a credential override. Remove or correct an invalid YAML authtoken even when you pass --authtoken. See the FAQ for runtime failures.