@hahahhh/sshx 0.0.2-rc.1 → 0.0.3-rc.0

package/README.md

@@ -2,11 +2,12 @@
 
 > Transparent SSH enhancement — add remote-to-local commands, auto port forwarding, and local domains to your SSH workflow. Zero side effects when you don't need them.
 
-**sshx** is a drop-in wrapper around OpenSSH. Wrap it as `alias ssh=sshx` and your existing SSH workflow works exactly as before — every flag, config, and connection passes through verbatim. But when you connect to a host with sshx-aware features enabled, you unlock a persistent, shared remote server that gives you:
+**sshx** is a drop-in wrapper around OpenSSH. Wrap it as `alias ssh=sshx` and your existing SSH workflow works exactly as before — every flag, config, and connection passes through verbatim. But when you connect to a host (or Docker container) with sshx-aware features enabled, you unlock a persistent, shared remote server that gives you:
 
 - 🔄 **Reverse command bridge** — run `sshx local <cmd>` *on the remote* to execute commands on your local machine, with stdout, stderr, exit code, and stdin all propagated.
 - 🔌 **Automatic port forwarding** — remote loopback listeners (e.g., a dev server on `localhost:8080`) are automatically detected and forwarded to your local machine.
 - 🌐 **Local domain binding** — access forwarded ports as `<host>.<your-user>.sshx:<port>` in your local browser, no manual `-L` flags needed.
+- 🐳 **Docker container support** — target running containers by name or ID: `sshx my-container`. Command bridge support works inside containers via `docker exec`.
 
 ## Why sshx?
 
@@ -31,6 +32,16 @@ sshx is designed to be **safe to alias**. Hosts without sshx configuration are u
 - `~/.ssh/config` resolution is handled by OpenSSH — no reimplementation.
 - Bypass with `sshx --no-wrap` or `SSHX_DISABLE=1` at any time.
 
+### 🐳 Docker Container Target
+
+When the target doesn't match any SSH host, sshx falls back to resolving it as a running Docker container:
+
+- `sshx <container-name>` — opens a shell in the container via `docker exec`.
+- `sshx <container-id-prefix>` — matches by container ID prefix.
+- Explicit SSH targets (`user@host`, IP addresses, hostnames with dots/colons) are never treated as Docker containers.
+- Command bridge support works inside containers.
+- Requires `docker` CLI available on the local machine — gracefully falls back to SSH if Docker isn't found or the container isn't running.
+
 ### 🔄 Remote-to-Local Command Bridge
 
 Run commands on your **local machine** from inside an SSH session:
@@ -51,15 +62,15 @@ sshx local pbcopy < /tmp/some-data
 When a process on the remote starts listening on `127.0.0.1` (e.g., `npm run dev` on port 3000), sshx detects it and:
 
 1. Broadcasts the port to the local daemon.
-2. Creates a shared TCP forward over SSH.
-3. Binds the SSH target domain, e.g. `debian.<your-user>.sshx`.
+2. Assigns the SSH target its own loopback IP.
+3. Exposes a TCP proxy at the target domain, e.g. `debian.<your-user>.sshx:3000`.
 
-sshx first tries to use the same local port as the remote listener. If that local port is already occupied, it automatically tries the next port (`+1`) until it finds a free one. Run `sshx forward` to see the active mapping.
+The URL port is the remote port. sshx does not bind `127.0.0.1:<port>`; it binds the target's private loopback IP instead, so `debian.<your-user>.sshx:8080` and `ubuntu.<your-user>.sshx:8080` can point at different hosts at the same time. Run `sshx forward` to see the active mappings.
 
 ### 🌐 Local Domains (macOS, Linux)
 
-- A local DNS responder on `127.0.0.1:53` resolves `*.sshx` names dynamically.
-- The domain resolves to localhost; the URL port selects the forwarded local listener.
+- A local DNS responder on `127.0.0.1:53` resolves active target names dynamically.
+- Each target domain resolves to a private loopback IP; the URL port selects the remote listener.
 - On macOS, `/etc/resolver/<suffix>` is configured once (with `sudo` when needed).
 - All terminals on the same host share one DNS resolver and forwarding daemon.
 
@@ -128,6 +139,21 @@ sshx -p 2222 user@my-server hostname
 
 All existing SSH options work — `-F`, `-o`, `-J`, `ProxyJump`, etc. are handled by OpenSSH.
 
