A tour of the TUI
The stack from the devlanes.run TUI demo, run for real: an npm workspace with api (Hono), web (Vite and React) and worker in TypeScript, on a shared Postgres and Redis with a Mailpit per lane. Walk through the TUI on it key by key.
Requirements
Section titled “Requirements”- devlanes, with
devlanes setuprun once - Node 22.12 or later
- Docker with Compose v2 (2.24.4 or newer, for
infra.per_lane)
Run it
Section titled “Run it”cd showcase-tui-tourdevlanes startdevlanes start opens the TUI on lane 0 and runs the start inside it. Open https://example-tui-tour.localhost to see the orders api reads from the lane’s database and a form that sends a mail. api puts the mail on the lane’s Redis queue, worker sends it over SMTP, and it lands in the lane’s own Mailpit at https://mail.example-tui-tour.localhost.
During a start
Section titled “During a start”devlanes start --no-ui --output plain prints the start as text:
ok infraok setupok installok migrateok seedexample-tui-tour@0 · mainok services 3 of 3 ready ok api https://api.example-tui-tour.localhost ok web https://example-tui-tour.localhost ok worker http://127.0.0.1:20443- Infra: the Compose project
example-tui-tourruns Postgres and Redis for every lane. Each lane runs its own Mailpit (infra.per_lane) inexample-tui-tour-lane0,example-tui-tour-lane1and so on, andinfra.hostsroutesmail.<lane domain>to its web port. - Setup:
databasecreatesexample_tui_tour_mainin the shared Postgres, andrediswriteslane:ownerinto Redis index 0 (the lane index).devlanes lane cleanruns the matchingteardownentries. - Tasks:
installrunsnpm installat the workspace root until it succeeds once for the lane, andmigrate(apps/api/src/scripts/migrate.ts) creates theorderstable on every start. - Services:
apiis ready when/healthzanswers,web(preset: vite) when/does, andworker, which has no port to probe, when it printsworker ready:.flakyhasautostart: falseand stays stopped. seed(after: services) posts three orders through the runningapi.
Try next: a tour of the TUI
Section titled “Try next: a tour of the TUI”Each step happens in the TUI that devlanes start opened. Run the devlanes commands from a second terminal in the same folder. ? lists every key.
The start. While the lane starts, the top bar names the current step after
starting example-tui-tour@0:, the services wait as… api queued · waiting for containers, and the lane’s pane lists the phases. On the first start, a few seconds in:main @0 · starting · 3 of 7 ready✓ infra 3 of 3 healthy✓ setup database (2 of 2)⠸ tasks install (1 of 2)queued api, web, worker: waiting for installx stops the start. Select a unit to watch its output.When it ends the top bar says
example-tui-tour@0 up: 3 of 3 services ready.The lane’s details. The lane is selected first. Its pane shows
branch,worktree,profile,domain,ports, how many services are up,tasks 3 done,setup 2 of 2 doneand theinfraports.jandkmove through the list.servicesshows a table of state, CPU, memory and URL, andapishows its live output under the titleapi ready · http://127.0.0.1:20410, markedwatching · enter types.ggoes back to the lane,tto the tasks andito the infra.Zoom. On
api,zgives the pane the whole screen, andzagain brings the list back.Typing. Select
weband press Enter. The footer turns intoTYPING into web · keys go to the program · esc or ctrl+] returns to the list. Typehand Enter, and Vite prints itsShortcutslist. Esc returns to the list.Profiles.
g, thenp, opens the picker:start example-tui-tour@0 with profiles[x] default default +api, +web, +worker[ ] backend +api, +worker[ ] everything *, flakyWith none checked, enter starts the default profile.space check enter start esc canceleverythingnamesflaky, since*skips services withautostart: false. Esc closes the picker.Restart. Select
workerand pressr. The row shows· workerand the pane titleworker stopped, then● workeragain with a newworker ready:line. On Windows the old output ends with^CTerminate batch job (Y/N)? Y, from the batch file npm runs through.Infra.
iselects the infra section:containersholds this lane’smailpit,sharedholdspostgresandredis, and▸ setup 2 doneis folded. Selecting a container shows its Docker logs, with its host ports in the title anddocker logson the right of the border.lonsetupunfoldsdatabaseandredis. Ondatabasethe pane readsdatabase setup.database · done · 4m agoabove theCREATE DATABASEits first run printed, andsruns it again: the title turns todone · just now.Monitor.
Mshows CPU and memory graphs for the machine and a table of every unit of every lane on it,example-tui-tourincluded.Magain returns.Daemon.
Dshows the daemon’s version, pid and uptime, its checks anddaemon.logas it follows. Esc returns.A failure. Select
flaky. Its pane saysNot running. Lane starts skip it (autostart is off). s starts it.Presss. It prints a batch line every 2 seconds and crashes on the tenth batch. The row turns into✕ flaky failed · exit 1and the pane explains it above the last output:failed exited with code 1 just now, 20s after startreason exited: code=1 signal=nullnext r restarts itdevlanes logs example-tui-tour@0:flaky prints the whole logThe last output shows
TypeError: Cannot read properties of undefined (reading 'orders')with its stack trace throughapps/flaky/src/report.ts, followed by npm’snpm errorlines. devlanes never restarts it. From anywhere in the list,njumps to the next problem, hereflaky. The lane now countsflakyamong the services it runs, so a later plaindevlanes startstarts it again too.An ad-hoc unit. In the second terminal:
Terminal window devlanes exec --name load -- npm run load -w apps/apiready example-tui-tour@0:load pid=79084logs: devlanes logs example-tui-tour@0:load -fstop: devlanes stop example-tui-tour@0:loadAn
▾ ad-hoc 1 runninggroup appears at the end of the services with◉ loadin it, andapi’s output fills withGET /api/orders 200 1msonce a second.devlanes stop loadstops it and leaves the row as· load. Theloadscript runs Node with--use-system-ca, because devlanes 0.11.3 does not give exec unitsNODE_EXTRA_CA_CERTS.A second lane. A worktree is a lane:
Terminal window git worktree add ../examples-checkout -b feat/checkoutcd ../examples-checkout/showcase-tui-tourdevlanes startdevlanes lane new --name example-tui-tour-review --start --no-uiin the same folder gives a second lane too. It printscreated example-tui-tour@1 named example-tui-tour-review (main)after the sameoklines as above. The TUI grows a lane bar,lanes 1 main 2 example-tui-tour-reviewwith1-9 or [ ] switch laneson the right, and the lane’s pane lists both lanes underlanes in example-tui-tour.]or2switches to lane 1, whoseapisaysconnected to postgres (example_tui_tour_lane1)andconnected to redis (db 1). Its page is https://example-tui-tour1.localhost and its inbox https://mail.example-tui-tour1.localhost.[or1goes back.Freeze and thaw. With
loadstopped (while it runs, freeze answerserror: lane example-tui-tour@0 is starting, stopping or running a task; retry when it is done):Terminal window devlanes debug freezefrozen example-tui-tour@0a request, a connection or a command thaws it, or run devlanes debug thaw example-tui-tour@0The list title becomes
@0 frozen · 6/7 up, every running service and the lane’smailpitshow❄instead of their dot,api’s pane title readsapi ❄ frozen, and the lane’s pane addsidle frozen since 01:27 UTC, last activity a command at 01:27 UTC.workerhas nokeep_awake, so it does not hold the lane awake.devlanes debug thawprintsthawed example-tui-tour@0and the dots come back.Quit.
qcloses the TUI and prints where things stand:Lane example-tui-tour@0 failed, 6/7 up, 1 failedDaemon running, 2 lanes runningStop devlanes stop --lane example-tui-tour@0Everything keeps running in the daemon, and
devlanes startopens the TUI on the lane again. This run hadtui.on_quit: keepin~/.devlanes/config.yaml. With the default,ask,qfirst asks whether to keep the lanes or stop them.
To remove it all:
devlanes lane clean example-tui-tour-review --yesdevlanes lane clean 0 --yesdocker compose -p example-tui-tour down -vThe first prints cleaned example-tui-tour@1: stopped 3 units, teardown database, redis. It drops example_tui_tour_lane1, flushes Redis index 1 and removes the lane’s Mailpit, while lane 0 keeps running. docker compose -p example-tui-tour down -v removes the shared Postgres and Redis with their volumes, which lane clean leaves in place.
devlanes.yaml: the per-lane names, the Compose infra with setup and teardown, the tasks, four services and three profiles.docker-compose.yml: Postgres and Redis (shared) and Mailpit (per lane), each with a healthcheck.apps/api/: the Hono API, with the orders and mail routes insrc/routes/.apps/api/src/scripts/:migrate.tsandseed.tsfor the tasks, andload.tsfordevlanes exec.apps/worker/src/index.ts: takes mail jobs off the Redis queue and sends them to Mailpit.apps/flaky/src/report.ts: the report job that crashes about 20 seconds in.