@solcreek/dew 0.7.52 → 0.7.54

package/README.md

@@ -83,23 +83,65 @@ port = 6379
 [[service]]
 name = "mailpit"
 image = "axllent/mailpit:latest"
-port = 8025
+port = 8025                      # primary port (health-gated + forwarded)
+ports = ["1025"]                 # extra host forwards: "PORT" or "HOST:CONTAINER"
 ```
 
 `dew up` then boots the project and its services in one VM; containers use
-the VM network, so the dev server reaches them on `localhost`.
+the VM network, so the dev server reaches them on `localhost`. A service that
+exposes more than one port (mailpit's SMTP `1025` alongside its web UI `8025`)
+lists the extras in `ports` — each `"PORT"` (host = container) or
+`"HOST:CONTAINER"` to remap the host side.
 
 `--services-only` (alias `--no-dev`) boots just the services — handy when
 the app itself runs on the host and only its backing services live in dew.
 This is the docker-compose-shaped path: several arbitrary OCI images,
 health-gated and port-forwarded, in one microVM with no container daemon.
 
-To reach a service running on the **macOS host** (e.g. a websocket gateway
-in the VM calling back to a host RPC), use the hostname `host.internal`
-(alias `host.dew.internal`) — dew's equivalent of `host.docker.internal`.
-It resolves to the VM's NAT gateway in both the guest and its containers,
-so you never hardcode the `192.168.64.x` gateway IP. The host service must
-bind `0.0.0.0` (not `127.0.0.1`) to be reachable from the VM.
+### Reach the macOS host from the VM
+
+A service in the VM often has to call back to a process on your Mac — a
+websocket gateway hitting a host RPC, an app talking to a database you run
+natively. dew gives you two host aliases so you never hardcode the
+`192.168.64.x` gateway IP. Both resolve inside the guest **and** inside
+`--net=host` containers, so a `dew.toml` service reaches the host the same
+way the guest does.
+
+| Alias | Reaches a host service bound to | Path | Use when |
+|---|---|---|---|
+| `host.internal` (alias `host.dew.internal`) | `0.0.0.0` (all interfaces) | VZ NAT gateway | the host service already listens on all interfaces |
+| `host.lo.internal` | **`127.0.0.1`** (the dev default) | vsock → host loopback | the service is loopback-only, or you want to dodge the macOS 26 VZ NAT regression |
+
+**`host.internal` — the NAT-gateway alias**, dew's equivalent of
+`host.docker.internal`. The host service must bind `0.0.0.0`; a `127.0.0.1`
+bind stays unreachable (same caveat as docker's alias):
+
+```bash
+# bind the host service to 0.0.0.0 (a 127.0.0.1 bind is unreachable):
+python3 -m http.server 50051 --bind 0.0.0.0
+# then from the VM (or a --net=host container): curl http://host.internal:50051
+```
+
+**`host.lo.internal` — a vsock tunnel straight to the host's loopback.**
+This is the one for the common dev case where the host service is bound to
+`127.0.0.1` (a Rails RPC, a local Postgres, etc.). Declare the ports to
+expose; dew forwards each over vsock to the host's `127.0.0.1` — no
+`0.0.0.0` rebind, and because it never touches the network stack it is
+**immune to the macOS 26 VZ NAT regression**:
+
+```bash
+dew up --expose-host 50051
+# in the VM: host.lo.internal:50051 → the host's 127.0.0.1:50051
+```
+
+```toml
+# or, in dew.toml:
+[host]
+expose = [50051]
+```
+
+dew only ever dials its own loopback on a port you declared, so the VM can't
+reach anything else on the host.
 
 ### Run any container
 
@@ -240,6 +282,7 @@ Dev:
   dew up --with postgres,redis   Dev with built-in services
   dew up --init                  Write a starter dew.toml
   dew up --services-only         Boot services without a dev server
+  dew up --expose-host PORT      Reach a host 127.0.0.1 service in the VM
   dew down                       Stop dev environment
 
 Share:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solcreek/dew",
-  "version": "0.7.52",
+  "version": "0.7.54",
   "description": "Sandboxed Linux compute, agent-native and human-friendly.",
   "license": "MIT",
   "repository": {