Remote access (SSH/VNC)

The burrowee cli reaches a paired gateway's exposed ssh/vnc service in one command — no manual burrowee connect flags, no port bookkeeping:

burrowee ssh home-mac             # reads ssh_config, execs ssh
burrowee open --svc vnc home-mac  # reads vnc_config, forwards the port

Copy

burrowee ssh <host> resolves <host> from ~/.burrowee/cli/ssh_config and execs the system ssh against the forwarded port. Every other service goes through burrowee open --svc <svc> <host>[@<relay>], which resolves <host> from the matching ~/.burrowee/cli/<svc>_config alias file (vnc_config, rdp_config, …), holds a local forward, and prints the 127.0.0.1:<port> address for your own client to connect to.

Prerequisites

The burrowee cli is installed and paired to a gateway (burrowee bootstrap <blob> <pin>, or the burrowee-connect skill).
The gateway has an enrolled service to reach — an ssh target (the machine itself) and/or a vnc target (a screen-sharing server on it).

1. Config files

All <svc>_config files live in ~/.burrowee/cli/ (override with BURROWEE_HOME) and share the same directive style: an OpenSSH-style Host <alias> block carrying burrowee routing as #@ comments.

~/.burrowee/cli/ssh_config (OpenSSH format — all other keywords, User, IdentityFile, IdentitiesOnly, etc., are read by ssh itself via -F):

# ~/.burrowee/cli/ssh_config
Host home-mac
    #@gateway studio-mini
    #@relay   eu-relay
    # #@service ssh   (default when omitted)
    User sam

Copy

