Remote box in Docker
A Docker container runs its own devlanes daemon and basics-hello-node, and your machine connects to it as a remote box through docker exec instead of SSH. After pairing, https://example-hello-node.localhost opens on your machine and reaches the server in the container, under the same hostname and port number it has there.
Requirements
Section titled “Requirements”- devlanes, with
devlanes setuprun once, on the latest release: the image build stops when the release it installs differs from yours (devlanes updatefixes that) - Docker with Linux containers
Run it
Section titled “Run it”From this folder, build the image. The build context is the repository root, because the image copies basics-hello-node and _internal/brand from it; the examples repository is not public yet, so the container cannot clone it. In PowerShell, write the version by hand, such as --build-arg CLIENT_VERSION=0.11.3.
cd remote-docker-boxdocker build --build-arg CLIENT_VERSION="$(devlanes --version | cut -d' ' -f2)" -f Dockerfile -t acme-box ..docker run -d --init --name acme-box acme-boxdocker exec acme-box devlanes start --no-uiThe first devlanes command in the container starts the box’s daemon there.
Tell your devlanes how to reach the box. devlanes config set reads the value as YAML, so the command is a quoted flow list:
devlanes config set remote.boxes.acme-box.command '[docker, exec, -i, acme-box, devlanes, tunnel, --stdio]'The box serves only machines it paired with. Get a one-time code in the container, then connect with it:
docker exec acme-box devlanes daemon pairdevlanes remote connect acme-box --background --code BQGA-0RH8daemon pair prints the code alone when no terminal is attached (docker exec -t prints it with instructions). Use the one it printed, within 10 minutes. Later connections, also after a restart of your daemon, need no code.
Open https://example-hello-node.localhost. The page says This is lane 0 of example-hello-node. and shows port 41001, the port of web in the container. devlanes remote ls shows the box; its output starts with:
items: state: connected server: devlanes 0.11.3 host: acme-box transport: command https_port: 443 lanes: 1 ports: port: 41001 lane: example-hello-node@0 unit: web kind: service state: bound addresses: 127.0.0.1, ::1During a start
Section titled “During a start”- The image build runs
npm cifor the app and commits the copy to a Git repository onmainin~/examples. docker run --initkeeps the container up withsleep infinity;--initreaps the processes the box’s daemon leaves behind.docker exec acme-box devlanes start --no-uiruns in~/examples/basics-hello-nodeas lane 0. Its first start runs theinstalltask (npm install), which finds the image’snode_modulesand has little to do. Lanes in the box take ports from41000-41999(box/config.yaml), away from the default pool your machine uses, so your machine can mirror them under the same numbers.devlanes.local.yamlin the container (box/overlay.yamlhere) merges over the example’sdevlanes.yaml. It addsadmin, the same server underadmin.example-hello-node.localhostwithhidden: true, andsyncofoutboxonweb.devlanes remote connect acme-boxmakes your daemon run the command fromremote.boxes.acme-box.command.docker exec -ipasses its input and output through without a terminal, anddevlanes tunnel --stdioin the container talks to the box’s daemon. The code pairs your machine; the box keeps a hash of the token it gives your machine.- The box sends its lanes, ports and hostnames, leaving out
admin. Your daemon listens on 127.0.0.1:41001 and ::1:41001 and addsexample-hello-node.localhostto your proxy, with a certificate from your own CA, so the container needs no trust setup. A request goes through the proxy to that port, then overdocker execto 127.0.0.1:41001 in the container. Published ports play no part.
Try next
Section titled “Try next”- Start a second lane in the box:
docker exec acme-box git worktree add -q ../../examples-checkout -b feat/checkout, thendocker exec acme-box sh -c 'cd ../../examples-checkout/basics-hello-node && devlanes start --no-ui'. Itsinstalltask does a fullnpm install, since the new worktree has nonode_modules. Lane 1 getsadminand thesyncentry too: a worktree without its owndevlanes.local.yamlreads the primary worktree’s. - Open https://example-hello-node1.localhost on your machine. It works without reconnecting and says
This is lane 1 of example-hello-node., anddevlanes url lslists both hostnames next toexample-hello-node@0:webandexample-hello-node@1:web. - Run
docker exec acme-box devlanes stop web, then reload the page. Your proxy answers 503DL201 Service not runningwithStart it on acme-box: devlanes start --lane example-hello-node@0, since commands are never sent to the box.docker exec acme-box devlanes start --no-ui webbrings it back. - Run
docker exec acme-box devlanes status 0. It listsadminas ready on port 41000, butdevlanes remote lson your machine has no port 41000, andhttps://admin.example-hello-node.localhostfails the TLS handshake there because your proxy has no route or certificate for it. Plainhttp://admin.example-hello-node.localhostanswers 404DL101 Unknown host. - Run
docker exec acme-box sh -c 'date -u > outbox/now.txt'. A second later the file is in~/.devlanes/sync/acme-box/example-hello-node/example-hello-node@0/outbox/on your machine (%USERPROFILE%\.devlanes\sync\...on Windows), next tohello.txt.devlanes remote syncshows the folder aswatching. - Run
docker exec acme-box devlanes daemon clients. It lists your machine aspairedand connected. - Run
docker exec acme-box devlanes daemon revokewith the id it shows (dl_cid_...).devlanes remote lsthen showsneeds_pairingwith the fixdevlanes daemon pair on acme-box, then devlanes remote connect acme-box --code <code>, and the page answers 503 until you pair again. - Run
docker restart acme-box. Your daemon reconnects on its own and the box’s daemon starts again, but its lanes stay idle, and the page answers 503, untildocker exec acme-box devlanes start --no-ui. Theinstalltask does not run again. - When you are done:
devlanes remote disconnect acme-box,devlanes config unset remote.boxes.acme-box,docker rm -f acme-boxanddocker image rm acme-box. Synced files stay under~/.devlanes/sync/acme-boxuntil you delete them.
Dockerfile: the box image, Debian 12 with Node 24, Git and devlanes, withbasics-hello-nodeand_internal/brandcopied in and committed to a fresh repository.box/install-devlanes.sh: installs devlanes withinstall.sh --dir ~/.devlanes/binand stops the build when its release differs fromCLIENT_VERSION.box/config.yaml: the box’s user config, with its ownports.range.box/overlay.yaml: the box’sdevlanes.local.yamlfor basics-hello-node, with the hiddenadminservice and thesyncentry.box/outbox/hello.txt: the filesynccopies to your machine.