Remote SSH box
box-setup.sh turns a fresh Linux VPS into a devlanes box and starts basics-hello-node on it. Your laptop then runs devlanes remote connect over SSH and opens https://example-hello-node.localhost from the box as if it ran locally. ssh_config.example has Host entries for plain SSH, Tailscale and Cloudflare Tunnel.
Requirements
Section titled “Requirements”On the box:
- Linux with glibc 2.35 or newer (Debian 12, Ubuntu 22.04 and later), x86_64 or arm64
- an ordinary user with
sudoand SSH key login; the script refuses to run as root bashgitandcurl, orsudoto install them- Node 22 or later with npm, for basics-hello-node, installed where a non-interactive SSH session finds it (
/usr/local/bin, or a package in/usr/bin). Debian 12 and Ubuntu 22.04 ship Node 18 and 12 in their own repositories, so use Node’s own builds. A Node that only nvm in~/.bashrcputs onPATHis missing for the box daemon. Not needed with--no-start.
On the laptop:
- devlanes, with
devlanes setuprun once - the OpenSSH client and a key the box accepts, loaded in an agent so reconnects need no prompt
- the same devlanes release as the box (
devlanes --versionon both)
Run it
Section titled “Run it”On the laptop, add a Host entry for the box to ~/.ssh/config (%USERPROFILE%\.ssh\config on Windows). The first block of ssh_config.example is the one for a VPS with a public address:
Host acme-box HostName 203.0.113.10 User acmeCopy the script to the box and run it there. -t gives sudo a terminal to ask for a password:
cd remote-ssh-boxscp box-setup.sh acme-box:ssh -t acme-box bash box-setup.shThe script prints this, with apt-get’s own lines left out. This run passed --repo with a local copy of this repository, so the clone line names it:
==> glibc 2.36==> installing git curl==> git version 2.39.5==> installing devlanes into /home/acme/.devlanes/binInstalled devlanes 0.11.3 to /home/acme/.devlanes/bin/home/acme/.devlanes/bin is not on PATH. Add it to your shell profile: export PATH="/home/acme/.devlanes/bin:$PATH"==> added /home/acme/.devlanes/bin to PATH in /home/acme/.profile for new login shells==> turned linger on for acme==> ports.range is 25000-32767 on this box==> cloning /srv/examples.git into /home/acme/examples==> starting basics-hello-node… tasks: install✓ installexample-hello-node@0 · main✓ services 1 of 1 ready ✓ web https://example-hello-node.localhostexample-hello-node.localhost needs devlanes setup (CA not trusted)==> pairing code for your laptoppairing code: GCXQ-DD42it works once and expires in 10 minuteson your other machine, run: devlanes remote connect <box> --code GCXQ-DD42The CA not trusted line is about browsers on the box itself and can be ignored: the laptop serves the box’s hostnames with its own CA.
Back on the laptop, give it a port range that does not overlap the box’s 25000-32767, then connect with the code:
devlanes config set ports.range 20000-24999devlanes daemon restart # only if the daemon was already runningdevlanes remote connect acme-box --code GCXQ-DD42devlanes remote lsremote connect stays attached to show SSH prompts; Ctrl-C detaches and the connection stays up (--background returns once connected). The first lines of remote ls show the mirrored port and route:
items: state: connected server: devlanes 0.11.3 host: acme-box transport: ssh https_port: 443 lanes: 1 ports: port: 25000 lane: example-hello-node@0 unit: web kind: service state: bound addresses: 127.0.0.1, ::1 conflicts: - relay: - routes: host: example-hello-node.localhost port: 25000 lane: example-hello-node@0 unit: web url: https://example-hello-node.localhost state: readyOpen the route’s url in your browser. The page says This is lane 0 of example-hello-node., and https://example-hello-node.localhost/lane answers with the box’s port, 25000.
If an ordinary user cannot bind port 443 on the box, its proxy falls back to 8443 and its URLs read https://example-hello-node.localhost:8443. The laptop then listens on 8443 too and the URL opens unchanged (box proxy on another port).
The pairing code lasts 10 minutes. For a new one, run ssh acme-box '~/.devlanes/bin/devlanes daemon pair', which prints only the code.
During box-setup.sh
Section titled “During box-setup.sh”Each step checks first, so a second run skips what is done and leaves an existing clone, devlanes install and ports.range alone.
- Checks the glibc version with
getconf GNU_LIBC_VERSIONand stops below 2.35 or on musl. - Installs
gitandcurlwithapt-get(ordnf) throughsudowhen they are missing. - Installs devlanes with
install.sh --dir ~/.devlanes/bin.remote connectalways looks there, so the non-interactive SSHPATH, which skips~/.bashrc, needs no change. The script also adds that directory toPATHin~/.profilefor your own login shells.install.shinstalls only the latest release and has no version flag; when devlanes is already installed, the script leaves it, so the box changes release only when you rundevlanes updatethere. - Runs
sudo loginctl enable-linger "$USER"when systemd runs, so the box daemon survives your last SSH session. Without it,devlanes remote lson the laptop showsthe box stops your processes at logout. - Sets
ports.rangeto25000-32767when the box still has the default20000-32767. - Clones this repository into
~/examples. - Runs
devlanes start --no-uiin~/examples/basics-hello-node, which runs the example’snpm installtask and starts the box daemon with the script’sPATH. For an example with apackage.json, the script stops before this whennodeis not on thatPATH. - Runs
devlanes daemon pair.
Options:
--example <folder>starts another example, such as--example basics-ready-checks. Install what its README lists on the box first.--no-startinstalls and clones only, then prints a pairing code.--repo <url>clones another repository, such as your fork.
Tailscale
Section titled “Tailscale”A box on your tailnet is an ordinary SSH host to devlanes. Use the acme-tailnet block of ssh_config.example with the box’s full MagicDNS name, then devlanes remote connect acme-tailnet as above. With Tailscale SSH, the default check rule asks for a browser sign-in that remote connect never shows, so use an accept rule for the box and account, or run ssh acme-tailnet true first and connect within the check period. Mirrored ports travel inside the SSH connection, so the tailnet policy only needs TCP port 22. Remote boxes over Tailscale has the policy rules.
Cloudflare Tunnel
Section titled “Cloudflare Tunnel”Publish the box’s localhost:22 as an SSH application behind Cloudflare Access, then use the acme-cloudflare block. Its ProxyCommand names cloudflared by its full path, since ssh runs as a child of the devlanes daemon with the daemon’s PATH. cloudflared’s login URL never reaches remote connect, so get the Access token in a terminal first with ssh acme-cloudflare true, and again when the session expires. Remote boxes through Cloudflare covers the tunnel, Access and the Cloudflare One Client.
Limits
Section titled “Limits”- A real VPS, arm64, the
dnfpath and the Tailscale and Cloudflare blocks are untested. - TCP only. UDP ports on the box are not mirrored.
- Run the same release on both machines.
install.shinstalls the latest one, so keep the laptop current withdevlanes update, and rundevlanes updateon the box when the laptop moves ahead. A different release with the same protocol connects with a warning; a different protocol does not connect. - devlanes never installs or updates anything on the box, and the laptop never runs commands there. Start, stop and inspect lanes in an SSH shell on the box.
- A Windows laptop uses Windows’ OpenSSH, which has no ControlMaster, so every reconnect authenticates again. Keep the key in the ssh-agent service (Windows clients).
Try next
Section titled “Try next”Start a second lane on the box:
cd ~/examples && git worktree add ../examples-checkout -b feat/checkout, thencd ../examples-checkout/basics-hello-node && devlanes start --no-ui. Without reconnecting,devlanes url lson the laptop lists both:HOST TARGET PORT STATEexample-hello-node.localhost -> example-hello-node@0:web 25000 readyexample-hello-node1.localhost -> example-hello-node@1:web 25010 readyproxy: http :80, https :443Run
devlanes stopin that worktree on the box. https://example-hello-node1.localhost on the laptop then answers 503 with the proxy’sDL201 Service not runningpage, which names the box and the command to run there,devlanes start --lane example-hello-node@1.Run
devlanes daemon clientson the box. It lists the laptop as paired and connected, with its address and how many ports it mirrors.Run
devlanes url print webin~/examples/basics-hello-node. It adds a line per connected client with the URL that opens there, such ason acme-laptop: https://example-hello-node.localhost.Run
devlanes remote disconnect acme-boxon the laptop. It removes the mirrored port and hostname.When you are done with the box, run
devlanes lane clean <lane> --yesthere for each lane.
box-setup.sh: prepares the box, starts an example and prints a pairing code. Bash, Linux only.ssh_config.example:Hostentries for plain SSH, Tailscale and Cloudflare Tunnel.