overmux 0.0.1 → 0.0.2

package/dist/docs/000-index.md

@@ -0,0 +1,21 @@
+---
+title: Overmux documentation
+description: Build and understand an Overmux application.
+---
+
+# Overmux documentation
+
+Overmux is a local or self-hosted web UI for tmux sessions, Pi agents, and Git workspaces.
+
+- [What is Overmux?](./100-introduction/100-what-is-overmux.md)
+- [How Overmux Works](./100-introduction/200-how-overmux-works.md)
+- [Why Overmux?](./100-introduction/300-why-overmux.md)
+- [Install and Run Overmux](./200-getting-started/100-install-and-run-overmux.md)
+- [Install Overmux Desktop](./200-getting-started/200-install-overmux-desktop.md)
+- [Install Overmux PWA](./200-getting-started/300-install-overmux-pwa.mdx)
+- [Choose an HTTPS Setup](./200-getting-started/400-secure-with-https/100-choose-an-https-setup.md)
+- [Tailscale Serve](./200-getting-started/400-secure-with-https/200-tailscale-serve.md)
+- [Cloudflare Tunnel](./200-getting-started/400-secure-with-https/300-cloudflare-tunnel.md)
+- [Self-hosted Reverse Proxy](./200-getting-started/400-secure-with-https/400-self-hosted-reverse-proxy.md)
+
+Run `overmux docs` to print the absolute path to this installed documentation directory.

package/dist/docs/100-introduction/100-what-is-overmux.md

@@ -0,0 +1,7 @@
+---
+title: What is Overmux?
+---
+
+Overmux is a web-based, customizable dev environment. Designed for coding using Agents.
+
+

package/dist/docs/100-introduction/200-how-overmux-works.md

@@ -0,0 +1,7 @@
+---
+title: How Overmux Works
+---
+
+Overmux is a [light-weight web framework](oxymoron definition), designed to be run in an Electron shell, a PWA on your phone, or a mobile app.
+
+It's highly customizable

package/dist/docs/100-introduction/300-why-overmux.md

