[kevin-orellana]

Human readable section

Problem. The Linux network guide leaves local service access and process identity unclear. It also implies that direct mode always bypasses the gateway.

Solution. Explain both existing modes, including local sockets, the operator identity that services see, and retained proxy variables.

Trade-off. Direct mode retains its broader access. This clarification adds no isolation mechanism.

Description

The author approved the documentation wording. Codex prepared this change and checked its claims against current source and existing tests.
Configuration, runtime code, and defaults stay the same.

Related Issues

Related to #47. Complements #196, which updates the operator reference pages.

Type of Change

Documentation update

Testing

• The all-features workspace build passed on ARM64 Linux.
• EXPERIMENTAL_LINUX_SUPPORT=TRUE cargo test --workspace --locked --all-features -- --show-output passed: 4,595 reported passes and 17 ignored tests across 140 suites.
• The Linux output checker accepted two omissions: the credential-daemon fixture and the alias-read assertion. The alias-write assertions ran.
• The prose checker, 16 relative links and anchors, and git diff --check passed.
• Independent review verified the wording against the namespace, gateway, filesystem, and identity controls.

The first test attempt omitted the Linux opt-in setting. The corrected run above passed.

• I ran the relevant suites (just check, or cargo test --workspace --all-features)
• If I touched Rust, I ran cargo fmt --all and cargo clippy --workspace --all-targets --all-features -- -D warnings (Not applicable: no Rust changed.)

Checklist

• I have read the CONTRIBUTING document
• I have reviewed and understand every line of code in this PR, including any generated by AI tools, and I can explain why it works (Documentation only; Codex checked the final wording against source.)
• My change is focused and reasonably small; I have split unrelated work into separate PRs
• I have added any necessary tests that prove my fix is effective or my feature works (No new tests were needed for this documentation clarification.)
• I have updated the documentation accordingly
• My changes generate no new warnings (The build reported the documented vendored shell warnings.)

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[github-actions]

Assessment: Comment

I checked each Linux network claim against the source at fae5791. One sentence about reaching local HTTP services through the gateway is wrong for the common clients (see the inline comment). The other claims match the code.

Checks that held

• Socket filter in both modes: SyscallPolicy::for_config ignores the network mode, and socket_rules permits only AF_UNIX and AF_INET.
• Direct mode joins the surrounding OS namespace: Network::AllowAll leads to enter_namespaces(join_host_network). No Landlock network or scope restriction exists, so loopback listeners and abstract Unix sockets are reachable.
• Proxy variables in direct mode: compose sets them for every spec. The gateway binds 127.0.0.1 in the trusted process's namespace, so a direct-mode client can still reach it.
• The agent refuses a network table, and contain_egress defaults to true: pinned in record/config/mod.rs and process.rs tests.
• Gateway mode cannot reach loopback directly: it uses a private namespace, and only the relay endpoints are served.
• Pathname sockets and directory grants: consistent with the mount view. The kernel does not apply read-only mount checks to sockets.
• Terminology: "surrounding OS" and "the box's trusted process" match docs/design/terminology.md.

The direct-mode wording is a clear improvement over the old "bypasses the gateway" statement.

[github-actions]

Assessment: Comment

I re-reviewed at e02a04e. The loopback paragraph now matches the code: NO_PROXY exempts 127.0.0.1,localhost, Shell and Monty refuse loopback URLs, and only a request sent to the gateway explicitly gets a policy decision. One small accuracy follow-up is inline (Shell/Monty also refuse private and link-local literals). Nothing blocks the merge.

Checks that held at this commit

• New loopback paragraph: matches LOOPBACK_EXEMPTION (run/contain/boundary.rs) and the Shell's check_url_safe tests.
• Unchanged since the last review: the socket filter (Unix and IPv4 only in both modes), direct mode joining the surrounding OS namespace, proxy variables in direct mode, the agent refusing a network table, pathname sockets under directory grants, and the operator-identity paragraph.
• New Terms rows: abstract sockets follow the network namespace, and pathname sockets follow filesystem visibility. Both are correct, and both #terms links resolve.

The loopback correction is clear and links to the page that owns the proxy-variable facts.

[github-actions]

Assessment: Approve

I re-reviewed at 0da4fca. The only change since e02a04e is line 137. It now says Shell curl and Monty fetch() refuse loopback, private, and link-local literals, which matches is_ip_blocked in crates/shell/src/vfs_kernel.rs and the wording in egress.md § How traffic reaches the gateway. I have no open findings.

Checks that held at this commit

• Built-in client refusals: line 137 matches the Shell's is_ip_blocked (loopback, RFC 1918, link-local/IMDS) and egress.md.
• Loopback and gateway paragraph: unchanged since e02a04e. It still matches LOOPBACK_EXEMPTION and the check_url_safe tests.
• Unchanged and still correct: the socket filter (Unix and IPv4 only in both modes), direct mode joining the surrounding OS namespace, proxy variables in direct mode, the agent refusing a network table, pathname sockets under directory grants, the operator-identity paragraph, and the two Terms rows.