+### 1a. Connect to a Docker container
+
+```sh
+# By container name
+sshx my-dev-container
+
+# By container ID prefix
+sshx 4fa8bc
+
+# Run a command directly
+sshx my-container cat /etc/os-release
+```
+
+sshx detects that the target isn't an SSH host and automatically uses `docker exec`. The command bridge and other features work exactly the same inside containers.
+
 ### 2. Try the command bridge
 
 Inside your SSH session on the remote:
@@ -151,13 +177,12 @@ On your **local** machine, open:
 http://my-server.<your-user>.sshx:8080
 ```
 
-No `-L` flags, no manual forwarding.
-
-If local port `8080` is already occupied, sshx will try `8081`, then `8082`, and so on. Check the chosen port with:
+No `-L` flags, no manual forwarding. Since each target gets its own loopback IP, another target can expose its own `8080` at the same time:
 
 ```sh
 sshx forward
-# 8080 -> my-server:8080
+# http://my-server.<your-user>.sshx:8080 -> my-server:8080
+# http://other-server.<your-user>.sshx:8080 -> other-server:8080
 ```
 
 ---
@@ -175,17 +200,9 @@ features:
   # Remote-to-local command bridge (`sshx local <cmd>` on the remote)
   commandBridge: true
 
-  ports:
-    # Auto-detect loopback TCP listeners on the remote and forward them.
-    auto: true
-    # Future: also detect 0.0.0.0 listeners.
-    # bindAll: false
-
-  domains:
-    # Enable local domain binding (<host>.<user>.sshx:<port>).
-    enabled: true
-    # Custom domain suffix. Default: <local-user>.sshx
-    suffix: user.sshx
+  # Auto-detect remote loopback TCP listeners and expose them via
+  # <host>.<user>.sshx:<remote-port>.
+  autoForward: true
 
 commands:
   # Commands blocked from bridge execution.
@@ -216,7 +233,7 @@ commands:
 4. **Forwarding**: Detected ports are forwarded through a single shared local daemon using `ssh -W`.
 5. **Domains**: The local DNS responder maps `<target>.<suffix>` → localhost. The browser's URL port selects the local forwarded port.
 
-When `sshx` is invoked for a **non-matching host** (no sshx config, or host not in scope), it `exec`s the real `ssh` directly — no daemon, no installation, no overhead.
+When `sshx` is invoked for a **non-matching host** (no sshx config, or host not in scope), it first checks if the target resolves to a running Docker container. If neither SSH nor Docker matches, it `exec`s the real `ssh` directly — no daemon, no installation, no overhead.
 
 ---
 
@@ -225,20 +242,22 @@ When `sshx` is invoked for a **non-matching host** (no sshx config, or host not
 - `sshx --no-wrap ...` — skip all sshx behavior and call raw `ssh`.
 - `SSHX_DISABLE=1 sshx ...` — same as `--no-wrap`, useful in scripts.
 - `sshx local ...` on a **client** (not inside a remote session) — errors immediately with a clear message. `local` is globally reserved.
+- Docker containers that aren't running or can't be reached are pure passthrough — sshx falls back to raw `ssh` with no side effects.
 - Unmatched hosts are pure passthrough — no files created, no processes started.
 
 ---
 
 ## Platform Support
 
-| Platform | Client | Server |
-|---|---|---|
-| macOS | ✅ | — |
-| Linux | ✅ | ✅ |
-| Windows | 🔜 | — |
+| Platform | Client | Server | Docker Client |
+|---|---|---|---|
+| macOS | ✅ | — | ✅ |
+| Linux | ✅ | ✅ | ✅ |
+| Windows | 🔜 | — | 🔜 |
 
 - **Client**: macOS and Linux are fully supported.
 - **Server**: Linux is required for the remote sshx server (uses `/proc/net/tcp*` for port detection).
+- **Docker Client**: macOS and Linux — targets any running Docker container via `docker exec`.
 
 ---
 
@@ -248,7 +267,7 @@ When `sshx` is invoked for a **non-matching host** (no sshx config, or host not
 sshx/
 ├── cmd/sshx/          # Main entry point
 ├── internal/
-│   ├── cli/           # CLI parsing, host detection
+│   ├── cli/           # CLI parsing, host detection, Docker container resolution
 │   ├── sshcompat/     # SSH argument compatibility
 │   ├── config/        # YAML configuration
 │   ├── protocol/      # Client-server wire protocol

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hahahhh/sshx",
-  "version": "0.0.2-rc.1",
+  "version": "0.0.3-rc.0",
   "type": "module",
   "description": "Transparent SSH enhancement wrapper for OpenSSH",
   "repository": {