@@ -0,0 +1,22 @@
+---
+title: Why Overmux?
+---
+
+As AI coding agents have improved my time has shifted from:
+
+- Writing code in an IDE
+- Running commands manually
+
+To:
+
+- Talking to agents
+- Reviewing code produced by agents
+- Trying to "orient" myself in codebases and keep in touch with how things work
+- Spawning and keeping track of agents
+- Coding on my phone
+
+I lived in a customized tmux setup. But kept noticing that that the terminal, for all it's glory, might not be the best place to build the experiences needed, especially for code review and mobile.
+
+[Herdr](https://github.com/herdrdev/herdr) (a TUI) and [Orca](https://github.com/stablyai/orca) (web based) offer a decent default experience. But they lack the customizability I love with the terminal and neovim. They use their own muxer implementations and dictate workflows.
+
+This future filled me with existential dread, so I built Overmux to embed my terminal in a Desktop webapp and build my own experience with a mix of tmux terminals + custom web uis.

package/dist/docs/200-getting-started/100-install-and-run-overmux.md

@@ -0,0 +1,51 @@
+---
+title: Install and Run Overmux
+---
+
+First you need to install the `overmux` CLI.
+
+### Recommended: Install with Mise
+
+[Mise](https://mise.jdx.dev) installs and manages developer tools and their versions.
+
+1. [Install Mise](https://mise.jdx.dev/getting-started.html).
+
+2. Install Overmux globally:
+
+   ```bash
+   mise use --global npm:overmux
+   ```
+
+### Alternatively: Install with pnpm
+
+Prerequisites:
+
+- [Node.js 22](https://nodejs.org/en/download) or newer
+- [pnpm 10](https://pnpm.io/installation) or newer
+
+Install Overmux globally:
+
+```bash
+pnpm add --global overmux
+```
+
+## Initialize Overmux
+
+Once the CLI is installed, create your Overmux setup:
+
+```bash
+overmux init
+```
+
+This creates your setup in `$XDG_CONFIG_HOME/overmux`. Read more about the Overmux [project structure](../300-fundamentals/100-project-structure.md).
+
+## Start the server
+
+```bash
+overmux serve
+```
+
+Open Overmux in your browser to confirm it works.
+
+To configure hosts and ports, see [Configuration](../300-fundamentals/200-configuration.md).
+

package/dist/docs/200-getting-started/200-install-overmux-desktop.md

@@ -0,0 +1,41 @@
+---
+title: Install Overmux Desktop
+---
+
+Overmux Desktop makes your already-running Overmux web server feel like a native app, with notifications.
+
+## macOS
+
+### Install using the CLI
+
+After installing the Overmux CLI:
+
+```bash
+overmux desktop install
+```
+
+Overmux Desktop is installed in `~/Applications/Overmux.app`.
+
+### Install from GitHub
+
+Download the ZIP for your Mac from the [Overmux releases](https://github.com/richardgill/overmux/releases), extract it, then move `Overmux.app` to `~/Applications`.
+
+Overmux is not currently signed or notarized. Follow [Apple's instructions for opening an app from an unidentified developer](https://support.apple.com/en-us/102445) to allow it to run.
+
+## Linux
+
+Download the AppImage or Debian package from the [Overmux releases](https://github.com/richardgill/overmux/releases).
+
+For the AppImage:
+
+```bash
+chmod +x Overmux-Desktop-<version>-linux-x64.AppImage
+./Overmux-Desktop-<version>-linux-x64.AppImage
+```
+
+For Debian-based distributions:
+
+```bash
+sudo apt install ./overmux-desktop_<version>_amd64.deb
+overmux-desktop
+```

package/dist/docs/200-getting-started/300-install-overmux-pwa.mdx

@@ -0,0 +1,92 @@
+---
+title: Install Overmux PWA
+---
+
+Overmux is a [progressive web app (PWA)](https://developer.mozilla.org/en-US/docs/Web/Progressive_web_apps), so you can install it on a mobile device. The installed app gets its own home screen icon and opens in a standalone window.
+
+<Callout type="warning">
+  PWAs must be hosted on HTTPS. See [Choose an HTTPS setup](./400-secure-with-https/100-choose-an-https-setup.md).
+</Callout>
+
+## Chrome on Android
+
+Open your Overmux URL and either select the **Add to Home Screen** banner or open the browser menu and select **Install app**. Confirm by selecting **Install**. You can then open Overmux from your home screen or app drawer.
+
+<div style={{ display: "flex", flexWrap: "wrap", gap: "1rem" }}>
+  <ImageZoom
+    alt="The Add to Home Screen banner in Chrome on Android"
+    height={533}
+    src="https://docs.ntfy.sh/static/img/pwa-install-chrome-android.jpg"
+    width={240}
+  />
+  <ImageZoom
+    alt="The Install app menu action in Chrome on Android"
+    height={533}
+    src="https://docs.ntfy.sh/static/img/pwa-install-chrome-android-menu.jpg"
+    width={240}
+  />
+  <ImageZoom
+    alt="The PWA installation confirmation on Android"
+    height={533}
+    src="https://docs.ntfy.sh/static/img/pwa-install-chrome-android-popup.jpg"
+    width={240}
+  />
+</div>
+
+<p style={{ textAlign: "center" }}>
+  <em>Imagine it says overmux, not ntfy, thx</em>
+</p>
+
+## Firefox on Android
+
+Open your Overmux URL, open the browser menu, and select **Install**. Select **Add** to place Overmux on your home screen.
+
+<div style={{ display: "flex", flexWrap: "wrap", gap: "1rem" }}>
+  <ImageZoom
+    alt="The Install menu action in Firefox on Android"
+    height={533}
+    src="https://docs.ntfy.sh/static/img/pwa-install-firefox-android-menu.jpg"
+    width={240}
+  />
+  <ImageZoom
+    alt="The Add to Home Screen confirmation in Firefox"
+    height={533}
+    src="https://docs.ntfy.sh/static/img/pwa-install-firefox-android-popup.jpg"
+    width={240}
+  />
+</div>
+
+<p style={{ textAlign: "center" }}>
+  <em>Imagine it says overmux, not ntfy, thx</em>
+</p>
+
+## Safari on iOS
+
+Open your Overmux URL in Safari, select **Share**, and then select **Add to Home Screen**.
+
+<div style={{ display: "flex", flexWrap: "wrap", gap: "1rem" }}>
+  <ImageZoom
+    alt="The Share button in Safari on iOS"
+    height={520}
+    src="https://docs.ntfy.sh/static/img/pwa-install-safari-ios-button.jpg"
+    width={240}
+  />
+  <ImageZoom
+    alt="The Add to Home Screen action in Safari on iOS"
+    height={520}
+    src="https://docs.ntfy.sh/static/img/pwa-install-safari-ios-menu.jpg"
+    width={240}
+  />
+  <ImageZoom
+    alt="The Add to Home Screen confirmation on iOS"
+    height={520}
+    src="https://docs.ntfy.sh/static/img/pwa-install-safari-ios-add-icon.jpg"
+    width={240}
+  />
+</div>
+
+<p style={{ textAlign: "center" }}>
+  <em>Imagine it says overmux, not ntfy, thx</em>
+</p>
+
+Screenshots adapted from the [ntfy PWA installation guide](https://docs.ntfy.sh/subscribe/pwa/).

package/dist/docs/200-getting-started/400-secure-with-https/100-choose-an-https-setup.md

@@ -0,0 +1,14 @@
+---
+title: Choose an HTTPS Setup
+---
+
+Your Overmux could expose sensitive information or access to your system. If you're exposing overmux anywhere other than localhost, it's a good idea to configure it with HTTPS. HTTPS protects login credentials and session traffic, and browsers require it to install Overmux as a PWA.
+
+Choose a setup that matches how you want to access Overmux:
+
+| Setup | How it works |
+| --- | --- |
+| [Tailscale Serve](./200-tailscale-serve.md) | Connect through a private Tailscale VPN so only devices connected to the VPN can access Overmux. |
+| [Cloudflare Tunnel](./300-cloudflare-tunnel.md) | Connect through a public Cloudflare hostname, optionally protected by Cloudflare Access login. |
+| [Self-hosted reverse proxy](./400-self-hosted-reverse-proxy.md) | Run your own reverse proxy and TLS certificates to securely forward requests to Overmux. |
+

package/dist/docs/200-getting-started/400-secure-with-https/200-tailscale-serve.md

@@ -0,0 +1,44 @@
+---
+title: Tailscale Serve
+---
+
+[Tailscale Serve](https://tailscale.com/docs/features/tailscale-serve) gives Overmux a private HTTPS URL available to devices in your tailnet. Tailscale manages the certificate and forwards requests to Overmux over loopback.
+
+## Configure Overmux
+
+Set the first authentication origin to your machine's Tailscale HTTPS URL. Keep the server bound to the same loopback address and port that Tailscale Serve will target:
+
+```ts
+export default defineOvermuxConfig({
+  auth: {
+    mode: "cli-login",
+    origins: ["https://your-machine.your-tailnet.ts.net"],
+    trustedProxyPeer: "127.0.0.1",
+  },
+  host: "127.0.0.1",
+  port: 4200,
+  // ...
+});
+```
+
+Replace the example origin with the hostname Tailscale assigns to your machine.
+
+## Start Overmux and Tailscale Serve
+
+Start Overmux:
+
+```bash
+overmux serve
+```
+
+In another terminal, publish its loopback listener through Tailscale Serve:
+
+```bash
+tailscale serve --bg http://127.0.0.1:4200
+```
+
+Open the HTTPS URL printed by Tailscale on another device in your tailnet. Run `overmux auth login` to create a login link if authentication is enabled.
+
+Do not expose port 4200 directly or change `trustedProxyPeer` to a non-loopback address. Overmux trusts forwarded HTTPS and host information only from this immediate proxy peer.
+
+See Tailscale's [Serve documentation](https://tailscale.com/docs/features/tailscale-serve) for installation, tailnet access controls, and command reference.

package/dist/docs/200-getting-started/400-secure-with-https/300-cloudflare-tunnel.md

@@ -0,0 +1,59 @@
+---
+title: Cloudflare Tunnel
+---
+
+[Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/) publishes Overmux through a Cloudflare-managed hostname without opening an inbound port on your network. You need a domain managed by Cloudflare.
+
+## Create the tunnel
+
+[Install `cloudflared`](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/downloads/), authenticate it, and create a tunnel:
+
+```bash
+cloudflared tunnel login
+cloudflared tunnel create overmux
+cloudflared tunnel route dns overmux overmux.example.com
+```
+
+Create `~/.cloudflared/config.yml` using the tunnel ID and credentials path printed by `cloudflared tunnel create`:
+
+```yaml
+tunnel: <tunnel-id>
+credentials-file: /home/you/.cloudflared/<tunnel-id>.json
+
+ingress:
+  - hostname: overmux.example.com
+    service: http://127.0.0.1:4200
+  - service: http_status:404
+```
+
+## Configure Overmux
+
+Use the public HTTPS hostname as the authentication origin and trust only the local tunnel process:
+
+```ts
+export default defineOvermuxConfig({
+  auth: {
+    mode: "cli-login",
+    origins: ["https://overmux.example.com"],
+    trustedProxyPeer: "127.0.0.1",
+  },
+  host: "127.0.0.1",
+  port: 4200,
+  // ...
+});
+```
+
+## Start Overmux and the tunnel
+
+Start both processes:
+
+```bash
+overmux serve
+cloudflared tunnel run overmux
+```
+
+Open `https://overmux.example.com`. Run `overmux auth login` to create a login link if authentication is enabled.
+
+The hostname is publicly reachable unless you restrict it. Use [Cloudflare Access](https://developers.cloudflare.com/cloudflare-one/access-controls/) when you want an additional identity check before requests reach Overmux.
+
+See Cloudflare's [tunnel setup guide](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/get-started/) for service installation and production operation.

package/dist/docs/200-getting-started/400-secure-with-https/400-self-hosted-reverse-proxy.md

@@ -0,0 +1,32 @@
+---
+title: Self-hosted Reverse Proxy
+---
+
+Use this option when you already operate a domain, TLS certificates, and a reverse proxy such as Caddy, Nginx, or HAProxy.
+
+Configure the proxy to:
+
+- Terminate HTTPS for your public hostname.
+- Forward HTTP and WebSocket requests to an Overmux loopback listener.
+- Preserve the request host and send single-valued `X-Forwarded-Host` and `X-Forwarded-Proto: https` headers.
+
+Configure Overmux with the exact public origin, loopback listener, and immediate proxy peer:
+
+```ts
+export default defineOvermuxConfig({
+  auth: {
+    mode: "cli-login",
+    origins: ["https://overmux.example.com"],
+    trustedProxyPeer: "127.0.0.1",
+  },
+  host: "127.0.0.1",
+  port: 4200,
+  // ...
+});
+```
+
+Do not expose the loopback backend directly or configure a non-loopback address as `trustedProxyPeer`.
+
+For complete proxy-specific walkthroughs and example configurations, see Open WebUI's [HTTPS and reverse proxy guide](https://docs.openwebui.com/reference/https/). Adapt the upstream address and port to `http://127.0.0.1:4200`, and retain Overmux's origin and trusted-proxy configuration above.
+
+You can also consult the official documentation for [Caddy](https://caddyserver.com/docs/quick-starts/reverse-proxy), [Nginx](https://docs.nginx.com/nginx/admin-guide/web-server/reverse-proxy/), or [HAProxy](https://www.haproxy.com/documentation/haproxy-configuration-tutorials/proxying-essentials/).

package/dist/docs/300-fundamentals/100-project-structure.md

@@ -0,0 +1,3 @@
+---
+title: Project Structure
+---

package/dist/docs/300-fundamentals/200-configuration.md

@@ -0,0 +1,3 @@
+---
+title: Configuration
+---

package/dist/docs/300-fundamentals/300-theming.md

@@ -0,0 +1,3 @@
+---
+title: Theming
+---

package/dist/docs/300-fundamentals/400-server.md

@@ -0,0 +1,3 @@
+---
+title: Server
+---

package/dist/docs/300-fundamentals/500-client.md

@@ -0,0 +1,3 @@
+---
+title: Client
+---

package/dist/docs/300-fundamentals/600-operations.md

@@ -0,0 +1,3 @@
+---
+title: Operations
+---

package/dist/docs/300-fundamentals/700-resources.md

@@ -0,0 +1,3 @@
+---
+title: Resources
+---

package/dist/docs/300-fundamentals/800-streams.md

@@ -0,0 +1,3 @@
+---
+title: Streams
+---

package/dist/docs/300-fundamentals/900-authentication-and-security.md

@@ -0,0 +1,3 @@
+---
+title: Authentication and Security
+---

package/dist/docs/400-reference/100-configuration.md

@@ -0,0 +1,3 @@
+---
+title: Configuration
+---

package/dist/docs/400-reference/200-server-api.md

@@ -0,0 +1,3 @@
+---
+title: Server API
+---

package/dist/docs/400-reference/300-client-api.md

@@ -0,0 +1,3 @@
+---
+title: Client API
+---

package/dist/docs/400-reference/400-cli/100-serve.md

@@ -0,0 +1,33 @@
+---
+title: "overmux serve"
+description: "Serve the Overmux web UI"
+---
+
+# `overmux serve`
+
+Serve the authenticated Overmux web UI. Development starts private Vite behind the public Overmux gateway. Production builds with Vite and serves static assets without running Vite.
+
+## Usage
+
+```text
+overmux serve [--config path] [--host host] [--port port] [--login | --no-login]
+overmux serve --production [--no-build] [--config path] [--host host] [--port port] [--login | --no-login]
+```
+
+## Options
+
+| Flag | Description | Default |
+| --- | --- | --- |
+| `--config <path>, -c <path>` | Configuration file | `$XDG_CONFIG_HOME/overmux/overmux.config.ts` |
+| `--host <host>` | Override the public listener host | Configured host |
+| `--port <port>` | Override the public listener port | Configured port |
+| `--login` | Create and print a browser login grant after startup | Human terminal sessions |
+| `--no-login` | Do not create a grant and print the `overmux auth login` command | Agent, CI, and non-interactive sessions |
+| `--production` | Build and serve `productionWebAssetsDir` |  |
+| `--no-build` | With `--production`, serve existing assets after checking `index.html` exists |  |
+
+`--login` and `--no-login` are mutually exclusive. By default, a human terminal session receives a single-use login grant after the server is ready. Agent, CI, and non-interactive sessions receive `overmux auth login --port <resolved-port>` instead. The explicit flags override this environment-based default.
+
+A grant prints one server-issued URL for every authenticated browser origin. Redeeming its code or any URL consumes the grant and authenticates only that origin; create another grant for another origin. The output identifies the browser login page, expiry, and command for creating another grant.
+
+`--no-build` without `--production` is invalid. Vite's build output cleanup follows its `build.emptyOutDir` setting.

package/dist/docs/400-reference/400-cli/200-auth.md

@@ -0,0 +1,52 @@
+---
+title: "overmux auth"
+description: "Manage CLI-issued browser authentication"
+---
+
+# `overmux auth`
+
+Manage browser login grants and sessions for a running local Overmux server.
+
+Authentication administration uses the private same-user control socket. When multiple local servers are running, use `--port` to select one.
+
+## Create a login grant
+
+```text
+overmux auth login [--code] [--json] [--port value] [--url]
+```
+
+| Flag | Description |
+| --- | --- |
+| `--code` | Print only the login code |
+| `--json` | Print machine-readable JSON |
+| `--port <value>` | Running local server port |
+| `--url` | Print only the primary origin's login URL |
+
+Set at most one of `--code`, `--url`, and `--json`. Default output prints the code, every server-issued URL in order, the exact expiry, and the command for creating another grant. `--url` prints only the primary origin's URL, `--code` prints only the code, and JSON output contains the grant metadata with its ordered `urls` array. Every URL embeds the same secret ticket; the code and ticket belong to one single-use grant. Redeeming any one of them consumes the whole grant and authenticates only that origin, so create another grant to log in at another origin.
+
+## List sessions
+
+```text
+overmux auth list [--json] [--port value]
+```
+
+| Flag | Description |
+| --- | --- |
+| `--json` | Print machine-readable JSON |
+| `--port <value>` | Running local server port |
+
+Session output contains non-secret metadata only, including the browser origin that issued each session. Non-expiring sessions report their expiry as `never`.
+
+## Revoke sessions
+
+```text
+overmux auth revoke [--all] [--json] [--port value] [<id>]
+```
+
+| Flag | Description |
+| --- | --- |
+| `--all` | Revoke every active session |
+| `--json` | Print machine-readable JSON |
+| `--port <value>` | Running local server port |
+
+Specify exactly one session ID or `--all`. Revocation immediately invalidates the selected browser sessions.

package/dist/docs/400-reference/400-cli/300-call.md

@@ -0,0 +1,28 @@
+---
+title: "overmux call"
+description: "Invoke an operation on a running Overmux server"
+---
+
+# `overmux call`
+
+Invoke an operation on a running local Overmux server.
+
+The CLI discovers the local instance and obtains a short-lived bearer credential through its private same-user control socket. Use `--port` to select an instance when multiple local servers are running.
+
+## Usage
+
+```text
+overmux call [--input value] [--port value] <operation-name>
+```
+
+## Arguments
+
+| Argument | Description | Required |
+| --- | --- | --- |
+| `operation-name` | Operation name | Yes |
+## Options
+
+| Flag | Description | Default |
+| --- | --- | --- |
+| `--input <value>, -i <value>` | Operation input as JSON |  |
+| `--port <value>, -p <value>` | Running local server port |  |

package/dist/docs/400-reference/400-cli/400-check.md

@@ -0,0 +1,20 @@
+---
+title: "overmux check"
+description: "Validate an Overmux configuration"
+---
+
+# `overmux check`
+
+Validate an Overmux configuration.
+
+## Usage
+
+```text
+overmux check [--config path]
+```
+
+## Options
+
+| Flag | Description | Default |
+| --- | --- | --- |
+| `--config <path>, -c <path>` | Configuration file | `$XDG_CONFIG_HOME/overmux/overmux.config.ts` |