~/.burrowee/cli/vnc_config (same directive style; #@service defaults to vnc — and any other service follows the same <svc>_config pattern):

# ~/.burrowee/cli/vnc_config
Host home-mac
    #@gateway studio-mini
    #@relay   eu-relay
    # #@service vnc   (default when omitted)

Copy

#@gateway defaults to the Host alias itself; #@relay is repeatable (file order = priority; override per-invocation with <host>@<relay>); #@service defaults to the --svc value (ssh for ssh_config). A <host> with no matching Host block is treated as a bare gateway id/name — exactly as ssh <host> does.

2. Connect

With the config files in place, connecting is one command:

burrowee ssh home-mac             # ssh, via ~/.burrowee/cli/ssh_config
burrowee open --svc vnc home-mac  # VNC forward, via ~/.burrowee/cli/vnc_config

Copy

burrowee ssh resolves ssh_config, opens the forward, and execs the system ssh against it. Every token after the host passes through to ssh verbatim (-l me, -i key, a remote command). burrowee ssh list prints the configured aliases.

burrowee open prints listening on 127.0.0.1:<port> → … and blocks until Ctrl-C — it execs no client of its own; point your VNC (or RDP, or anything) client at the printed address. The @<relay> suffix and the --relay/--gw flags override whatever the host's alias block says.

3. Example shell functions

The cli repo ships example shell functions (shell/burrowee.bash, shell/burrowee.zsh, shell/burrowee.fish) that wrap burrowee open and launch a viewer at the forwarded port — a vnc <host> one-worder. They are examples to copy and adapt into your shell rc, not installed commands:

# bash → ~/.bashrc
source /path/to/burrowee.bash
# zsh → ~/.zshrc
source /path/to/burrowee.zsh
# fish → ~/.config/fish/config.fish
source /path/to/burrowee.fish

Copy

burrowee.bash (burrowee.zsh is the same functions under a zsh header):

# burrowee.bash — EXAMPLE shell functions over `burrowee` + the {svc}_config
# aliases (bash/zsh). Copy/adapt into your shell rc — these are examples, not
# shipped commands:   source /path/to/burrowee.bash
#
# The CLI already resolves a <host> from ~/.burrowee/cli/<svc>_config:
#   burrowee ssh  <host>            # reads ssh_config, execs ssh
#   burrowee open --svc vnc <host>  # reads vnc_config, forwards the port
# A viewer-launching wrapper only needs the local port `open` prints.

# vnc <host>: forward via vnc_config (svc=vnc) and launch a viewer; hold until
# Ctrl-C. Adapt for any {svc}_config service (rdp, http, …). VNC client: macOS
# `open vnc://…`; Linux $BURROWEE_VNC_CLIENT, else vinagre/remmina/vncviewer.
vnc() {
    local host="$1"
    if [ -z "$host" ]; then echo "usage: vnc <host>" >&2; return 2; fi

    local out; out="$(mktemp)"
    burrowee open --svc vnc "$host" >"$out" 2>&1 &
    local pid=$!
    trap 'kill "$pid" 2>/dev/null; rm -f "$out"' INT TERM

    local port="" i=0
    while [ "$i" -lt 100 ]; do
        port="$(sed -n 's/.*listening on 127\.0\.0\.1:\([0-9][0-9]*\).*/\1/p' "$out" 2>/dev/null | head -1)"
        [ -n "$port" ] && break
        kill -0 "$pid" 2>/dev/null || break
        sleep 0.1; i=$((i+1))
    done

    if [ -z "$port" ]; then
        echo "vnc: forward did not come up:" >&2; cat "$out" >&2
        trap - INT TERM
        kill "$pid" 2>/dev/null; rm -f "$out"; return 1
    fi

    echo "vnc: $host → 127.0.0.1:$port; Ctrl-C to disconnect"
    local addr="127.0.0.1:$port"
    if [ "$(uname)" = "Darwin" ]; then
        open "vnc://$addr"
    elif [ -n "$BURROWEE_VNC_CLIENT" ]; then
        "$BURROWEE_VNC_CLIENT" "$addr" &
    else
        local c
        for c in vinagre remmina vncviewer; do
            if command -v "$c" >/dev/null 2>&1; then "$c" "$addr" & break; fi
        done
    fi

    wait "$pid" 2>/dev/null
    trap - INT TERM
    rm -f "$out"
}

Copy

burrowee.fish:

# burrowee.fish — EXAMPLE shell functions over `burrowee` + the {svc}_config
# aliases. Copy/adapt these into ~/.config/fish/config.fish — they are examples,
# not shipped commands:   source /path/to/burrowee.fish
#
# The CLI already resolves a <host> from ~/.burrowee/cli/<svc>_config:
#   burrowee ssh  <host>            # reads ssh_config, execs ssh
#   burrowee open --svc vnc <host>  # reads vnc_config, forwards the port
# A viewer-launching wrapper only needs the local port `open` prints.

# vnc <host>: forward via vnc_config (svc=vnc) and launch a viewer; Ctrl-C to
# disconnect. Adapt for any {svc}_config service (rdp, http, …).
function vnc --description 'burrowee open --svc vnc <host> + launch viewer'
    set -l host $argv[1]
    if test -z "$host"
        echo "usage: vnc <host>" >&2
        return 2
    end

    set -l out (mktemp)
    burrowee open --svc vnc $host >$out 2>&1 &
    set -l pid $last_pid
    set -g __vnc_pid $pid
    function __vnc_cleanup --on-signal INT --on-signal TERM
        kill $__vnc_pid 2>/dev/null
    end

    set -l port ""
    for i in (seq 100)
        set port (sed -n 's/.*listening on 127\.0\.0\.1:\([0-9][0-9]*\).*/\1/p' $out 2>/dev/null | head -1)
        test -n "$port"; and break
        kill -0 $pid 2>/dev/null; or break
        sleep 0.1
    end

    if test -z "$port"
        echo "vnc: forward did not come up:" >&2
        cat $out >&2
        functions -e __vnc_cleanup
        set -e __vnc_pid
        kill $pid 2>/dev/null
        rm -f $out
        return 1
    end

    echo "vnc: $host → 127.0.0.1:$port; Ctrl-C to disconnect"
    set -l addr "127.0.0.1:$port"
    if test (uname) = Darwin
        open "vnc://$addr"
    else if set -q BURROWEE_VNC_CLIENT
        $BURROWEE_VNC_CLIENT $addr &
    else
        for c in vinagre remmina vncviewer
            if command -v $c >/dev/null 2>&1
                $c $addr &
                break
            end
        end
    end

    wait $pid 2>/dev/null
    functions -e __vnc_cleanup
    set -e __vnc_pid
    rm -f $out
end

Copy

4. Troubleshooting

No VNC client found. The example vnc function looks for open (macOS), then $BURROWEE_VNC_CLIENT, then vinagre/remmina/vncviewer on Linux. Set BURROWEE_VNC_CLIENT=/path/to/your/viewer if none of those match, or run burrowee open --svc vnc <host> yourself and connect manually to the printed 127.0.0.1:<port> address.
Forward never comes up (timeout). The example functions poll the burrowee open output for up to 10s (100 × 0.1s); if no listening on … line appears, they print the captured output and exit non-zero. Check that the gateway is online and the named service (ssh/vnc) is actually enrolled on it — burrowee gateways list / burrowee routes from the paired client.
Wrong relay. #@relay in ssh_config/vnc_config pins which relay to route through — it is repeatable, and file order is the priority. Omit it to use the client's default relay; override a single connection with <host>@<relay> (or --relay). If a gateway is reachable through more than one relay and the wrong one gets picked, add or correct the #@relay line(s) for that Host alias.