luv-cli 0.4.0__tar.gz → 0.5.0__tar.gz

{luv_cli-0.4.0 → luv_cli-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: luv-cli
-Version: 0.4.0
+Version: 0.5.0
 Summary: Launch Claude Code or Codex agents on GitHub repos with isolated workspaces and optional Docker dev environments
 Project-URL: Homepage, https://github.com/exospherehost/luv
 Project-URL: Repository, https://github.com/exospherehost/luv
@@ -121,7 +121,9 @@ also keeps reusing its workspace — it names a workspace, where a URL names a P
 | `luv config set\|get\|unset <key> [value]` | Read or write a single setting |
 | `luv config list` | Show all settings |
 | `luv --init` | Configure default GitHub org only |
-| `luv ls [--host H] [--prune] [--no-pr]` | List every live session on every host, with each one's PR link |
+| `luv ls [--host H] [--prune] [--no-pr] [--no-ports]` | List every live session on every host, with each one's PR link and detected ports |
+| `luv ports [<repo> [n]] [--watch [N]]` | Show ports the sessions are listening on; naming one forwards it to localhost |
+| `luv ports --off [<repo> [n]]` | Drop forwards again |
 | `luv continue [<repo> [number]]` | Attach to a live session |
 | `luv handover [<repo> [n]] --to HOST` | Move a session to another machine and resume it there |
 | `luv rm <session\|workspace>...` | Kill a session and delete its workspace on its host |
@@ -235,6 +237,20 @@ luv continue                        # reattach exactly where you left off
 
 Use `--local` for a one-off local run, `-s HOST` to target a different machine, and `-i PATH` for a different SSH key.
 
+### Reaching servers the agent started
+
+Agents working on a remote start servers there. luv finds them and forwards them to this machine on the same port number wherever it's free, so the URL in the agent's output is the URL that works for you.
+
+```bash
+luv ls                       # PORTS column: what was detected, on every session
+luv ports myrepo 42          # forward that session's ports to localhost
+luv ports --off myrepo 42    # drop them again
+```
+
+The session you're **attached to** is forwarded automatically as servers come and go, and announces each one on the tmux status line (`luv: localhost:3000 → dashboard`) — nothing to run. Everything else is opted in by name, because a busy host carries dozens of sessions and they shouldn't all claim local ports uninvited.
+
+Both processes under the session's tmux pane and Docker Compose stacks belonging to the workspace are found; forwards bind `127.0.0.1`, and they outlive detaching so a long-running session stays reachable.
+
 ### Handing a session to another machine
 
 Start something on your laptop, then move it — workspace, uncommitted work, and the agent's conversation — to a machine that won't go to sleep:

{luv_cli-0.4.0 → luv_cli-0.5.0}/README.md

@@ -98,7 +98,9 @@ also keeps reusing its workspace — it names a workspace, where a URL names a P
 | `luv config set\|get\|unset <key> [value]` | Read or write a single setting |
 | `luv config list` | Show all settings |
 | `luv --init` | Configure default GitHub org only |
-| `luv ls [--host H] [--prune] [--no-pr]` | List every live session on every host, with each one's PR link |
+| `luv ls [--host H] [--prune] [--no-pr] [--no-ports]` | List every live session on every host, with each one's PR link and detected ports |
+| `luv ports [<repo> [n]] [--watch [N]]` | Show ports the sessions are listening on; naming one forwards it to localhost |
+| `luv ports --off [<repo> [n]]` | Drop forwards again |
 | `luv continue [<repo> [number]]` | Attach to a live session |
 | `luv handover [<repo> [n]] --to HOST` | Move a session to another machine and resume it there |
 | `luv rm <session\|workspace>...` | Kill a session and delete its workspace on its host |
@@ -212,6 +214,20 @@ luv continue                        # reattach exactly where you left off
 
 Use `--local` for a one-off local run, `-s HOST` to target a different machine, and `-i PATH` for a different SSH key.
 
+### Reaching servers the agent started
+
+Agents working on a remote start servers there. luv finds them and forwards them to this machine on the same port number wherever it's free, so the URL in the agent's output is the URL that works for you.
+
+```bash
+luv ls                       # PORTS column: what was detected, on every session
+luv ports myrepo 42          # forward that session's ports to localhost
+luv ports --off myrepo 42    # drop them again
+```
+
+The session you're **attached to** is forwarded automatically as servers come and go, and announces each one on the tmux status line (`luv: localhost:3000 → dashboard`) — nothing to run. Everything else is opted in by name, because a busy host carries dozens of sessions and they shouldn't all claim local ports uninvited.
+
+Both processes under the session's tmux pane and Docker Compose stacks belonging to the workspace are found; forwards bind `127.0.0.1`, and they outlive detaching so a long-running session stays reachable.
+
 ### Handing a session to another machine
 
 Start something on your laptop, then move it — workspace, uncommitted work, and the agent's conversation — to a machine that won't go to sleep:

{luv_cli-0.4.0 → luv_cli-0.5.0}/docs/configuration.md

@@ -109,6 +109,30 @@ or `ssh_opts` may be set here and takes precedence over the `remote.*` value of
 the same name. This is what makes `-s otherbox` usable: without it, one global
 key would be wrong for every host but the default.
 
+### `ports`
+
+*object.* Port forwarding. Servers an agent starts on a remote host are
+detected and tunnelled to this machine — see
+[remote-sessions.md](remote-sessions.md#reaching-servers-the-agent-started).
+Every key is optional:
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `auto` | `true` | Forward the session you are attached to, as servers come and go. `false` leaves everything to `luv ports`. |
+| `interval` | `10` | Seconds between re-checks while attached. Minimum 2. |
+| `bind` | `"127.0.0.1"` | Local address the forwards listen on. `"0.0.0.0"` would publish the agent's dev server to your whole network. |
+| `min` | `1024` | Ports below this are ignored; a dev server is not on 80. |
+| `ignore` | `[]` | Specific ports never to forward. |
+| `max_per_session` | `12` | Cap on forwards per session, so one stack cannot eat the local port space. |
+
+```bash
+luv config set ports.interval 5
+luv config set ports.ignore '[5432, 6379]'
+luv config set ports.auto false
+```
+
+Unlike `remote.*`, these are global — there is no `remote.hosts.<name>.ports`.
+
 ## Resolution order
 
 **Host:** `-s HOST` → `remote.host`. If neither, luv runs locally.

{luv_cli-0.4.0 → luv_cli-0.5.0}/docs/remote-sessions.md

@@ -256,6 +256,85 @@ luv -i ~/.ssh/other_key myrepo      # use a different key this once
 Detach from a session with `Ctrl-b d` (tmux's default prefix). The agent keeps
 running.
 
+## Reaching servers the agent started
+
+An agent working on the remote starts servers there — a dev server, a compose
+stack, a database. luv finds them and tunnels them to this machine, on the same
+port number wherever it is free, so the URL the agent prints in its own output
+is the URL that works here.
+
+**The session you are attached to is forwarded automatically.** It is re-checked
+every few seconds, so a server started ten minutes into a session is reachable
+shortly after it comes up, without running anything. When a forward appears the
+session says so on its tmux status line:
+
+```
+luv: localhost:3000 → dashboard, localhost:8080 → server
+```
+
+The ports are also set on the tmux session as `@luv_ports`, if you would rather
+have them permanently in your own `status-right`.
+
+**Everything else is opted in by name.** A busy host carries dozens of sessions
+and they should not all get a piece of this machine's port space uninvited:
+
+```bash
+luv ls                          # PORTS column: what was detected, forwarded or not
+luv ports                       # detail view; refreshes what is already forwarded
+luv ports myrepo 42             # forward this session's ports
+luv ports myrepo 42 --watch     # ...and keep it up to date, printing each change
+luv ports --off myrepo 42       # drop them again
+luv ports --off                 # drop everything
+```
+
+```
+HOST  WORKSPACE      REMOTE  LOCAL  URL                    SERVICE    STATE
+box   myrepo-box-42    3000   3001  http://localhost:3001  dashboard  up
+box   myrepo-box-42    5173   5173  http://localhost:5173  vite       up
+box   other-box-17     5432   5432  -                      postgres   detected
+```
+
+Forwards outlive detaching — the session is still running and `localhost:3000`
+should keep working — so `luv ports myrepo 42` is also how a long-running
+session stays reachable after you close the window.
+
+`REMOTE` and `LOCAL` differ when the local number was already taken, by another
+session or by something of your own; luv walks up from the remote number and
+remembers what it chose, so the URL stays put across runs.
+
+### What gets found
+
+Two sources, because neither sees everything:
+
+- **Processes under the session's tmux pane.** A server the agent started
+  itself — `npm run dev`, `python -m http.server` — is a descendant of the pane,
+  which is what ties the port to a session. Only your own processes are visible
+  this way, so other people's services on a shared box never appear.
+- **Docker Compose stacks belonging to the workspace.** A published port is held
+  by `docker-proxy` rather than by anything under the pane, so the Compose
+  project label answers instead. Both the project luv starts (`luv-<workspace>`)
+  and the one an agent gets by running `docker compose up` itself (named after
+  the workspace folder) count as the workspace's.
+
+A port that is only *exposed* to the Compose network — `9009/tcp` with no host
+mapping — has nothing on the host to point a tunnel at and is not offered. Add a
+`ports:` entry to the compose file if you want it.
+
+Forwards bind `127.0.0.1` on this machine, so nothing is republished to your
+network. See [`ports.*`](configuration.md#ports) to change the interval, the
+bind address, or which ports are skipped, and `ports.auto` to turn the automatic
+half off entirely.
+
+### When it doesn't work
+
+- **Nothing detected, and the host is otherwise fine.** The host needs a luv new
+  enough to know `luv --listening`; an older one reports nothing rather than
+  failing. Upgrade luv there.
+- **`warning: <host> refuses port forwarding`.** That host's `sshd_config` has
+  `AllowTcpForwarding no`.
+- **A forward that stopped working.** The watcher logs to `~/.luv/ports.log`; it
+  cannot print while a full-screen agent UI owns the terminal.
+
 ## Handing a session to another machine
 
 `luv handover` relocates a running workspace. The usual direction is laptop →

{luv_cli-0.4.0 → luv_cli-0.5.0}/docs/sessions.md

@@ -42,7 +42,10 @@ the session (which luv does as soon as the clone lands) breaks nothing.
       "pr_number": 42,
       "pr_url": "https://github.com/exosphere/myrepo/pull/42",
       "pr_state": "OPEN",
-      "pr_checked": 1753408899
+      "pr_checked": 1753408899,
+      "ports": [3000, 5173],
+      "forwards": [{"remote": 3000, "local": 3001, "label": "dashboard"}],
+      "ports_checked": 1753408899
     }
   ]
 }
@@ -65,6 +68,9 @@ the session (which luv does as soon as the clone lands) breaks nothing.
 | `pr_checked` | Unix time GitHub was last asked about it |
 | `pr_hint` | PR number known at dispatch (`-l` / `-pr` only); absent otherwise. Set even when the folder isn't yet known, which is always the case for `-l` |
 | `adopted` | Present when this machine found the session rather than starting it |
+| `ports` | Ports the session was last seen listening on, on its own host |
+| `forwards` | Live tunnels to this machine: `remote` port, the `local` one it landed on, and the service `label`. Persisted so a URL stays put across runs, and so a forward survives detaching |
+| `ports_checked` | Unix time the forwards were last brought in line |
 
 `attached`, `activity`, and `live` are recomputed on every reconcile and are
 deliberately **not** written back to the file.