VibeTunnel: The Browser-as-Terminal Proxy That Lets You Command Your Machine From Anywhere
Hook
What if you could check on your long-running AI coding agent from your phone’s browser without touching SSH keys, port forwarding, or VPN configs? VibeTunnel makes this work with a single command.
Context
Remote terminal access has been stuck in the SSH paradigm for decades. Whether you’re traveling and want to check if your test suite finished, or you’re curious if your AI agent crashed after attempting its 47th code refactor, you typically reach for SSH—assuming you’ve set up keys, configured port forwarding, and can remember if you’re on port 22 or 2222 this time. Mobile SSH clients exist but they’re clunky, and keeping SSH access secure across devices is a chore most developers tolerate rather than enjoy.
VibeTunnel takes a different approach: instead of securing shell access through cryptographic protocols, it intercepts your local terminal sessions and streams them to a local web server. Your terminal output becomes a WebSocket stream that any browser can consume. The result is a zero-config way to peek at your terminal from another device on your network, or share what’s happening in your shell with a colleague. It’s particularly useful in the age of AI coding agents—tools like Cursor, Aider, or Cody that run in your terminal for extended periods. VibeTunnel gives you a “check in” mechanism without context-switching to your development machine.
Technical Insight
VibeTunnel’s architecture centers on a command wrapper and streaming pipeline. At its core, the system provides a vt command that you prefix to any shell invocation. When you run vt zsh or vt bash, VibeTunnel spawns a pseudoterminal (PTY), captures all input and output, and forwards it through a local forwarding process. Here’s what a basic session looks like:
# Start VibeTunnel forwarding in the background
vibetunnel fwd &
# Launch your shell through VibeTunnel
vt zsh
# Now browse to http://localhost:4020
# Your terminal appears in real-timeUnder the hood, VibeTunnel maintains a Node.js server process that manages multiple terminal sessions simultaneously. Each session is identified and tracked, with the browser UI providing visual indicators for which terminals have recent activity. The server uses WebSocket connections to push terminal output to connected browsers with minimal latency—you see keystrokes and command output almost instantly.
The session recording mechanism deserves particular attention. VibeTunnel automatically writes every session to asciinema format, a JSON-based terminal recording standard. This means every command you run, every output line, and every timing detail is preserved without any additional tooling. The asciinema format stores events as timestamped JSON objects, making it trivial to replay sessions later or parse them programmatically. For teams running AI agents overnight, this becomes an automatic audit log of what the agent attempted.
The most interesting architectural choice is the dual-distribution model. VibeTunnel ships both as a native macOS menu bar application (built specifically for Apple Silicon) and as an npm package. The macOS app provides a GUI for starting/stopping the service and quick access to the web dashboard, while the npm version (npx vibetunnel fwd) works headlessly on Linux servers or in CI environments. The system intelligently detects when the native app is running and defers to it, preventing port conflicts.
Git Follow Mode showcases creative integration with developer workflows. When enabled, VibeTunnel watches for IDE focus changes and automatically switches the displayed terminal session to match whatever Git branch you’re working on. This is implemented through filesystem watching and process monitoring:
// Conceptual example of Git Follow Mode logic
watchIDEFocus((activeProject) => {
const branch = getCurrentGitBranch(activeProject);
const matchingSession = sessions.find(s =>
s.workingDirectory.includes(activeProject) &&
s.gitBranch === branch
);
if (matchingSession) {
switchActiveDashboardSession(matchingSession.id);
}
});The browser interface uses keyboard shortcuts (Cmd/Ctrl+1-9) for rapid session switching, mimicking tmux-style window management but accessible from any device with a browser. Sessions display activity indicators—visual badges that highlight which terminals have produced output since you last viewed them. This attention management system becomes critical when monitoring multiple AI agent sessions or long-running build processes across different projects.
The forwarding mechanism itself is elegantly simple: vibetunnel fwd establishes the local server on port 4020 and begins listening for vt-wrapped sessions. There’s no cloud dependency, no account creation, and no external services. Everything runs on your machine, which means your terminal output never leaves your local network unless you explicitly tunnel it out (via ngrok or similar). For security-conscious developers, this localhost-only approach is refreshing—you get remote access conveniences without shipping your terminal contents to third-party servers.
Gotcha
Platform support is VibeTunnel’s biggest constraint. The recommended native macOS app requires Apple Silicon (M1, M2, M3+ chips), which immediately excludes anyone on Intel-based Macs from the optimal experience. While they can fall back to the npm package, they lose the menu bar integration and GUI conveniences. More significantly, Windows support is completely absent—there’s no native app, and the npm package doesn’t support Windows terminal environments. If your team uses mixed platforms, you’ll face adoption friction.
The first-run experience on macOS can be jarring. VibeTunnel scans your filesystem for Git repositories to enable features like Git Follow Mode. On modern macOS, this triggers a cascade of permission dialogs for privacy-protected folders (Desktop, Documents, Downloads, etc.). Each prompt interrupts your flow, and if you deny any of them, VibeTunnel’s Git integration may behave unpredictably in those directories. This is an OS limitation rather than VibeTunnel’s fault, but it creates setup friction that SSH-based alternatives don’t have.
The localhost-only default is both a feature and a limitation. While it’s excellent for security, accessing your terminal from outside your local network requires additional tunneling tools (ngrok, Tailscale, Cloudflare Tunnel). VibeTunnel doesn’t provide this out of the box, which means truly remote access—checking your terminal from a coffee shop, for instance—requires combining VibeTunnel with another tool. At that point, you might question whether SSH would’ve been simpler.
Verdict
Use VibeTunnel if you’re on macOS or Linux and frequently need casual access to terminal sessions from other devices on your local network—particularly when monitoring AI coding agents, long-running builds, or processes you want to check without SSH ceremony. It’s especially valuable if you work across multiple Git branches simultaneously and want automatic context switching, or if you need automatic session recording without configuring asciinema separately. The browser-based UI makes it trivial to share what’s happening in your terminal during pair programming or demos. Skip it if you’re on Windows, need Intel Mac support for the native experience, already have a comfortable SSH workflow, or require robust remote access from outside your network without additional tunneling tools. The platform limitations and permission-prompt friction during setup make it a poor fit for heterogeneous development teams, but for Mac-centric shops doing AI-assisted development, it solves real workflow friction.
