Add --publish: the one ingress control

Everything else in the file gates egress, which left an everyday request unanswered: the
agent starts a dev server inside the sandbox and a human wants to look at it. This puts a
listener on the host that forwards into the container, so a browser, curl or an API
tester reaches the server the sandboxed process runs.

`--publish [ADDR:]HOST:CONTAINER`, config `publish` and AISB_PUBLISH, repeatable, with the
cost named in the flag: it is ingress, so whatever that server serves is reachable from
the address it binds. The default address is 127.0.0.1 because a bare podman -p binds
every interface (measured) -- a port committed in a repo config must not quietly be a port
on the LAN. publish_addr changes the default machine-wide; a spec with a non-loopback
address warns on every run. The grammar is smaller than podman's on purpose: one port per
entry, no ranges, no /udp, no `*` -- this list is reviewed line by line, and typing
0.0.0.0 is the whole warning. An address means three parts, so `127.0.0.1:8000` is refused
rather than guessed. No -p alias: that flag belongs to the harness (claude -p prints).

Fail closed, as elsewhere: --net none cannot forward a port and podman discards the
mapping while starting the container anyway, so "it ran" would mean "nothing is
listening"; a host port already in use is named before the container starts, not after a
build; pick_port() will not hand the gate a port this run publishes. The container is
labelled with the ports it was given, and doctor reports them.

Inside, publish_rules() accepts tcp on the published ports in the input chain and never
the output one. Measured (docs/networking.md): pasta delivers the connection over
loopback, so that rule counts 0 packets on the reference host; it is there for a host or a
bridge network that delivers on the interface, and so that `nft list table inet aisb`
answers "what can reach this container". The ports are validated again inside the
entrypoint, because a ruleset is not somewhere to splice an unvalidated string. And the
measurement that makes a configured preview look broken: a server bound to 127.0.0.1
inside answers inside and refuses the published port outside, so dev servers must bind
0.0.0.0 -- both skills say so in the change that writes the port.

Tests. Unit: the grammar and every port list that looks right and is not, config/env/flag
precedence and dedup, the canonical spec in --print-policy, the `# ingress:` header, the
flags reaching the invocation before the image, egress enforcement byte-identical with a
port open, which chain the rule lands in and that a non-numeric port never reaches nft as
code. e2e (tests/e2e/13_publish.sh): one real container with enforce=nft where the host
gets its 200 and the same run still refuses a domain outside the allowlist at 403, the
server runs as uid 1000 with no capabilities so it cannot widen its own port, and the host
listener is gone when the container exits.

LLM-Generated: true

docs/networking.md

@@ -50,6 +50,43 @@ domains you allowlisted, resolved by the gate itself. CDNs, SNI and CONNECT-time
 filtering all work because squid terminates the CONNECT request and resolves the
 name itself.
 
+## Publishing a port (ingress)
+
+`--publish` is the one control that runs the other way: podman/pasta puts a listener on the
+host and forwards what arrives into the container, so a client on the host can reach a server
+the sandboxed process listens on. Nothing about the egress model changes -- the same run that
+answers your browser still refuses every domain outside the allowlist
+(`tests/e2e/13_publish.sh` asserts exactly that, in one container).
+
+Binding and parsing decisions, and why:
+
+| decision | reason |
+|---|---|
+| default bind address `127.0.0.1` | measured: a bare `-p 8000:8000` binds `*:8000`, i.e. every interface. A port in a committed config must not quietly be a port on the LAN. `publish_addr` or an explicit `addr:` changes it, and a non-loopback address warns. |
+| one port per entry, no ranges, no `/udp` | this list is a policy a human reviews; a range is a line nobody reads. |
+| `*` ("every interface") is refused; `0.0.0.0` is accepted | podman's shorthand hides what it opens. Making someone type the address is the whole warning. |
+| an address requires three parts | `0.0.0.0:8000` means two different things in podman's grammar. Refusing it with a message beats guessing. |
+| `--net none` + `--publish` refuses | measured: podman prints one line about discarding the mapping and starts the container regardless. "It ran" with nothing listening is the worst outcome here. |
+| a busy host port refuses the run | measured before the container starts, because podman's own error arrives after any build. |
+| the ruleset accepts the published ports on the `input` hook | see below: it changes nothing on the reference host, and it is the audit trail on every host. |
+
+Where the packet actually arrives was the interesting measurement. The `input` chain is
+`policy drop`, so a port forward looks doomed from the reading of it -- and it is not:
+
+| Probe | Result | Consequence |
+|---|---|---|
+| `--net allow --publish H:8000`, server on `0.0.0.0`, `curl` from the host | **200**, with `enforce=nft` in the same run | the existing ruleset does not block a published port |
+| `nft -a list chain inet aisb input` while that port serves traffic | `aisb-publish` counter: **0 packets** | pasta forwards the connection into the namespace over **loopback**, so `iifname "lo" accept` carries it |
+| server bound to `127.0.0.1` **inside**, port published | host: connection refused; inside: 200 | pasta delivers to the container's own address, not to its loopback → dev servers must bind `0.0.0.0` |
+| `ss -ltnp` on the host while published | `LISTEN 127.0.0.1:H ... pasta.avx2` | the listener is pasta's, on loopback, and it is gone when the container exits |
+| container's own view of its interface | `wlp4s0` with the **host's** LAN address | pasta mirrors the host address into the namespace, which is why a *remote* host cannot reach the published port: only pasta's own socket on the host accepts, and it accepts on the address we named |
+
+So `publish_rules()` in the entrypoint is deliberately not what makes publishing work here.
+It is there because (a) a different host, or a bridge network, can deliver the packet on the
+container's own interface, where `policy drop` would leave a port that looks configured and
+answers nothing, and (b) `nft list table inet aisb` should answer "what can reach this
+container" instead of leaving that question to a flag on the host.
+
 ## Measurements
 
 | Probe | Result | Consequence |
