--- slug: "monotykamary-pi-localterm" source_type: "readme" source_url: "https://cdn.jsdelivr.net/gh/monotykamary/localterm@main/README.md" repo: "https://github.com/monotykamary/localterm" source_file: "README.md" branch: "main" --- # localterm [![version](https://img.shields.io/npm/v/@monotykamary/localterm?style=flat&colorA=000000&colorB=000000)](https://npmjs.com/package/@monotykamary/localterm) [![downloads](https://img.shields.io/npm/dt/@monotykamary/localterm.svg?style=flat&colorA=000000&colorB=000000)](https://npmjs.com/package/@monotykamary/localterm) Your terminal should just be a browser tab. Run `npx @monotykamary/localterm@latest start` and every browser tab is one shell. Open a new tab to spawn another. Close a tab and its shell waits in the session switcher (top-right) for a short grace window — switch back to it in that window, or it's reaped. That's the whole product. ![demo](https://www.localterm.dev/demo.png) ## Install ```bash npx @monotykamary/localterm@latest start ``` This boots a local daemon and opens a browser tab. The URL depends on what's installed on the machine — `localterm status` shows the active one: | Surface | URL | Requires | | ------------ | --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | **tailnet** | `https://.ts.net` | [Tailscale](https://tailscale.com) connected, HTTPS certs enabled for the tailnet | | **local** | `https://localterm.localhost` | `portless` (installed via `localterm install`) | | **loopback** | `http://localterm.localhost:3417` | nothing — `.localhost` resolves to `127.0.0.1` via [RFC 6761](https://datatracker.ietf.org/doc/html/rfc6761), no `/etc/hosts` edit needed | To install globally: `npm install -g @monotykamary/localterm && localterm start`. ## Usage The mental model is **shell = browser tab**: - **New tab** → new shell. - **Close tab** → the shell detaches and waits in the session switcher (top-right) for ~30s; reattach in that window or it's reaped. A shell still producing output (a build) or running a foreground program (a `sleep`) is kept alive, so a closed tab never kills a running command. - **Reload tab** → fresh shell (the prior one waits in the switcher like a closed tab). - **Switch** → the session switcher (top-right, or ⌘/Ctrl+I) re-points this tab at any live shell; search by title, path, or shell. Transient connection drops silently reattach to the same shell. If you want a shell that survives a full page reload in the _same_ tab, run `tmux` _inside_ localterm. → full model in [Usage](https://github.com/monotykamary/localterm/blob/HEAD/docs/usage.md). ## Features | | | | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 🐚 [**Shells**](https://github.com/monotykamary/localterm/blob/HEAD/docs/shells.md) | Pick a shell per tab, per CLI call, or globally (`LOCALTERM_SHELL`); login profiles + OSC 7 / git-dirty hooks for zsh, bash, fish. | | 🎨 [**Themes & fonts**](https://github.com/monotykamary/localterm/blob/HEAD/docs/appearance.md) | 20 built-in themes (16 dark + 4 light) + **Auto (system)**; import your own (JSON or iTerm `.itermcolors`); 11 bundled fonts + a custom system Nerd Font — all offline. | | ⏰ [**Automations**](https://github.com/monotykamary/localterm/blob/HEAD/docs/automations.md) | Scheduled + folder-watch + event + webhook jobs; shell or headless agent runners; background tabs. | | 🚀 [**Auto-start & remote access**](https://github.com/monotykamary/localterm/blob/HEAD/docs/auto-start.md) | launchd (macOS) / systemd user unit (Linux); Tailscale or an ssh tunnel turns a VPS into an ssh + tmux replacement. | | 🔐 [**Identity & SSO**](https://github.com/monotykamary/localterm/blob/HEAD/docs/identity.md) | Multi-user access via `header` (reverse proxy), `passkey` (WebAuthn), or `oidc`. | | 🤖 [**pi integration**](https://github.com/monotykamary/localterm/blob/HEAD/docs/pi.md) | Kitty graphics + OSC 8 links, and secret scrubbing for pi's bash tool. | | 🛡️ [**Security**](https://github.com/monotykamary/localterm/blob/HEAD/docs/security.md) | Loopback-bound by default; DNS-rebinding defense; safe sharing. | ## CLI ```bash localterm start [-p 3417] [-H 127.0.0.1] [--open] # daemonizes by default localterm stop | status | restart localterm install # auto-start service + URL surfaces + completions localterm exec "" [--cwd ] [--shell ] [--json] # one-shot: run, capture, exit with its code localterm session new|ls|attach|exec|capture|kill … # tmux-parity PTY control localterm secret list|get|set|delete # Keychain-backed per-program secrets ``` State lives in `~/.localterm/` (PID, port, server log at `~/.localterm/server.log`). → full reference in [CLI](https://github.com/monotykamary/localterm/blob/HEAD/docs/cli.md). ## Resources & contributing - 🐛 [Issue tracker](https://github.com/monotykamary/localterm/issues) · 💬 [Pull requests welcome](https://github.com/monotykamary/localterm/blob/main/CONTRIBUTING.md) - 📖 [**Full docs**](https://github.com/monotykamary/localterm/blob/HEAD/docs/README.md) · 🤝 [Contributing guide](https://github.com/monotykamary/localterm/blob/main/CONTRIBUTING.md) · 📝 [AGENTS.md](https://github.com/monotykamary/localterm/blob/main/AGENTS.md) (code style) ### License localterm is MIT-licensed open-source software.