Targets

A target is one thing your gateway exposes: a name, a local address, and a handler type that says how the gateway should speak to it.

Field	Meaning
Name	How the outside refers to it. CLI clients connect by this name (burrowee cli connect --svc <name>), and web domains attach to it.
Target	The local address the gateway forwards to, in host:port form — 127.0.0.1:3000, 127.0.0.1:22, or another machine on the gateway's LAN.
Handler type	http(s) (CLI type name: web) or raw — see below.
Active	A toggle. An inactive target keeps its configuration and sessions but is not served until you switch it back on.

You create and manage targets in the local console (the Targets tab — name it, point it at the local address, pick a type), remotely from the cloud console's gateway detail page (which relays the same operations down to the gateway), or from the command line:

burrowee gateway target list
burrowee gateway target add <svc> <host:port> [--type <web|raw>]
burrowee gateway target address <svc> <host:port>   # re-point at another address
burrowee gateway target remove <svc>

Either way, the gateway's own store is where the target actually lives. target address re-points an existing target's upstream without recreating it — domains, sessions, and settings all stay attached.

Names starting with $ are reserved

Target names may not start with $ — that namespace is reserved for Burrowee's internal use. target add/rename reject such names outright. The name console is also reserved: it's the local console's own preset target.

Handler types

There are only two: http(s) for anything a browser talks to, and raw for everything else.

http(s) — web service (the default)

http(s) covers every web service — plain HTTP and HTTPS alike; you never pick between them. The first time a request arrives, the gateway probes the local address once and decides: if it answers TLS (many self-hosted apps and admin panels serve their own, often with a self-signed certificate), the gateway re-encrypts to it — self-signed certificates on loopback addresses are accepted; if it answers plaintext (a typical dev server on 127.0.0.1:3000), the gateway pipes the request bytes straight through. The result is cached, and the cache self-corrects — if the service was down during the probe, or later changes scheme, the gateway re-probes rather than serving a stale answer.

Don't worry about a plaintext last hop — that's only on the gateway machine itself; everything between the viewer and the gateway is end-to-end encrypted.

The gateway always forwards the real client IP to a web backend in the X-Forwarded-For header — it sets the header rather than appending to it, so a client-forged X-Forwarded-For is dropped instead of passed through. There is nothing to configure.

This is the default: leave the handler type empty when creating a target and you get http(s) — on the CLI the type name is web (target add <svc> <host:port> --type web). (Existing setups may still show the older values auto, http, or https — all three are served as web targets and display as http(s).)

raw — an opaque byte pipe

raw does no protocol handling at all: bytes in, bytes out — the byte stream reaches the backend untouched, with no header or proxy-protocol injection. Use it for anything that isn't web — SSH, databases, RDP, game servers, custom TCP protocols. This is the type CLI clients use with burrowee cli connect and burrowee cli ssh. (You may see the older spelling raw-forward in existing setups; it means the same thing and is accepted everywhere raw is.)

Two things web targets have that raw targets deliberately don't: sessions (a raw target has no session surface — access control happens at the protocol you're tunnelling, like SSH's own auth) and random domains (a raw target is never assigned a *.burrowee.net name; only a custom-domain attach applies).

Transport mode and the warm pool

Each target has a transport mode — how its traffic rides the gateway↔relay link:

• multiplex — streams share the gateway's existing relay connections. The only mode for web targets.
• isolated — the target gets its own dedicated warm connections to the relay. Raw targets are born isolated, which keeps a long-lived byte stream (an SSH session, a database connection) off the shared lanes.

burrowee gateway target mode <svc> <isolated|multiplex> [--pool-min <n>] [--pool-max <n>]

--pool-min/--pool-max size the warm pool for an isolated target (--pool-max 0 means the default ceiling). To opt a raw target back onto the shared lanes: target mode <svc> multiplex.

Changing a target's type

You can change a target's handler type in place — the Protocol control on the target row in either console. The change applies to new connections immediately; an http(s) target also drops its cached scheme-probe result and re-probes.

Change the type in place — never delete and recreate

Deleting a target permanently deletes every session minted for it. If you delete a target and recreate it under the same name to change its type, all existing share links and viewer sessions for it die immediately with an invalid-token error. Use the in-place protocol change instead; it leaves sessions intact.

Domains

A web target becomes reachable in a browser once a domain points at it — either an auto-assigned *.burrowee.net address from the random-domain pool or a custom domain of your own (say app.example.com). Domains are managed by the cloud console (which owns DNS and certificates) and attached per target; the local console's Domains column shows what's attached and links you to the management page. See the console guide for the domain and certificate flow.

Exposing the local console itself

The local console is loopback-only by default, but you can expose it through a relay — token-gated, exactly like any other target — with a dedicated preset instead of a hand-rolled target:

burrowee gateway target console enable
burrowee gateway target console disable

enable creates (or re-activates) a target named console pointed at the loopback console address; disable deactivates it without deleting it, so sessions minted against it survive and enable picks the same target back up. Because console is a reserved name (see above), you can't shadow or delete this preset by hand — it's managed only through these two verbs.

Before exposing the console, set a console password with burrowee gateway console password — the remote console is password-gated on top of the session token, with rate-limited, audited verification; see Local console → Console password.

Registering a service dynamically

Adding a target with target add is for services that are always running. For a service you only want reachable while it's actually up — a dev process you start and stop by hand — register it directly instead, without touching the target store at all:

burrowee register --name <svc> --target <host:port>

This dials the gateway's local register socket and holds the connection open for as long as the registered process runs; the moment it exits or drops, the name stops resolving. burrowee register defaults to the legacy per-user path (~/.burrowee/gateway/sockets/register.sock); the socket a system-installed gateway actually serves lives under its data root, so when the two sides disagree, run the diagnostic and pass the resolved path with --sock:

burrowee gateway register info   # the resolved socket path, whether it dials, declared targets
``` A registered service is always handled as `raw` and never appears in `target list`, the local console's Targets tab, or the cloud console — it exists only for the lifetime of the `burrowee register` process, reachable by [CLI clients](/cli/connect-ssh) under `<svc>` the same way a stored `raw` target would be. It's meant for wrapping an existing TCP service that shouldn't need any Burrowee-aware code of its own.