@@ -60,6 +97,8 @@ name itself.
 | `--network=host` in a rootless container | works, has internet | makes the host-loopback gate possible |
 | `--network=pasta` (default), egress | works | pasta is a plain internet tap, no filtering |
 | container → host `127.0.0.1` via `--map-host-loopback,100.64.0.1` | **works** | the gate address |
+| host → container via `-p 127.0.0.1:H:C`, `--net allow`, ruleset installed | **works**; the `input` hook sees 0 packets for it | ingress arrives on `lo` — see "Publishing a port" above |
+| `-p H:C` with no address | binds `*:H` on the host | the default bind address in `ai-sandbox` is `127.0.0.1`, not podman's |
 | `--map-host-loopback,127.0.0.1` | rejected by passt (`Invalid address to remap to host`) | the magic address must not itself be loopback |
 | `--network=pasta:--map-gw` | works (the gateway address already maps to the host by default) | `--map-host-loopback` chosen for explicitness |
 | squid as root with `--cap-drop=ALL` | `setgid: (1) Operation not permitted`, gate dies | run the gate as `proxy` from the start |

docs/recipes.md

@@ -159,6 +159,53 @@ pi --allow registry-1.docker.io --allow auth.docker.io --allow production.cloudf
 pi --allow aipi.reeseapps.com --allow 10.20.0.5:5432
 ```
 
+## Ports: two directions, two answers
+
+**Outbound — a service on your machine** (dev postgres, redis, a mock API, a local model
+server). That is egress, so it is an allow entry, not a flag. `100.64.0.1` is the address that
+stands for the host's loopback inside the container:
+
+```ini
+# .ai-sandbox/allow
+100.64.0.1:5432            # postgres from `docker compose up db`, on the host
+
+# .ai-sandbox/config -- point the app at the mapped address (no secret is a URL like this)
+env = DATABASE_URL=postgresql://dev@100.64.0.1:5432/app_dev
+# HTTP on anything but 80/443/8443 also has to skip the proxy, or the gate is asked for it:
+env = NO_PROXY=100.64.0.1,localhost,127.0.0.1,::1
+env = no_proxy=100.64.0.1,localhost,127.0.0.1,::1
+```
+
+**Inbound — a server the sandbox runs, to be seen from the host.** Publish it. Bound to
+loopback by default, so `http://127.0.0.1:8000` in your browser works and nothing on your
+network can reach it:
+
+```bash
+# the one-off preview: the agent runs the server, you look at it
+ai-sandbox --allow aipi.reeseapps.com --publish 8000 -- npm run dev -- --host 0.0.0.0
+
+# a host port that is free, a different container port
+ai-sandbox --publish 18080:3000 -- npm run dev -- --host 0.0.0.0
+
+# from a project's own config, so `ai-sandbox` alone is the invocation
+#   .ai-sandbox/config:  publish = 8000
+#                        publish = 18080:3000
+```
+
+Four things worth knowing before it looks broken (all measured, all in
+[`networking.md`](networking.md)):
+
+* the server must listen on `0.0.0.0` **inside** — `--host 0.0.0.0`, `uvicorn --host
+  0.0.0.0`, `runserver 0.0.0.0:8000`. A `127.0.0.1`-only server answers inside and refuses the
+  published port.
+* egress is unaffected. A published port is ingress: the run keeps its allowlist, its
+  unprivileged uid and its ruleset, and the ruleset names the ports it opened.
+* `--net none` refuses to publish rather than start with nothing listening; a host port that
+  is already taken is named before the container starts, not after the build.
+* a non-loopback bind (`publish = 0.0.0.0:18080:3000`) means exactly what it says: anything that
+  can route to this machine can reach that server. It warns, and it does not belong in a
+  committed config — that file outlives the run that justified it.
+
 ## Git
 
 ```bash

docs/threat-model.md

@@ -107,6 +107,21 @@ Be honest about these, and design your work accordingly.
    *in the sandbox* by default; `--validate-in host` hands that judgement to you and
    warns on every run.
 
+14. **A published port is a door you opened.** `--publish` (and `publish` in a config
+    file) puts a listener on the host that forwards into the container, so a client
+    outside can reach a server the agent is running. That is the feature — preview a dev
+    server, poke a local API — and it is also the whole risk: whatever that server serves,
+    and whatever it accepts, is reachable from the address it is bound to, by things other
+    than you. The default binds `127.0.0.1`, because a bare podman `-p` binds every
+    interface (measured); a spec with a non-loopback address warns on every run and should
+    not be committed. Egress stays enforced either way: a published port is ingress, not a
+    loosened allowlist, and the same run that answers your browser still refuses a domain
+    outside it (`tests/e2e/13_publish.sh`). The agent inside cannot widen its own port or
+    open a new one — the mapping is decided on the host before the container starts and the
+    command runs with no capabilities. What it *can* do is serve whatever it likes on a port
+    you asked for. Publish the port of the server you meant to preview, and treat that port
+    as published content for as long as the run lasts.
+
 ## Residual risk rating
 
 *Accidental destruction and ambient credential leakage: largely eliminated.*