Don't Make Users Install a Client for One Command: Adding an In-Browser Terminal to Your Vibe Project
An in-browser terminal is not a toy for power users — it is the product's last mile: xterm.js setup, an allowlist with three red lines, three sandbox tiers, reconnect-and-resume, and mobile keyboards, with a fictional funnel of 1000→540→300→170→96.

Three things up front, so you read the right article. First, this piece is not about desktop terminal products — the site already has a news story on Mitchell Hashimoto's OSC 7501 terminal protocol, about giving terminals a new protocol. It is not about packaging and distributing a CLI tool either — the site already has a guide, "Don't Just Build a Web Page: A Hands-On Guide to CLI Tools for Your Vibe Project," about shipping your tool as a command line. And it is not about server operations. This piece is about one thing only: embedding a terminal inside your own product so users can run commands without leaving the browser. Second, the whole article runs on one fictional example to make the ideas concrete: the example product is "Cloud Workshop," an online tool that lets users run data-processing scripts in the browser; the example user is "Lin Xiao," an analyst processing data on a tablet while traveling; every number, conversation, and scene in the example is fictional practice material, meant to make the reasoning concrete — not a real product or a real event. Third, the funnel numbers in the last section are also a fictional sample, used to do the math, not real data.
Lin Xiao's story goes like this. On a Wednesday afternoon, riding a high-speed train, she gets a message from a client: one column of dates in the report she sent that morning is formatted wrong, and the client needs it for a meeting that afternoon. She opens her tablet, logs in to Cloud Workshop, and everything is there — the data, the script — except for one command: run the cleaning script once more and export again. She has two choices: find a computer, download a client, install a command-line tool, set up keys, and burn half an hour; or open the terminal inside the Cloud Workshop page, type one command, and be done in two minutes. She picks the second. That is the entire reason an in-browser terminal exists: when a user hits a problem, the fix should be one input box away, not one installation away.
Many vibe projects stall at exactly this step. The product itself already works, and the author knows users occasionally need to type a command — restart a task, read a log, change a setting, export data. But the author's first instinct is usually to write a doc teaching users to install a CLI, or to say flatly that "this can't be done on the web." Nine out of ten users will not install something just to run one command. They give up, or they message support, or they switch to a competitor where everything works on the web. Embedding a terminal in the browser fixes that gap. It is not a bonus feature for power users. It is the "last mile" of how a product gets used.
First, decide whether your product needs a terminal at all
Not every product needs one. The test is simple: do your users have moments that cannot be described in words or done with clicks, and can only be solved by typing one command? A data tool needs to run scripts and change parameters; a deployment product needs to read logs and restart services; an education product needs students to actually type commands and read errors; a collaboration product needs admins to process a batch of accounts at once. If moments like that come up a few times a month, a terminal is worth building. If everything in your product can be done by clicking buttons, bolting on a terminal just adds an entry point nobody clicks — plus a security responsibility nobody asked for.
There is a second way to judge it: the less your users know about the command line, the more an in-browser terminal is worth. For programmers, installing a CLI takes five minutes, and a browser terminal is only "a bit more convenient." For analysts, operations staff, and teachers like Lin Xiao, installing a client is a wall in itself, and a browser terminal decides whether they can use the feature at all.
xterm.js: before writing code, do three sums
Building a browser terminal, the first step barely needs a decision about which library: xterm.js is the de facto standard. It is the same terminal VS Code uses, it has the biggest ecosystem, and when something breaks, someone has already asked about it. What actually needs deciding is the three costs it brings: bundle size, fonts, and the renderer. Get any of them wrong and on day one someone will complain the page got slow, the text looks blurry, or typing lags.
The first cost is bundle size. xterm.js plus a few common plugins packs to a few hundred KB. That is nothing on a desktop, but on mobile and slow networks it is worth weighing. The fix is not to load it on first paint: load it dynamically when the user opens the terminal panel, and do not load it at all if they never open it. First paint stays fast, and waiting half a second to open the terminal is fine — the user clicked to "open a tool," so half a second is within expectations. Loading it into first paint instead means every user pays for a feature only half of them use. That is a bad deal.
The second cost is fonts. A terminal lives or dies on monospace fonts: get the font wrong and the output stops lining up and tables fall apart. The monospace fonts browsers ship with look different on every system — Windows, macOS, and phones each have their own — so table alignment becomes luck. The safe move is to ship your own monospace font, such as JetBrains Mono, with system fonts as fallback if loading fails. Load the font lazily too, so it does not fight first paint for bandwidth. And one detail: Chinese fonts. If your users will read Chinese output in the terminal — file names, Chinese text in logs — test how the monospace font handles Chinese up front, instead of finding out from a user's screenshot asking why the characters overlap.
The third cost is the renderer, and xterm.js offers three: WebGL, canvas, and dom. WebGL is the fastest and stays smooth when output floods in, but it depends on the GPU and can misbehave on old machines and some virtual machines; canvas is the middle ground, fast enough with the best compatibility, and enough for most products; dom is the slowest, but it lets screen readers read terminal content, which matters if you have accessibility requirements or very little output. My advice: default to canvas, and step up to WebGL only when it is available and output is heavy. There is no "best" renderer, only the one that fits your users' machines. Before launch, test on a three-year-old laptop. It teaches more than ten benchmark articles.
The PTY does the real work; the browser is just a screen
Many people building a browser terminal for the first time assume the obvious: run some JavaScript in the browser and it can execute commands. It cannot. There is no shell in a browser; commands have to run on a server. The standard approach is a PTY plus a WebSocket: the server opens a pseudo-terminal (PTY) for each terminal session and uses it like a real terminal, while the browser and server stay connected over a WebSocket — keystrokes go one way, output comes back the other. xterm.js is only the screen. The PTY is the thing doing the work.
Three things in this model need deciding up front. First, the session. When a user opens a terminal, you create a session on the server: a PTY process, a set of environment variables, a working directory. A session is the unit you bill for and the unit you clean up. The moment you create one, decide when it dies — when the user closes the page, or after some time in case they come back. That decision shapes everything after it, so do not leave it to the end.
Second, reconnection. WebSockets drop: in a tunnel on the metro, when Wi-Fi switches, when a laptop lid closes and opens again. What happens after a drop is where designs split. The worst approach kills the session on disconnect, so the user comes back to a command that never finished and output that is gone, and has to start over. The better approach leaves the session running on the server and lets the user pick up where they left off. That is what Lin Xiao fears most on the train: three minutes without signal in a tunnel, then finding her cleaning script was killed halfway, the data half-exported, the report still not sent. Surviving a dropped connection is not a nice extra. It is the pass mark for a browser terminal.
An allowlist is not distrust of users; it protects you
The moment a terminal is connected, the first question is what users may type. The answer can only be an allowlist: only the commands you list are allowed, everything else is refused. A blocklist — "everything except these few dangerous ones may run" — does not work for terminals. You can never list every dangerous variant: ban rm today and someone deletes things with dd tomorrow, and the day after that someone does it with a pipeline combination you have never seen. An allowlist flips the default: nothing is allowed unless you have named it. A new command gets in only after you review it. It looks rigid, but it is the only approach you can sleep soundly with.
Three kinds of commands are red lines, never to be allowed. The first is anything that deletes or damages the system: rm, dd, mkfs — commands that touch the filesystem directly, where one slip or one malicious input can wipe a whole machine. The second is anything that reaches the outside network: curl and wget sending requests out. Allow those and users can use your server as a stepping stone to scan other sites and fetch things they should not, and the blame lands on you. The third is anything that writes to system directories: writing into /etc, /usr, or system configuration. Whatever environment your service runs in, there are directories that must not be touched, and that line needs a second lock in the sandbox section — an allowlist alone is not enough.
How to make an allowlist without annoying people is a product question. More commands is not better; commands that match the task are better. Cloud Workshop users run data-processing scripts, so the allowlist is built around that: run a script, read logs, list files, export data, plus a few commands to check status — a dozen or so is enough. What if a user wants a command outside the allowlist? Give them a clear path: the interface should say "this command is not in the allowed set; if you genuinely need it, apply here," instead of coldly replying command not found. When users are refused, what frustrates them most is not "no" — it is not knowing why not, or who to ask.
One point that is easy to miss: arguments need controlling too. Allowing ls is not enough, because ls /etc/passwd and ls ./data are two different things. The allowlist has to work at the level of command plus argument template: ls is allowed, but only for listing things under the working directory; scripts may run, but only scripts the user uploaded themselves. Argument checks must happen on the server. The checks in the browser only exist to warn the user earlier; they cannot be trusted. Remember: every check in the browser is decoration. The server-side layer is the real gate.
Sandboxes, three tiers: how much you pay, how safe you feel
The allowlist controls what may be typed; the sandbox controls how far the damage spreads if something goes wrong. The two layers have to ship together — one without the other is the same as neither. Sandboxes come in three tiers, and cost and peace of mind rise together. Which tier to pick depends on your users and your budget.
The first tier is a WebAssembly sandbox inside the browser. Commands do not run on a server at all; they run in a small environment in the browser using WebAssembly. The upside is cost: no server bill, users are isolated from each other by nature, and if something breaks it only breaks inside that user's own browser. The downside is capability: it cannot run genuinely large scripts or read data on the server, so it fits teaching, demos, and light computation. If your product teaches people to write commands, practice, and run small examples, the first tier is enough. Do not spend more.
The second tier is container isolation. Each session gets one container, commands run inside it, and it is destroyed when done. The upside is thorough isolation: users cannot interfere with each other, and if something breaks it only breaks one container. The downside is real cost: each container needs memory, CPU, and startup time, and as concurrency grows, so does the bill. Cloud Workshop uses this tier: Lin Xiao's cleaning script runs in her own container, reads her own data, and the container is reclaimed when done, leaving nothing behind. Containers also carry a hidden cost: images need maintaining and startup speed needs tuning, and whether a user waits three seconds or ten to open a terminal makes a big difference to how it feels. Smaller images and better warm-up mean shorter waits.
The third tier is a restricted account on the backend. Commands run directly on the server, but under a dedicated account with very low privileges that can only read and write its own directories and only use allowlisted commands. The upside is that it is the cheapest and fastest, with almost no startup cost. The downside is the weakest isolation: one vulnerability can reach the whole machine. This tier only fits two situations: all your users are trusted internal employees, or your allowlist is extremely tight and the commands can be counted on one hand. Personal projects and internal tools can start here, but anything open to the public should move to containers from day one. The server money saved ends up as the bill for a security incident.
Too much output breaks everything: streaming, truncation, paging, search
The easiest place for a terminal to fail is not a command that will not run — it is a command that runs and produces too much output. Lin Xiao runs her cleaning script over ten thousand rows of data, one result line per row, and the output keeps scrolling for three minutes. On the browser side xterm.js keeps writing furiously, memory climbs, the page gets slower, and finally the whole tab freezes. What the user sees is not a result but a page that will not move. This is the most unfair kind of failure: the command actually finished, and the product died on the last mile of showing it.
The first valve is streamed output with throttling. Write output to the screen in chunks as it arrives instead of waiting to accumulate it, and throttle it: when too much arrives in a short time, merge it before writing. Human eyes cannot read dozens of lines a second, so writing faster is pointless. Throttling also saves memory: only the most recent few thousand lines stay on screen, while older output moves into a history buffer that can still be scrolled to but does not take up rendering work.
The second valve is truncation. A single command's output needs a cap — say one hundred thousand lines or fifty MB — and when it is reached, stop and tell the user "output truncated; the full result is in a file, download it there." The cap is not stinginess; it is protection. A terminal with no cap is a balloon waiting to burst. When truncating, say clearly where it was cut, where the full output lives, and how to get it. Users do not mind being truncated. They mind being truncated without being told.
The third valve is paging and search. When output runs past one screen, what users need is not "keep scrolling" but "jump to the part I want." Paging loads output in blocks and fetches the next block at the bottom; search finds keywords in the output, such as ERROR or one order number. Both are simple to build and they double the experience. Search especially: after running a command, the first thing a user often does is press Ctrl+F to find something, but the browser's own find box barely works inside xterm.js, so you need your own search box in the terminal panel. It is a small thing, but users reach for it every day.
Refreshing the page must not kill the terminal
Web pages have a built-in flaw: refreshing loses state. That is fine for an ordinary page, which just loads again. It is not fine for a terminal — the command a user is running and the output already produced would vanish on refresh, and the user would feel your product threw their work away. Session persistence exists to fix exactly this: refreshing does not break the connection, and coming back means picking up where you left off.
The way to do it is to untie the session from the page. The session lives on the server and has its own ID; the browser only stores that ID. Refresh the page, close and reopen the tab, even switch devices — as long as you come back carrying the ID, you reconnect to the same session and see the earlier output. That is the whole secret of "refresh does not break the line": the ID is the session's identity card, and the page is only the window looking at it.
Reconnecting is not enough on its own; there has to be history playback too. When a user reconnects, the first thing they should see is not a blank terminal but how far the output had got before they left. The server has to store each session's output — with a cap, such as the most recent five thousand lines — and on reconnection push that history to the browser first, then continue with new output. The order cannot be wrong: history first, new output after, nothing inserted in between, no lines dropped. Lose one line and the user no longer knows how far the command got. Done well, session persistence makes users feel your terminal is "reliable," and in a tool product that is the most valuable thing anyone can say about it.
Mobile is the easiest part to forget, and the first place it shows
Back to Lin Xiao: she uses the terminal on a tablet. Many teams build a browser terminal, test it entirely on a computer, and only discover at launch that it is unusable on phones and tablets. Mobile is not a "quick responsive tweak." It is a different way of typing, with three problems a desktop never has.
The first problem is the virtual keyboard. Phones and tablets have no physical keyboard. Tap an input box and the virtual keyboard slides up from the bottom, covering half the screen and leaving the terminal only a few lines tall. The fix is to make the terminal panel move with the keyboard: when the keyboard appears, the terminal shrinks upward so the input line stays visible above it; when the keyboard hides, the terminal expands again. One more detail: the enter and switch keys on virtual keyboards behave differently on iOS and Android, so both systems need testing on real devices before launch. A simulator will not catch this. You have to tap it on a real phone.
The second problem is missing shortcuts. Desktop terminal users press Ctrl+C, Ctrl+L, and Tab to complete without thinking; on mobile, those keys are all gone. A user who cannot press Ctrl+C cannot stop a runaway command and can only wait; without Tab completion, a long file name has to be typed one letter at a time. The fix is a row of virtual function keys on the terminal panel: Ctrl, Tab, arrow keys, Esc, as a permanent small keyboard where one tap equals one key press. It does not matter if the row is ugly. Working matters more than pretty. The keys Lin Xiao uses most on her tablet are Tab and Ctrl+C in that row; without them, she cannot get anything done on the train.
The third problem is paste. On a desktop, copy and paste is muscle memory. On mobile it is long-press, wait for the menu, tap paste — three steps. Worse, browser security rules mean a web page needs the user's explicit permission to read the clipboard, and some browsers refuse outright. The fix is a visible "Paste" button: one tap asks the browser for permission once, and pastes into the terminal when granted; long-pressing the terminal area should also bring up a paste menu. Copying a command from somewhere else and pasting it into the terminal is the most common action on mobile. If that chain breaks, the mobile terminal is decoration.
Who ran what: you need a record
Once a terminal can run commands, it stops being an interface feature and becomes a doorway to action. A doorway needs a ledger: who ran what command, when, and what came out. The ledger is not there to watch users. It exists so that when something goes wrong, the story can be told. Data deleted, a setting changed wrongly, a bill suddenly jumping — the first question is always "who did it." Without a ledger, nobody can answer, and in the end everyone shares the blame.
At minimum, the ledger should record four things: who the user is, the session ID, the full command text, and the time and result. The command text must be recorded exactly as typed, arguments included; recording half of it is the same as recording nothing. The result should at least say success or failure, and how long it ran. The output itself does not need recording in full — output is too large and storing all of it costs too much — but keep a summary or the first few lines so the incident can be located later. How long records are kept also needs deciding: thirty to ninety days is typical, longer for sensitive areas such as finance or healthcare. How long is not a guess; it should match your compliance requirements and be written into the docs.
Recording alone is not enough; sensitive commands need a second confirmation. Commands that delete data, change settings, send requests outside, or touch production should show a confirmation dialog before running, displaying the command exactly as it will run, so the user reads it once more and clicks confirm again. A second confirmation is not there to annoy users; it is there to catch a slip of the hand. Typing the wrong letter in a terminal is routine, and the dialog is the last gate. It should state clearly what the command will do and how much it affects — not just "are you sure?" A confirmation the user cannot understand is the same as no confirmation. Permissions need layering too: ordinary users run only their own scripts, while only admins run restarts and setting changes. The layers should follow the permission system your product already has; do not build a second one inside the terminal.
Timeouts and limits: do not let one session drag down the machine
A terminal session is a living resource: it eats CPU, eats memory, and holds connections. One user running an infinite loop, or one session left alone with nobody watching, can drag a whole machine down. Resource limits have to be set from day one, not patched in after the machine falls over. Setting limits is not stinginess; it is what lets every user have a terminal at all.
There are three layers of limits. The first is per command: how long one command may run — ten minutes, say — after which it is killed and the user is told "command timed out and was stopped." The second is per session: how much CPU and memory one session may use before it is throttled or killed. The third is the total number of sessions: how many sessions one machine may hold at once; when full, queue new ones and tell the user "it is busy right now, please wait a moment," instead of quietly accepting the new session and slowing everyone down.
Reclaiming zombie sessions is the other half of the job. A user closes the page and walks away, and the session stays on the server with nobody watching — that is a zombie session. The reclaim rule has to be written down: reclaim a session after how long idle, thirty minutes without input, say; and whether to warn the user first, for instance by printing a line in the terminal five minutes ahead: "this session will be reclaimed in five minutes; type any command to keep it." Reclaiming also needs a clean ending: what happens to a command still running — wait for it to finish, or kill it outright — and that has to be stated up front, so users do not come back to find their work half done with no ending. There is no standard answer for these numbers; start conservative, watch a week of real usage, then loosen them. Starting tight and loosening slowly is easy; starting loose and tightening later is not.
When the connection drops, do not pretend nothing happened
Connections will drop. The only question is what you show the user when they do. The worst approach is to say nothing: the terminal sits still, and the user cannot tell whether the command finished, the network dropped, or your service went down, so they keep pressing Enter to test it. That kind of silence damages trust the most: the user does not know what happened, and does not know whether to wait or start over.
The right approach is to state the situation plainly. When the connection drops, a notice appears at the top of the terminal: "Connection lost, reconnecting (attempt 1 of 3)." When reconnection succeeds, the notice goes away and output continues. Reconnection needs a cap — three attempts, say — with growing gaps between them. If the cap is reached without success, stop and say it plainly: "Connection failed. Check your network, then tap here to retry."
There is one iron rule: never silently drop output. While the connection is down, the command on the server may still be running and still producing output. When the connection comes back, that output has to be caught up, not treated as if it never happened. If it cannot be recovered, say so clearly: "Some output from the disconnected period could not be recovered; download the full log here." Users can accept "it was lost, but you told me it was lost and gave me a way to fix it." They cannot accept "it was lost, and you pretended it was not."
Doing the math: out of 1,000 people, 96 come back the next day
So far this has all been about how to build it. Now the math: will users actually use a terminal once it exists? The funnel below is a fictional sample, used to work the reasoning out clearly, not real data: out of 1,000 visits, 540 people opened the terminal, 54.0%; of those 540, 300 ran their first command successfully, 55.6%; of those 300, 170 finished a task with it, 56.7%; of those 170, 96 came back the next day, 56.5%. End to end, that is 9.6% overall. Checking the losses: 460 never opened the terminal, 240 opened it but did not get a command through, 130 got a command through but did not finish a task, 74 finished a task but did not return, plus the 96 who did return — 460+240+130+74+96=1000, and the math balances.
The most interesting part of this funnel is not the final 9.6% but the first step, 54.0%. Out of 1,000 people, 460 never opened the terminal at all. They did not open it because they never found it, or found it and had no idea what it was for. An entry point buried too deep, a name too technical, no explanation next to it — any of these bleeds this step away. To improve it, do not rush to add features; put the entry point where the user hits the problem: a "run a script in the terminal" button beside the data-processing page, an "open the terminal to see the full log" link under an error message. The closer the entry point is to the problem, the higher the open rate.
The third step, 56.7%, and the fourth, 56.5%, are about the same thing: did the terminal actually get the user's work done? Running one command is not finishing a task, and finishing a task is not coming back tomorrow. Users return because last time the terminal saved them time. Saving time does not come from the terminal itself but from the sum of every detail in the sections above: reconnections that do not break, output that does not freeze, a terminal that works on a phone, and errors that are explained instead of hidden. Every step of this funnel maps to something covered earlier. Keep this chart, replace the fictional numbers with real data after launch, and fix first whichever step falls hardest.
The smallest working version: five things first, everything else after
Where to start when it comes to building all this? My suggestion is a smallest working version with just five things: the basic connection of xterm.js plus WebSocket plus PTY; an allowlist with a dozen or so commands tied directly to the task; container isolation, one container per session; reconnection, with the session kept running on the server; and output truncation and caps, so the browser cannot be overwhelmed. With those five in place, the terminal can go live for real users.
Finally, back to Lin Xiao. On the train she opened the terminal, typed one command, re-exported the report, and sent it to the client. She installed nothing, set up no keys, and never left the browser. If your product also has a "Lin Xiao" — and a moment that is only one command away from solved — it is worth the time to embed a terminal. A terminal is not showing off. It is fixing the last mile. Fix the road, and users will walk down it.
Comments (0)
Related articles
Flexbox lays things out in one direction at a time, and when it is done right, the nav bar, the card wall, and the cart rows all behave. This guide follows MDN's Basic concepts of flexbox, Aligning items in a flex container, and Controlling ratios of flex items along the main axis: the two axes, containers and items, direction and wrapping, free space, the three flex properties, alignment on both axes, and gaps and auto margins.
One order is one object: table, dishes, total, paid — all filed by label. This guide follows MDN's Working with objects, JSON, and Object references: object literals, dot vs bracket notation, adding and deleting properties, for...in with hasOwn, methods and this, getters and setters, references vs copies, Object.assign and friends, null-prototype objects, JSON's strict rules, and stringify and parse with their number-precision trap.
On 17 November 2026, Microsoft launched MAI Code 2 and Code 2 Flash: the larger model has 77 billion active parameters and a one-million-token context, averaging 63.2% across four benchmarks — close to GPT-6.1 Sol and Claude Opus 5.5 — at $0.309 per task. Read the three caveats first: promotional pricing, the lowest score of the three, and no long-horizon work.